# Why ServiceStack
Source: https://docs.servicestack.net/why-servicestack

Developed in the modern age, ServiceStack provides an alternate, cleaner POCO-driven way of creating web services.

<lite-youtube class="w-full mx-4 my-4" width="560" height="315" videoid="Vae0ALalIP0" style="background-image: url('https://img.youtube.com/vi/Vae0ALalIP0/maxresdefault.jpg')"></lite-youtube>

### Features Overview

ServiceStack is a simple, fast, versatile and highly-productive full-featured [Web](https://razor.netcore.io) and 
[Web Services](/web-services) Framework that's 
thoughtfully-architected to [reduce artificial complexity](/autoquery/why-not-odata#why-not-complexity) and promote 
[remote services best-practices](/advantages-of-message-based-web-services) 
with a [message-based design](/what-is-a-message-based-web-service) 
that allows for maximum re-use that can leverage an integrated 
[Service Gateway](/service-gateway) 
for the creation of loosely-coupled 
[Modularized Service](/modularizing-services) Architectures.
ServiceStack Services are consumable via an array of built-in fast data formats (inc. 
[JSON](https://github.com/ServiceStack/ServiceStack/tree/main/ServiceStack.Text/src/ServiceStack.Text), 
XML,
[CSV](/csv-format),
[JSONL](/jsonl-format),
[JSV](/jsv-format), 
[ProtoBuf](/protobuf-format) and 
[MsgPack](/messagepack-format)) 
as well as XSD/WSDL for [SOAP endpoints](/soap-support) and 
[Rabbit MQ](/rabbit-mq), 
[Redis MQ](/redis-mq),
[Azure Service Bus](/azure-service-bus-mq),
[Amazon SQS](/aws#sqsmqserver) and
[Background MQ](/background-mq),
MQ hosts. 

Its design and simplicity focus offers an unparalleled suite of productivity features that can be declaratively enabled 
without code, from creating fully queryable Web API's with just a single Typed Request DTO with
[Auto Query](/autoquery/) supporting 
[every major RDBMS](/ormlite/#ormlite-rdbms-providers) 
to the built-in support for
[Auto Batched Requests](/auto-batched-requests) 
or effortlessly enabling rich [HTTP Caching](/http-caching) and
[Encrypted Messaging](/auth/encrypted-messaging) 
for all your existing services via [Plugins](/plugins).

<img src="/img/pages/svg/servicify.svg" width="100%">

Your same Services also serve as the Controller in ServiceStack's [Smart Razor Views](https://razor.netcore.io/)
reducing the effort to serve both 
[Web and Single Page Apps](https://github.com/ServiceStackApps/LiveDemos) as well as 
[Rich Desktop and Mobile Clients](https://github.com/ServiceStackApps/HelloMobile) that are able to deliver instant interactive 
experiences using ServiceStack's real-time [Server Events](/server-events).

ServiceStack Services also maximize productivity for consumers providing an 
[instant end-to-end typed API without code-gen](/csharp-client) enabling
the most productive development experience for developing .NET to .NET Web Services.

### Benefits
 
- **Simplicity** - All features are centered around APIs that accept and return Typed DTOs
- **Speed** - Built for speed on high-performance components utilizing performance APIs available in each .NET runtime
- **Web Services Best Practices** - Adopts time-tested SOA Integration Patterns for APIs and client integrations
- **Message-based Services** - Model-driven, code-first, friction-free development
- **Native Clients** - Clean, end-to-end typed idiomatic APIs for most major platforms
- **Modern** - No XML config, IOC built-in, no code-gen, conventional defaults
- **Smart** - Infers greater intelligence from your strongly typed DTOs
- **Effortless Features** - Most features enhance your existing DTOs making them trivial to enable
- **Multi Platform** - Supports .NET 4.5 and .NET Core platforms for hosting on Windows, OSX, Linux
- **Multiple Hosts** - Run in Web, Console, native Windows/OSX Desktop Apps, Windows Services
- **Host Agnostic** - Services are decoupled from HTTP and can be hosted in MQ Services
- **Highly testable** - Typed, idiomatic client APIs enable succinct, intuitive Integration tests
- **Mature** - Stable with over 10+ years of development 
- **Preserve Investment** - modern libraries that are [Continuously Improved](/release-notes-history) (not abandoned or replaced)
- **Dependable** - Commercially supported and actively developed
- **Increasing Value** - ServiceStack's [ever-growing features](https://servicestack.net/features) adds more capabilities around your Services with each release


### Generate Instant Typed APIs from within all Major IDEs!

ServiceStack now [integrates with all Major IDE's](/add-servicestack-reference.html) used for creating the best native experiences 
on the most popular platforms to enable a highly productive dev workflow for consuming Web Services, making ServiceStack the ideal 
back-end choice for powering rich, native iPhone and iPad Apps on iOS with Swift, Mobile and Tablet Apps on the Android platform 
with Java, OSX Desktop Applications as well as targeting the most popular .NET PCL platforms including Xamarin.iOS, Xamarin.Android, 
Windows Store, WPF, WinForms and Silverlight: 

[![](./img/pages/servicestack-reference/ide-plugins-splash.png)](https://www.youtube.com/watch?v=JKsgrstNnYY)

#### [JetBrains Rider ServiceStack Plugin](https://www.youtube.com/watch?v=JKsgrstNnYY)

The **ServiceStack** Rider plugin is installable directly from JetBrains Marketplace and enables seamless integration with JetBrains Rider for easily generating C#, TypeScript, F# and VB.NET Typed APIs from just a remote ServiceStack Base URL.

#### [VS.NET integration with ServiceStackVS](/create-your-first-webservice#step-1-download-and-install-servicestackvs)

Providing instant Native Typed API's for 
[C#](/csharp-add-servicestack-reference.html), 
[TypeScript](/typescript-add-servicestack-reference.html),
[F#](/fsharp-add-servicestack-reference.html) and 
[VB.NET](/vbnet-add-servicestack-reference.html) 
directly in Visual Studio for the 
[most popular .NET platforms](https://github.com/ServiceStackApps/HelloMobile) including iOS and Android using 
[Xamarin.iOS](https://github.com/ServiceStackApps/HelloMobile#xamarinios-client) and 
[Xamarin.Android](https://github.com/ServiceStackApps/HelloMobile#xamarinandroid-client) on Windows.

#### [Xamarin Studio integration with ServiceStackXS](/csharp-add-servicestack-reference.html#xamarin-studio)

Providing [C# Native Types](/csharp-add-servicestack-reference.html) 
support for developing iOS and Android mobile Apps using 
[Xamarin.iOS](https://github.com/ServiceStackApps/HelloMobile#xamarinios-client) and 
[Xamarin.Android](https://github.com/ServiceStackApps/HelloMobile#xamarinandroid-client) with 
[Xamarin Studio](https://www.xamarin.com/studio) on OSX. The **ServiceStackXS** plugin also provides a rich web service 
development experience developing Client applications with 
[Mono Develop on Linux](/csharp-add-servicestack-reference.html#xamarin-studio-for-linux)

#### [Android Studio integration with ServiceStack Plugin](/java-add-servicestack-reference.html)

Providing [an instant Native Typed API in Java](/java-add-servicestack-reference.html) 
and [Kotlin](/kotlin-add-servicestack-reference.html)
including idiomatic Java Generic Service Clients supporting Sync and Async Requests by leveraging Android's AsyncTasks to enable the creation of services-rich and responsive native Java or Kotlin Mobile Apps on the Android platform - directly from within Android Studio!

#### [JetBrains IDEs integration with ServiceStack IDEA plugin](/java-add-servicestack-reference.html#install-servicestack-idea-from-the-plugin-repository)

The ServiceStack IDEA plugin is installable directly from IntelliJ's Plugin repository and enables seamless integration with IntelliJ Java Maven projects for generating a Typed API to quickly and effortlessly consume remote ServiceStack Web Services from pure cross-platform Java or Kotlin Clients.

#### [Eclipse integration with ServiceStackEclipse](https://github.com/ServiceStack/ServiceStack.Java/tree/master/src/ServiceStackEclipse#eclipse-integration-with-servicestack)

The unmatched productivity offered by [Java Add ServiceStack Reference](/java-add-servicestack-reference.html) is also available in the 
[ServiceStackEclipse IDE Plugin](https://github.com/ServiceStack/ServiceStack.Java/tree/master/src/ServiceStackEclipse#eclipse-integration-with-servicestack) that's installable 
from the [Eclipse MarketPlace](https://marketplace.eclipse.org/content/servicestackeclipse) to provide deep integration of Add ServiceStack Reference with Eclipse Java Maven Projects
enabling Java Developers to effortlessly Add and Update the references of their evolving remote ServiceStack Web Services.

#### [Simple command-line utilities for ServiceStack](/add-servicestack-reference.html#simple-command-line-utilities)

In addition to our growing list of supported IDE's, the [x dotnet tool](/dotnet-tool) allows VS Code and other cross-platform IDEs, build servers, shell scripts and other automated tasks to easily Add and Update ServiceStack References with a single command.

#### [Invoke ServiceStack APIs from the command-line](/post-command)

Easily inspect and invoke C# .NET Web APIs from the command-line with Post Command which allows you to both inspect and
call any ServiceStack API with just its name and a JS Object literal. API Responses returned in human-friendly markdown tables by default or 
optionally as JSON & raw HTTP.

## Simple Customer Database REST Services Example

This example is also available as a [stand-alone integration test](https://github.com/ServiceStack/ServiceStack/blob/master/tests/ServiceStack.WebHost.Endpoints.Tests/CustomerRestExample.cs):

```csharp
//Web Service Host Configuration
public class AppHost : AppSelfHostBase
{
    public AppHost() 
        : base("Customer REST Example", typeof(CustomerService).Assembly) {}

    public override void Configure(Container container)
    {
        //Register which RDBMS provider to use
        container.Register<IDbConnectionFactory>(c => 
            new OrmLiteConnectionFactory(":memory:", SqliteDialect.Provider));

        using (var db = container.Resolve<IDbConnectionFactory>().Open())
        {
            //Create the Customer POCO table if it doesn't already exist
            db.CreateTableIfNotExists<Customer>();
        }
    }
}

//Web Service DTOs
[Route("/customers", "GET")]
public class GetCustomers : IReturn<GetCustomersResponse> {}

public class GetCustomersResponse
{
    public List<Customer> Results { get; set; } 
}

[Route("/customers/{Id}", "GET")]
public class GetCustomer : IReturn<Customer>
{
    public int Id { get; set; }
}

[Route("/customers", "POST")]
public class CreateCustomer : IReturn<Customer>
{
    public string Name { get; set; }
}

[Route("/customers/{Id}", "PUT")]
public class UpdateCustomer : IReturn<Customer>
{
    public int Id { get; set; }

    public string Name { get; set; }
}

[Route("/customers/{Id}", "DELETE")]
public class DeleteCustomer : IReturnVoid
{
    public int Id { get; set; }
}

// POCO DB Model
public class Customer
{
    [AutoIncrement]
    public int Id { get; set; }

    public string Name { get; set; }
}

//Web Services Implementation
public class CustomerService : Service
{
    public object Get(GetCustomers request)
    {
        return new GetCustomersResponse { Results = Db.Select<Customer>() };
    }

    public object Get(GetCustomer request)
    {
        return Db.SingleById<Customer>(request.Id);
    }

    public object Post(CreateCustomer request)
    {
        var customer = new Customer { Name = request.Name };
        Db.Save(customer);
        return customer;
    }

    public object Put(UpdateCustomer request)
    {
        var customer = Db.SingleById<Customer>(request.Id);
        if (customer == null)
            throw HttpError.NotFound($"Customer '{request.Id}' does not exist");

        customer.Name = request.Name;
        Db.Update(customer);

        return customer;
    }

    public void Delete(DeleteCustomer request)
    {
        Db.DeleteById<Customer>(request.Id);
    }
}

```

### [Calling the above REST Service from any C#/.NET Client](/csharp-add-servicestack-reference.html)

No code-gen required, can re-use above Server DTOs:

```csharp
var client = new JsonApiClient(BaseUri);

//GET /customers
var all = client.Get(new GetCustomers());                         // Count = 0

//POST /customers
var customer = client.Post(new CreateCustomer { Name = "Foo" });

//GET /customer/1
customer = client.Get(new GetCustomer { Id = customer.Id });      // Name = Foo

//GET /customers
all = client.Get(new GetCustomers());                             // Count = 1

//PUT /customers/1
customer = client.Put(
    new UpdateCustomer { Id = customer.Id, Name = "Bar" });       // Name = Bar

//DELETE /customers/1
client.Delete(new DeleteCustomer { Id = customer.Id });

//GET /customers
all = client.Get(new GetCustomers());                             // Count = 0
```

Same code also works with [Android, iOS, Xamarin.Forms, UWP and WPF clients](https://github.com/ServiceStackApps/HelloMobile).

::: info
[F#](/fsharp-add-servicestack-reference.html) and 
[VB.NET](/vbnet-add-servicestack-reference.html) can re-use same 
[.NET Service Clients](/csharp-client.html) and DTOs
:::

### [Calling from TypeScript](/typescript-add-servicestack-reference.html#ideal-typed-message-based-api)

```ts
const client = new JsonServiceClient(baseUrl);
const { results } = await client.get(new GetCustomers());
```

### [Calling from Swift](/swift-add-servicestack-reference.html#jsonserviceclientswift)

```swift
let client = JsonServiceClient(baseUrl: BaseUri)

client.getAsync(GetCustomers())
    .then {
        let results = $0.results;
    }
```

### [Calling from Java](/java-add-servicestack-reference.html#jsonserviceclient-usage)

```java
JsonServiceClient client = new JsonServiceClient(BaseUri);

GetCustomersResponse response = client.get(new GetCustomers());
List<Customer> results = response.results; 
```

### [Calling from Kotlin](/kotlin-add-servicestack-reference.html#jsonserviceclient-usage)

```kotlin
val client = JsonServiceClient(BaseUri)

val response = client.get(GetCustomers())
val results = response.results
```

### Calling the from [Dart](/dart-add-servicestack-reference#example-usage)

```dart
var client = new JsonServiceClient(baseUri);
var response = await client.get(new GetCustomers());
```

### [Calling from jQuery using TypeScript Definitions](/typescript-add-servicestack-reference.html#typescript-interface-definitions)

```js
$.getJSON($.ss.createUrl("/customers", request), request, 
    function (r: dtos.GetCustomersResponse) {
    	alert(r.Results.length == 1);
    });
```

### Calling from jQuery

```js
$.getJSON(baseUri + "/customers", function(r) {
	alert(r.Results.length == 1);
});
```

That's all the application code required to create and consume a simple database-enabled REST Web Service!


### Define web services following Martin Fowlers Data Transfer Object Pattern

ServiceStack was heavily influenced by [**Martin Fowlers Data Transfer Object Pattern**](http://martinfowler.com/eaaCatalog/dataTransferObject):

>When you're working with a remote interface, such as Remote Facade (388), each call to it is expensive. 
>As a result you need to reduce the number of calls, and that means that you need to transfer more data 
>with each call. One way to do this is to use lots of parameters. 
>However, this is often awkward to program - indeed, it's often impossible with languages such as Java 
>that return only a single value.
>
>The solution is to create a Data Transfer Object that can hold all the data for the call. It needs 
to be serializable to go across the connection. 
>Usually an assembler is used on the server side to transfer data between the DTO and any domain objects.

The Request- and Response DTO's used to define web services in ServiceStack are standard POCO's while 
the implementation just needs to inherit from a testable and dependency-free `IService` marker interface. 
As a bonus for keeping your DTO's in a separate dependency-free .dll, you're able to re-use them in 
your C#/.NET clients providing a strongly-typed API without any code-gen what-so-ever. Also your DTO's 
*define everything* ServiceStack does not pollute your web services with any additional custom 
artifacts or markup.

### Multiple Clients

Our generic Service clients covers the most popular Mobile, Desktop and Server platforms with first-class implementations for Xamarin, Android, Java and TypeScript which now includes:

 - [.NET Service Clients](/csharp-client)
    - C# / VB.NET / F#
    - .NET Core 2.1+
    - .NET Framework 4.5+
    - Blazor WASM
    - Xamarin.iOS
    - Xamarin.Android
    - UWP
    - Silverlight
 - [TypeScript Service Client](/typescript-add-servicestack-reference#typescript-serviceclient)
    - Web
    - Node.js Server
    - React Native
        - iOS
        - Android
 - [Python Service Client](/python-add-servicestack-reference)
 - [Dart](/dart-add-servicestack-reference)
   - Flutter
        - iOS
        - Android
   - Web / Angular.dart
 - [Java Service Client](/java-add-servicestack-reference#jsonserviceclient-api)
    - Android
    - JVM 1.7+ (Java, Kotlin, Scala, etc)
        - Java Clients
        - Java Servers
 - [Kotlin Service Client](/kotlin-add-servicestack-reference)
 - [Swift Service Client](/swift-add-servicestack-reference#swift-client-usage)
    - iOS
    - OSX
    - [Swift Package Manager Apps](https://github.com/ServiceStackApps/swift-techstacks-console)
 - [JavaScript (jQuery)](/ss-utils-js)
   - Web
 - [MQ Clients](/messaging#mq-client-architecture)
   - Background MQ
   - Rabbit MQ
   - Redis MQ
   - Amazon SQS
   - Azure Service Bus

### Multiple pluggable Formats

ServiceStack re-uses the custom artifacts above and with zero-config and without imposing any extra 
burden on the developer adds discoverability and provides hosting of your web service on a number 
of different formats, including: 
 
 - [JSON]/json-format)
 - XML
 - [JSV](/jsv-format)
 - [CSV](/csv-format)
 - [MsgPack](/messagepack-format)
 - [ProtoBuf](/protobuf-format)
 - [gRPC](/grpc/)
 - [SOAP 1.1/1.2](/soap-support)
 - HTML
   - [HTML5 Report Format](/html5reportformat)
   - [Sharp Pages](https://sharpscript.net/docs/script-pages)
   - [Razor](https://razor.netcore.io/)
   - [Markdown Razor](/markdown-razor)

### Multiple Endpoints

Whilst ServiceStack is fundamentally a premier HTTP Framework, its Services can also be consumed from new [gRPC](/grpc/) as well as legacy [SOAP 1.1 and 1.2](/soap-support) endpoints as well as a number of [MQ Servers](/messaging):

  - [Background MQ Service](/background-mq)
  - [Rabbit MQ Server](/rabbit-mq)
  - [Redis MQ Server](/redis-mq)
  - [Amazon SQS MQ Server](/amazon-sqs-mq)
  - [Azure Service Bus MQ](/azure-service-bus-mq)

### Multiple Hosting Options

In addition to supporting multiple formats and endpoints, ServiceStack can also be hosted within a multitude of different hosting options:

#### Windows, OSX or Linux
 - **.NET Core 2.1+**
   - [Web App or SelfHost](https://github.com/NetCoreApps/LiveDemos#servicestack-net-core-live-demos)
   - [Worker Service](/messaging#worker-service-templates)

#### Windows
 - **.NET Framework 4.5+**
   - [ASP.NET Core 2.1 LTS](/templates/corefx)
   - [Classic ASP.NET System.Web](https://github.com/ServiceStackApps/LiveDemos#live-servicestack-demos)
   - [Stand-alone, Self-Hosted HttpListener](/self-hosting)
   - [Stand-alone Windows Service](/templates/windows-service)
   - [Hosted inside WinForms with Chromium Embedded Framework](https://github.com/ServiceStack/ServiceStack.Gap#winforms-with-chromium-embedded-framework)
   - [Windows and Azure Service Fabric](https://github.com/ServiceStackApps/HelloServiceFabric)

#### OSX
 - [Hosted inside Mac OSX Cocoa App with Xamarin.Mac](https://github.com/ServiceStack/ServiceStack.Gap#mac-osx-cocoa-app-with-xmarainmac)

### Target Multiple platforms

With multi-targeted projects creating both .NET Framework and .NET Standard builds you can optionally run your same ServiceStack App on multiple platforms as seen with the [Hello Mobile Shared Gateway](/releases/v5_0_0#run-aspnet-core-apps-on-the-net-framework) project where its same shared [ServiceStack Server.Common project](https://github.com/ServiceStackApps/HelloMobile#servicestack-server-app) is used to host the same App running on:

 - [Server.NetCore](https://github.com/ServiceStackApps/HelloMobile/tree/master/src/Server.NetCore) - hosting the ServiceStack Services in a **ASP.NET Core 2.1 App**
 - [Server.NetCoreFx](https://github.com/ServiceStackApps/HelloMobile/tree/master/src/Server.NetCoreFx) - hosting in a **ASP.NET Core App** on the **.NET Framework**
 - [Server.AspNet](https://github.com/ServiceStackApps/HelloMobile/tree/master/src/Server.AspNet) - hosting classic **ASP.NET Framework** Web Applications
 - [Server.HttpListener](https://github.com/ServiceStackApps/HelloMobile/tree/master/src/Server.HttpListener) - host in a .NET Framework Self-Hosting **HttpListener** AppHost

### VS.NET Templates

There's a [VS.NET Template](/templates/) for creating solutions targeting most of the above platforms.

E.g. the [React Desktop Apps](https://github.com/ServiceStackApps/ReactDesktopApps) VS.NET Template provides an easy and integrated way to host a Single Page React App on multiple platforms.

## Goals of Service Design

The primary benefits of Services are that they offer the highest level of software re-use, they're [Real Computers all the way down](https://mythz.servicestack.net/#messaging) retaining the ability to represent anything. Especially at this level, encapsulation and its external interactions are paramount which sees the [Service Layer as its most important Contract](http://stackoverflow.com/a/15369736/85785), constantly evolving to support new capabilities whilst serving and outliving its many consumers. 

Extra special attention should be given to Service design with the primary goals of exposing its capabilities behind [consistent and self-describing](/why-servicestack#goals-of-service-design), intent-based [tell-dont-ask](https://pragprog.com/articles/tell-dont-ask) APIs. 

A Services ability to encapsulate complexity is what empowers consumers to be able to perform higher-level tasks like provisioning a cluster of AWS servers or being able to send a tweet to millions of followers in seconds with just a simple HTTP request, i.e. being able to re-use existing hardened functionality without the required effort, resources and infrastructure to facilitate the request yourself. To maximize accessibility it's recommended for Service Interfaces to be orientated around resources and verbs, retain a flat structure, customizable with key value pairs so they're accessible via the built-in QueryString 
and FormData support present in all HTTP clients, from HTML Forms to command-line utilities like [curl](https://curl.haxx.se).

### WCF the anti-DTO Web Services Framework

Unfortunately this best-practices convention is effectively discouraged by Microsoft's WCF SOAP Web Services framework as they encourage you to develop API-specific RPC method calls by mandating the use of method signatures to define your web services API. This results in less re-usable, more client-specific APIs that encourages more remote method calls. 

Unhappy with this perceived anti-pattern in WCF, ServiceStack was born providing a Web Service framework that embraces best-practices for calling remote services, using config-free, convention-based DTO's.

### Encourages development of message-style, re-usable and batch-full web services

Entire POCO types are used to define the request- and response DTO's to promote the creation well-defined coarse-grained web services. Message-based interfaces are best-practices when dealing with out-of-process calls as they can batch more work using less network calls and are ultimately more re-usable as the same operation can be called using different calling semantics. This is in stark contrast to WCF's Operation or Service contracts which encourage RPC-style, application-specific web services by using method signatures to define each operation.

As it stands in general-purpose computing today, there is nothing more expensive you can do than a remote network call. Although easier for the newbie developer, by using _methods_ to define web service operations, WCF is promoting bad-practices by encouraging them to design and treat web-service calls like normal function calls even though they are millions of times slower. Especially at the app-server tier, nothing hurts performance and scalability of your client and server than multiple dependent and synchronous web service calls.

Batch-full, message-based web services are ideally suited in development of SOA services as they result in fewer, richer and more re-usable web services that need to be maintained. RPC-style services normally manifest themselves from a *client perspective* that is the result of the requirements of a single applications data access scenario. Single applications come and go over time while your data and services are poised to hang around for the longer term. Ideally you want to think about the definition of your web service from a *services and data perspective* and how you can expose your data so it is more re-usable by a number of your clients.

## Difference between an RPC-chatty and message-based API

```csharp
public interface IWcfCustomerService
{
    Customer GetCustomerById(int id);
    List<Customer> GetCustomerByIds(int[] id);
    Customer GetCustomerByUserName(string userName);
    List<Customer> GetCustomerByUserNames(string[] userNames);
    Customer GetCustomerByEmail(string email);
    List<Customer> GetCustomerByEmails(string[] emails);
}
```

### contrast with an equivalent message based service:

```csharp
public class Customers : IReturn<List<Customer>> 
{
   public int[] Ids { get; set; }
   public string[] UserNames { get; set; }
   public string[] Emails { get; set; }
}
```

**Any combination of the above can be fulfilled by 1 remote call, by the same single web service - i.e what ServiceStack encourages!**

Fewer and more batch-full services require less maintenance and promote the development of more re-usable and efficient services. 
In addition, message APIs are much more resilient to changes as you're able to safely add more functionality or return more data without breaking or needing to re-gen existing clients. Message-based APIs also lend them better for cached, asynchronous, deferred, proxied and reliable execution with the use of brokers and proxies.

Comparatively there is almost no win for a remote RPC API, except to maybe [hide a remote service even exists](https://en.wikipedia.org/wiki/Fallacies_of_Distributed_Computing) by making a remote call look like a method call even though they're millions of times slower, leading new developers to develop inefficient, brittle systems from the start.


# Architecture Overview
Source: https://docs.servicestack.net/architecture-overview

Ultimately behind-the-scenes ServiceStack is just built on top of ASP.NET's Raw 
[IHttpAsyncHandler](https://msdn.microsoft.com/en-us/library/ms227433.aspx). 
Existing abstractions and [xmlconfig-encumbered legacy ASP.NET providers](http://mono.servicestack.net/mvc-powerpack/) have been abandoned, 
in favour of fresh, simple and clean [Caching](/caching), [Session](/auth/sessions) 
and [Authentication](/auth/authentication-and-authorization) providers all based on clean POCOs, 
supporting multiple back-ends and all working seamlessly together. Our best-practices 
architecture is purposely kept simple, introduces minimal new concepts or artificial constructs that 
can all be eloquently captured in the diagram below:

## Server Architecture

![ServiceStack Logical Architecture View](/img/pages/overview/servicestack-logical-view-02.png) 

## Client Architecture

ServiceStack's [Message-based design](/advantages-of-message-based-web-services) allows us to easily support [typed, generic and re-usable Service Clients](/clients-overview) for all our popular formats:

![ServiceStack HTTP Client Architecture](/img/pages/overview/servicestack-httpclients.png) 

Having all clients share the same interface allow them to be hot-swappable at run-time without code changes and keep them highly testable where the same unit test can also [serve as an XML, JSON, JSV, SOAP Integration Test](https://github.com/ServiceStack/ServiceStack/blob/master/tests/ServiceStack.WebHost.IntegrationTests/Tests/WebServicesTests.cs).

By promoting clean (endpoint-ignorant and dependency-free) Service and DTO classes, your web services are instantly re-usable and can be hosted in non-http contexts as well. E.g. The client architecture when one of the [built-in MQ Host is enabled](/redis-mq):

![ServiceStack MQ Client Architecture](/img/pages/overview/servicestack-mqclients.png) 

## Implementation 

The entry point for all ASP.NET and HttpListener requests is in the [ServiceStack.HttpHandlerFactory](https://github.com/ServiceStack/ServiceStack/blob/master/src/ServiceStack/HttpHandlerFactory.cs) whose purpose is to return the appropriate IHttpHandler for the incoming request.

There are 2 distinct modes in any ServiceStack application:

1. AppHost Setup and Configuration - Only done once for all services. Run only once on App StartUp.
1. Runtime - Run on every request: uses dependencies, plugins, etc. defined in the AppHost. Each new request re-binds all IOC dependencies to a new service instance which gets disposed at the end of each request.

The implementation of this can be visualized below:

![ServiceStack Overview](/img/pages/overview/servicestack-overview-01.png)

After the `IHttpHandler` is returned, it gets executed with the current ASP.NET or HttpListener request wrapped in a common [IRequest](https://github.com/ServiceStack/ServiceStack/blob/master/src/ServiceStack.Interfaces/Web/IRequest.cs) instance.


# Instantly Servicify existing Systems
Source: https://docs.servicestack.net/servicify

In addition to [AutoQuery](/autoquery/rdbms) automatically providing your Services implementations,
[Studio](/studio) providing its instant UI, ServiceStack also gained the capability to **[generate your entire API](/autoquery/autogen)** including Typed API contracts, data models, implementations & human-friendly pluralized HTTP API routes over an existing System RDBMS's tables.

<lite-youtube class="w-full mx-4 my-4" width="560" height="315" videoid="NaJ7TW-Q_pU" style="background-image: url('https://img.youtube.com/vi/NaJ7TW-Q_pU/maxresdefault.jpg')"></lite-youtube>

## AutoGen

ServiceStack's [AutoGen](/autoquery/autogen) enables a number of exciting possibilities, predominantly it's the fastest way to ServiceStack-ify an existing systems RDBMS where it will serve as an invaluable tool for anyone wanting to quickly migrate to ServiceStack and access its functionality ecosystem around ServiceStack Services:

<img src="/img/pages/svg/servicify.svg" width="100%">

**[AutoGen's](/autoquery/autogen)** code generation is programmatically customizable where the generated types can be easily augmented with additional declarative attributes to inject your App's conventions into the auto generated Services & Types to apply custom behavior like Authorization & additional validation rules. 

After codifying your system conventions the generated classes can optionally be "ejected" where code-first development can continue as normal.

This feature enables rewriting parts or modernizing legacy systems with the least amount of time & effort, once Servicified you can take advantage of declarative features like Multitenancy, Optimistic Concurrency & Validation, enable automatic features like Executable Audit History, allow business users to maintain validation rules in its RDBMS, manage them through **Studio** & have them applied instantly at runtime 
and visibly surfaced through ServiceStack's myriad of [client UI auto-binding options](/world-validation). **Studio** can then enable stakeholders with an instant UI to quickly access and search through their data, import custom queries directly into Excel or access them in other registered Content Types through a custom UI where fine-grained app-level access can be applied to customize which tables & operations different users have.

### gRPC's Typed protoc Universe

<img src="/img/pages/svg/grpc-icon-color.svg" height="100" align="right">

**AutoGen** also enables access to ServiceStack's ecosystem of metadata services & connectivity options where it's now become the **fastest way to generate gRPC endpoints** over an existing system. This is especially exciting as in addition to enabling high-performance connectivity to your Systems data, it opens it up to [all languages in gRPC's protoc universe](https://grpc.io/docs/languages/).

Whilst the Smart, Generic [C# / F# / VB.NET Service Clients](/grpc/generic) continue to provide the best UX for consuming gRPC Services, one of the nicest **protoc generated** clients languages is [Dart](http://dart.dev) - a modern high-level language with native class performance & script-like productivity where individual source files can be run immediately without compilation, it's quality tooling, static analysis &
high-level features like async/await make it an ideal exploratory language for consuming gRPC endpoints.

### Dart gRPC Script Playground

<img src="/img/pages/svg/dart-logo.svg" height="75" align="right">

This quick demo shows an example of instantly Servicifying a database & accesses it via gRPC in minutes, starting with a new [grpc](https://github.com/NetCoreTemplates/grpc) project from scratch, it [mixes](/mix-tool) in [autocrudgen](https://gist.github.com/gistlyn/464a80c15cb3af4f41db7810082dc00c) to configure **AutoGen** to generate AutoQuery services for the registered [sqlite](https://gist.github.com/gistlyn/768d7b330b8c977f43310b954ceea668) RDBMS that's copied into the project from the [northwind.sqlite](https://gist.github.com/gistlyn/97d0bcd3ebd582e06c85f8400683e037) gist.

Once the servicified App is running it accesses the gRPC Services in a new Dart Console App using the UX-friendly [Dart gRPC support in the x dotnet tool](/grpc/dart) to call the protoc generated Services:

> YouTube: [youtu.be/5NNCaWMviXU](https://youtu.be/5NNCaWMviXU)

[![](/img/pages/release-notes/v5.9/autogen-grpc.png)](https://youtu.be/5NNCaWMviXU)

### Flutter gRPC Android App

<img src="/img/pages/svg/flutter-logo.svg" height="75" align="right">

And if you can access it from Dart, you can access it from all platforms Dart runs on - the most exciting is Google's [Flutter](https://flutter.dev) UI Kit for building beautiful, natively compiled applications for Mobile, Web, and Desktop from a single codebase:

> YouTube: [youtu.be/3iz9aM1AlGA](https://youtu.be/3iz9aM1AlGA)

[![](/img/pages/release-notes/v5.9/autogen-grpc-flutter.jpg)](https://youtu.be/3iz9aM1AlGA)

## React Native Typed Client

<img src="/img/pages/svg/react-native-logo.svg" width="300" align="right">

gRPC is just [one of the endpoints ServiceStack Services](/why-servicestack#multiple-clients) can be accessed from, for an even richer & more integrated development UX they're also available in all popular Mobile, Web & Desktop languages [Add ServiceStack Reference](/add-servicestack-reference) supports.

Like [TypeScript](/typescript-add-servicestack-reference) which can be used in Browser & Node TypeScript code-bases as well as JavaScript-only code-bases like [React Native](https://reactnative.dev) - a highly productive Reactive UI for developing iOS and Android Apps:

[![](/img/pages/release-notes/v5.9/autogen-react-native.png)](https://youtu.be/6-SiLAbY63w)

::: info YouTube
[youtu.be/6-SiLAbY63w](https://youtu.be/6-SiLAbY63w)
:::


# Explore ServiceStack
Source: https://docs.servicestack.net/explore-servicestack

If you're completely new to ServiceStack, the [YouTube channel](https://www.youtube.com/channel/UC0kXKGVU4NHcwNdDdRiAJSA/videos) is a great way to explore some of the possibilities easily enabled with ServiceStack:

[![](/img/pages/overview/servicestack-youtube.png)](https://www.youtube.com/channel/UC0kXKGVU4NHcwNdDdRiAJSA/videos)

## Explore ServiceStack Apps

A great way to learn new technology is to explore existing Apps built with it, where for ServiceStack you can find a number of simple focused Apps at:

### [.NET Core Apps](https://github.com/NetCoreApps/LiveDemos)

### [.NET Framework Apps](https://github.com/ServiceStackApps/LiveDemos#live-servicestack-demos)

### [Sharp Apps](https://sharpscript.net/sharp-apps/app-index)

Many Apps are well documented like [World Validation](/world-validation) which covers how to re-implement a simple Contacts App UI in 
**10 popular Web Development approaches** - all calling the same ServiceStack Services. 

ServiceStack is a single code-base implementation that supports [.NET's most popular Server platforms](/why-servicestack#multiple-hosting-options) with
near perfect source-code [compatibility with .NET Core](/netcore) so all .NET Frameworks Apps are still relevant in .NET Core, e.g. 
the [EmailContacts guidance](https://github.com/ServiceStackApps/EmailContacts) walks through the recommended setup and physical layout structure of typical medium-sized ServiceStack projects, including complete documentation of how to create the solution from scratch, whilst explaining all the ServiceStack features it makes use of along the way.

## Starting Project Templates

Once you've familiarized yourself with ServiceStack and are ready to use it in action, get started with a customized starting project template from our online template builder at:

<h2 class="text-center pb-2"><a href="https://servicestack.net/start">servicestack.net/start</a></h2>

[![](/img/pages/overview/servicestack-start.png)](https://servicestack.net/start)


# ServiceStack v8.9
Source: https://docs.servicestack.net/releases/v8_09

<div class="-mt-16 flex justify-center not-prose">
    <audio-player id="v8-9-release" title="ServiceStack v8.9 Podcast Episode" src="https://media.servicestack.com/podcasts/v8-9-release.mp3" variant="compact" beacon-url="https://account.servicestack.net/stats/podcast/record?name=v8-9-release&source=v8_09&version=8.9"
        class="w-[500px]"></audio-player>
</div>

![](/img/pages/release-notes/v8.9/bg.webp)

We're happy to announce ServiceStack v8.9 - a major release packed with lots of new features and improvements across the board. Unfortunately these release notes have become apologetically long, so we've added a Table of Contents below to make it easier to jump to the biggest features you're interested in:

 - [OrmLite's new Configuration Model and Defaults](#ormlites-new-configuration-model-and-defaults)
 - [RDBMS Async Tasks Builder](#rdbms-async-tasks-builder)
 - [RDBMS Background Jobs (PostgreSQL, SQL Server, MySql/MariaDB)](#rdbms-background-jobs)
 - [RDBMS Request Logging and Analytics (PostgreSQL, SQL Server, MySql/MariaDB)](#rdbms-request-logging-and-analytics)
 - [Protect same APIs with API Keys or Identity Auth](#protect-same-apis-with-api-keys-or-identity-auth)
 - [AI Chat - OpenAI Chat Compatible API and Server Gateway](#ai-chat)
 - [AI Chat UI - Customizable, Private, ChatGPT-like UI](#ai-chat-ui)
 - [ChatCompletion custom API Explorer UI](#creating-a-custom-explorer-ui-for-openais-chat-api)
 - [XSS Vulnerability fixed in HtmlFormat.html](#xss-vulnerability-fixed-in-htmlformat.html)

## OrmLite's new Configuration Model and Defaults

In continuing with ServiceStack's [seamless integration with the ASP.NET Framework](https://docs.servicestack.net/releases/v8_01), providing a familiar development experience that follows .NET configuration model and Entity Framework conventions
has become a priority.

Implementing a new configuration model also gives us the freedom to change OrmLite's defaults which wasn't possible before 
given the paramount importance of maintaining backwards compatibility in a data access library that accesses existing
Customer data.

#### JSON used for Complex Types

The biggest change that applies to all RDBMS providers is replacing the JSV serialization used for serializing Complex Types with JSON now that most RDBMS have native support for JSON.

#### PostgreSQL uses default Naming Strategy

The biggest change to PostgreSQL is using the same default naming strategy as other RDBMS which matches EF's convention
that's used for ASP .NET's Identity Auth tables.

#### SQL Server uses latest 2022 Dialect

SQL Server now defaults to the latest SqlServer 2022 dialect which is also compatible with SQL Server 2016+

## New Configuration Model

OrmLite new modern, fluent configuration API aligns with ASP.NET Core's familiar `services.Add*()` pattern.
This new approach provides a more intuitive and discoverable way to configure your database connections, with strongly-typed
options for each RDBMS provider.

The new configuration model starts with the `AddOrmLite()` extension method to configure its default `IDbConnectionFactory` dependency by combining it with RDBMS provider-specific methods for the RDBMS you wish to use:

 - `UseSqlite()` in **ServiceStack.OrmLite.Sqlite.Data** 
 - `UsePostgres()` in **ServiceStack.OrmLite.PostgreSQL**
 - `UseSqlServer()` in **ServiceStack.OrmLite.SqlServer.Data**
 - `UseMySql()`  in **ServiceStack.OrmLite.MySql**
 - `UseMySqlConnector()`  in **ServiceStack.OrmLite.MySqlConnector**
 - `UseOracle()`  in **ServiceStack.OrmLite.Oracle** (community supported)
 - `UseFirebird()`  in **ServiceStack.OrmLite.Firebird** (community supported)

Each provider method accepts a connection string and an optional configuration callback that lets you customize the dialect's 
behavior with IntelliSense support.

It's an alternative approach to manually instantiating `OrmLiteConnectionFactory` with specific dialect providers,
offering better discoverability and a more consistent experience across different database providers.

### SQLite

```csharp
services.AddOrmLite(options => options.UseSqlite(connectionString));
```

Each RDBMS provider can be further customized to change its defaults with:

```csharp
services.AddOrmLite(options => options.UseSqlite(connectionString, dialect => {
        // Default SQLite Configuration:
        dialect.UseJson = true;
        dialect.UseUtc = true;
        dialect.EnableWal = true;
        dialect.EnableForeignKeys = true;
        dialect.BusyTimeout = TimeSpan.FromSeconds(30);
    })
);
```

### PostgreSQL

```csharp
services.AddOrmLite(options => options.UsePostgres(connectionString));
```

With Dialect Configuration:

```csharp
services.AddOrmLite(options => options.UsePostgres(connString, dialect => {
        // Default PostgreSQL Configuration:
        dialect.UseJson = true;
        dialect.NamingStrategy = new OrmLiteNamingStrategyBase();
    })
);
```

### Removed snake_case naming strategy

:::{.float-right .-mt-24! .-mr-12! .max-w-xs .pl-4}
![](/img/pages/release-notes/v8.9/postgres-naming-strategy.webp)
:::

PostgreSQL now defaults to using the same naming strategy as other RDBMS, i.e. no naming strategy, and uses the 
PascalCase naming of C# classes as-is.

With this change OrmLite's table and columns now follow EF's convention which is used for ASP.NET's Identity Auth tables.

This is more fragile in PostgreSQL as it forces needing to use quoted table and column names for all queries, e.g.

```sql
SELECT "MyColumn" FROM "MyTable"
```

This is required as PostgreSQL isn't case-insensitive and lowercases all unquoted symbols, e.g:

```sql
SELECT MyColumn FROM MyTable
-- Translates to:
SELECT mycolumn FROM mytable
```

This is already done by OrmLite, but any custom queries also need to use quoted symbols.

### SQL Server

```csharp
services.AddOrmLite(options => options.UseSqlServer(connectionString));
```

With Dialect Configuration:

```csharp
services.AddOrmLite(options => options.UseSqlServer(connString, dialect => {
        // Default SQL Server Configuration:
        dialect.UseJson = true;
    })
);
```

### Uses Latest SQL Server at each .NET LTS Release

To keep it modern and predictable, this will use the latest SQL Server Dialect that was released at the time of each 
major .NET LTS versions, currently `SqlServer2022OrmLiteDialectProvider`, which we'll keep until the next .NET LTS release.
Although the **2022** dialect is also compatible with every SQL Server version from **2016+**.

To use an explicit version of SQL Server you can use the generic overload that best matches your version:

```csharp
services.AddOrmLite(options => 
    options.UseSqlServer<SqlServer2014OrmLiteDialectProvider>(connString));
```

### MySQL

```csharp
services.AddOrmLite(options => options.UseMySql(connectionString));
```

With Dialect Configuration:

```csharp
services.AddOrmLite(options => options.UseMySql(connectionString, dialect => {
        // Default MySql Configuration:
        dialect.UseJson = true;
    })
);
```

For MySqlConnector use:

```csharp
services.AddOrmLite(options => options.AddMySqlConnector(connectionString));
```

### Named Connections

The new OrmLite configuration model also streamlines support for named connections, allowing you to register 
multiple database connections with unique identifiers in a single fluent configuration chain, e.g:

```csharp
services.AddOrmLite(options => {
        options.UseSqlite(":memory:")
            .ConfigureJson(json => {
                json.DefaultSerializer = JsonSerializerType.ServiceStackJson;
            });
    })
    .AddSqlite("db1", "db1.sqlite")
    .AddSqlite("db2", "db2.sqlite")
    .AddPostgres("reporting", PostgreSqlDb.Connection)
    .AddSqlServer("analytics", SqlServerDb.Connection)
    .AddSqlServer<SqlServer2014OrmLiteDialectProvider>(
        "legacy-analytics", SqlServerDb.Connection)
    .AddMySql("wordpress", MySqlDb.Connection)
    .AddMySqlConnector("drupal", MySqlDb.Connection)
    .AddOracle("enterprise", OracleDb.Connection)
    .AddFirebird("firebird", FirebirdDb.Connection);
```

### Complex Type JSON Serialization

Previously OrmLite only supported serializing Complex Types with a [single Complex Type Serializer](https://docs.servicestack.net/ormlite/complex-type-serializers)
but the new configuration model now uses a more configurable `JsonComplexTypeSerializer` where you can change the default 
JSON Serializer OrmLite should use for serializing Complex Types as well as fine-grain control over which types should
use which serializer by using the `ConfigureJson()` extension method on each provider.

```csharp
services.AddOrmLite(options => {
        options.UsePostgres(connectionString)
            .ConfigureJson(json => {
                // Default JSON Complex Type Serializer Configuration
                json.DefaultSerializer = JsonSerializerType.ServiceStackJson;
                json.JsonObjectTypes = [
                    typeof(object),
                    typeof(List<object>),
                    typeof(Dictionary<string, object?>),
                ];
                json.SystemJsonTypes = [];
                json.ServiceStackJsonTypes = [];
            });
    })
```

By default OrmLite uses **ServiceStack.Text** JSON Serializer which is less strict and more resilient than System.Text.Json
for handling versioning of Types that change over time, e.g. an `int` Property that's later changed to a `string`.

In addition to configuring a default you can also configure which types should be serialized with which serializer.
So we could change OrmLite to use **System.Text.Json** for all types except for `ChatCompletion` which we want to use 
**ServiceStack.Text** JSON for:

```csharp
services.AddOrmLite(options => {
        options.UsePostgres(connectionString)
            .ConfigureJson(json => {
                json.DefaultSerializer = JsonSerializerType.SystemJson;
                json.ServiceStackJsonTypes = [
                    typeof(ChatCompletion)
                ];
            });
    })
```

#### Unstructured JSON with JSON Object

The default Exception to this is for serialization of `object`, `List<object>` and `Dictionary<string,object>` types which is better handled by [#Script's JSON Parser](https://docs.servicestack.net/js-utils) 
which is able to parse any valid adhoc JSON into untyped .NET generic collections, which is both mutable and able to 
[utilize C# pattern matching](https://docs.servicestack.net/js-utils#getting-the-client_id-in-a-comfyui-output) 
for easy introspection. 

The new `TryGetValue<T>` extension method on `Dictionary<string,object?>` makes it even more convenient for parsing
adhoc JSON which can use the `out` Type parameter to reduce unnecessary type checking, e.g. here's a simple example 
of parsing a ComfyUI Output for the client_id used in a generation:

```csharp
var comfyOutput = JSON.ParseObject(json);
var prompt = (Dictionary<string, object?>)result.Values.First()!;
if (prompt.TryGetValue("prompt", out List<object> tuple) && tuple.Count > 3)
{
    if (tuple[3] is Dictionary<string, object?> extraData
        && extraData.TryGetValue("client_id", out string clientId))
    {
        Console.WriteLine(clientId);
    }
}
```

Where as an Equivalent implementation using System.Text.Json `JsonDocument` would look like:

```csharp
using System.Text.Json;

var jsonDocument = JsonDocument.Parse(json);
var root = jsonDocument.RootElement;

// Get the first property value (equivalent to result.Values.First())
var firstProperty = root.EnumerateObject().FirstOrDefault();
if (firstProperty.Value.ValueKind == JsonValueKind.Object)
{
    var prompt = firstProperty.Value;

    if (prompt.TryGetProperty("prompt", out var promptElement)
        && promptElement.ValueKind == JsonValueKind.Array)
    {
        var promptArray = promptElement.EnumerateArray().ToArray();
        if (promptArray.Length > 3)
        {
            var extraDataElement = promptArray[3];
            if (extraDataElement.ValueKind == JsonValueKind.Object
                && extraDataElement.TryGetProperty("client_id", out var clientIdElement)
                && clientIdElement.ValueKind == JsonValueKind.String)
            {
                var clientId = clientIdElement.GetString();
                Console.WriteLine(clientId);
            }
        }
    }
}
```

### Table Aliases

One potential breaking change is that table aliases are used verbatim and no longer uses a naming strategy for transforming
its name which potentially affects PostgreSQL when an Alias is used that doesn't match the name of the table, e.g:

```csharp
[Alias("MyTable")] //= "MyTable" 
public class NewMyTable { ... }

[Alias("MyTable")] //= my_table 
public class OldMyTable { ... }
```

Aliases should either be changed to the Table name you want to use or you can use the Naming Strategy Alias dictionaries
for finer-grain control over what Schema, Table, Column Names and Aliases should be used: 

```csharp
services.AddOrmLite(options => options.UsePostgres(connString, dialect => {
    dialect.NamingStrategy.TableAliases["MyTable"] = "my_table";
    dialect.NamingStrategy.SchemaAliases["MySchema"] = "my_schema";
    dialect.NamingStrategy.ColumnAliases["MyColumn"] = "my_columnt";
}));
```

### Table Refs

A significant internal refactor of OrmLite was done to encapsulate different ways of referring to a table in a single
`TableRef` struct, which is now used in all APIs that need a table reference.

The new `TableRef` struct allows for unified APIs that encapsulates different ways of referencing a table:

- Type `new TableRef(typeof(MyTable))`
- Model Definition `new TableRef(ModelDefinition<MyTable>.Definition)`
- Table Name `new TableRef("MySchema")`
- Schema and Table Name `new TableRef("MySchema", "MyTable"))`
- Quoted Name (use verbatim) `TableRef.Literal("\"MyTable\"")`
- Implicitly casts to a string as `new TableRef("MySchema")`.

OrmLite handles differences between different RDBMS Providers via its `IOrmLiteDialectProvider` interface. 
Previously OrmLite used to maintain multiple overloads for handling some of these differences in referencing a 
table but they've now all been consolidated into use a single `TableRef` parameter:

```csharp
public interface IOrmLiteDialectProvider
{
    bool DoesTableExist(IDbConnection db, TableRef tableRef);
    string GetTableNameOnly(TableRef tableRef);
    string UnquotedTable(TableRef tableRef);
    string GetSchemaName(TableRef tableRef);
    string QuoteTable(TableRef tableRef);
    bool DoesTableExist(IDbConnection db, TableRef tableRef);
    bool DoesColumnExist(IDbConnection db, string columnName, TableRef tableRef);
    string ToAddColumnStatement(TableRef tableRef, FieldDefinition fieldDef);
    string ToAlterColumnStatement(TableRef tableRef, FieldDefinition fieldDef);
    string ToChangeColumnNameStatement(TableRef tableRef, FieldDefinition fieldDef, string oldColumn);
    string ToRenameColumnStatement(TableRef tableRef, string oldColumn, string newColumn);
    string ToDropColumnStatement(TableRef tableRef, string column);
    string ToDropConstraintStatement(TableRef tableRef, string constraint);
    string ToDropForeignKeyStatement(TableRef tableRef, string foreignKeyName);
}
```

For example the `QuoteTable(TableRef)` method can be used to quote a table. Assuming our dialect was configured 
with the `my_table` Table Aliases, these are the results for the different ways of referencing `MyTable`:

```csharp
dialect.QuoteTable("MyTable")                       //= "my_table" (implicit)
dialect.QuoteTable(new("MyTable"))                  //= "my_table"
dialect.QuoteTable(new("MySchema","MyTable"))       //= "my_schema"."my_table"
dialect.QuoteTable(TableRef.Literal("\"MyTable\"")) //= "MyTable" (verbatim)
dialect.QuoteTable(new(typeof(MyTable)))            //= "my_table"
dialect.QuoteTable(new(ModelDefinition<MyTable>.Definition)) //= "my_table"
```

### Improved Observability

Significant effort was put into improving OrmLite's Observability where OrmLite's DB Connections can now be tagged
to make them easier to track in hooks, logs and traces.

To achieve this a new `Action<IDbConnection>` configuration callbacks were added to OrmLite Open Connection APIs
which is invoked before a DB Connection is opened, e.g:

```csharp
using var db = dbFactory.Open(configure: db => db.WithTag("MyTag"));
using var db = dbFactory.Open(namedConnection, configure: db => db.WithTag("MyTag"));

using var db = HostContext.AppHost.GetDbConnection(req, configure: db => db.WithTag("MyTag"));
```

Which ServiceStack uses internally to tag DB Connections with the feature executing it, or for `Db` connections used in 
Services it will tag it with the Request DTO Name.

:::{.wideshot}
![](/img/pages/release-notes/v8.9/ormlite-tags.webp)
:::

If a tag is configured, it's also included in OrmLite's Debug Logging output, e.g:

```txt
dbug: ServiceStack.OrmLiteLog[0]
      [PostgresDbJobsProvider] SQL: SELECT "Id", "ParentId", "RefId", "Worker", "Tag", "BatchId", "Callback", "DependsOn", "RunAfter", "CreatedDate", "CreatedBy", "RequestId", "RequestType", "Command", "Request", "RequestBody", "UserId", "Response", "ResponseBody", "State", "StartedDate", "CompletedDate", "NotifiedDate", "RetryLimit", "Attempts", "DurationMs", "TimeoutSecs", "Progress", "Status", "Logs", "LastActivityDate", "ReplyTo", "ErrorCode", "Error", "Args", "Meta" 
      FROM "BackgroundJob"
      WHERE ("State" = :0)
      PARAMS: :0=Cancelled
dbug: ServiceStack.OrmLiteLog[0]
      TIME: 1.818m
```

#### DB Command Execution Timing

OrmLite's debug logging now also includes the elapsed time it took to execute the command which is also available on the 
`IDbCommand` `GetTag()` and `GetElapsedTime()` APIs, e.g:

```csharp
OrmLiteConfig.AfterExecFilter = cmd =>
{
    Console.WriteLine($"[{cmd.GetTag()}] {cmd.GetElapsedTime()}");
};
```

### ExistsById APIs

New `ExistsById` APIs for checking if a row exists for a given Id:

```csharp
db.ExistsById<Person>(1);
await db.ExistsByIdAsync<Person>(1);

// Alternative to:
db.Exists<Person>(x => x.Id == 1);
await db.ExistsAsync<Person>(x => x.Id == 1);
```

### ResetSequence for PostgreSQL

The `ResetSequence` API is available to reset a Table's Id sequence in Postgres:

```csharp
db.ResetSequence<MyTable>(x => x.Id);
```

#### Data Import example using BulkInsert

This is useful to reset a PostgreSQL Table's auto-incrementing sequence when re-importing a dataset from a 
different database, e.g:

```csharp
db.DeleteAll<Tag>();
db.ResetSequence<Tag>(x => x.Id);
db.DeleteAll<Category>();
db.ResetSequence<Category>(x => x.Id);
        
var config = new BulkInsertConfig { Mode = BulkInsertMode.Sql };
db.BulkInsert(dbSqlite.Select<Tag>().OrderBy(x => x.Id), config);
db.BulkInsert(dbSqlite.Select<Category>().OrderBy(x => x.Id), config);
```

### New SqlDateFormat and SqlChar Dialect APIs

The SQL Dialect functions provide an RDBMS agnostic way to call SQL functions that differs among different RDBMS's.

The `DateFormat` accepts [SQLite strftime() function](https://www.w3resource.com/sqlite/sqlite-strftime.php) date and 
time modifiers in its format string whilst the `Char` accepts a character code, e.g:

```csharp
var q = db.From<CompletedJob>();
var createdDate = q.Column<CompletedJob>(c => c.CreatedDate);
var months = db.SqlColumn<string>(q
    .Select(x => new {
        Month = q.sql.DateFormat(createdDate, "%Y-%m"),
        Log = q.sql.Concat(new[]{ "'Prefix'", q.sql.Char(10), createdDate })
    }));
```

When executed in PostgreSQL it would generate:

```sql
SELECT TO_CHAR("CreatedDate", 'YYYY-MM'), 'Prefix' || CHR(10) || "CreatedDate" 
FROM "CompletedJob"
```

## RDBMS Async Tasks Builder

### Sequential Async DB Access

Async improves I/O thread utilization in multi-threaded apps like Web Servers. However, it doesn't improve the performance 
of individual API Requests that need to execute multiple independent DB Requests. These are often written to run async 
db access sequentially like this:

```csharp
var rockstars = await Db.SelectAsync<Rockstar>();
var albums = await Db.SelectAsync<Album>();
var departments = await Db.SelectAsync<Department>();
var employees = await Db.SelectAsync<Employee>();
```

The issue being that it's not running them in parallel as each DB Request is executed sequentially with the Request for
Albums not starting until the Request for Rockstars has completed.

To run them in parallel you would need to open multiple scoped DB Connections, await them concurrently then do the 
syntax boilerplate gymnastics required to extract the generic typed results, e.g:

```csharp
var connections = await Task.WhenAll(
    DbFactory.OpenDbConnectionAsync(),
    DbFactory.OpenDbConnectionAsync(),
    DbFactory.OpenDbConnectionAsync(),
    DbFactory.OpenDbConnectionAsync()
);

using var dbRockstars = connections[0];
using var dbAlbums = connections[1];
using var dbDepartments = connections[2];
using var dbEmployees = connections[3];

var tasks = new List<Task>
{
    dbRockstars.SelectAsync<Rockstar>(),
    dbAlbums.SelectAsync<Album>(),
    dbDepartments.SelectAsync<Department>(),
    dbEmployees.SelectAsync<Employee>()
};
await Task.WhenAll(tasks);

var rockstars = ((Task<List<Rockstar>>)tasks[0]).Result;
var albums = ((Task<List<Album>>)tasks[1]).Result;
var departments = ((Task<List<Department>>)tasks[2]).Result;
var employees = ((Task<List<Employee>>)tasks[3]).Result;
```

Even without Error handling, writing coding like this can quickly become tedious, less readable and error prone that
as a result is rarely done.

### Parallel DB Requests in TypeScript

This is easier to achieve in languages like TypeScript where typed ORMs like [litdb.dev](https://litdb.dev)
can run multiple DB Requests in parallel with just:

```csharp
const [rockstars, albums, departments, employees] = await Promise.all([
    db.all<Rockstar>($.from(Rockstar)),     //= Rockstar[]
    db.all<Album>($.from(Album)),           //= Album[]
    db.all<Department>($.from(Department)), //= Department[]
    db.all<Employee>($.from(Employee)),     //= Employee[]
])
```

Which benefits from TypeScript's powerful type system that allows destructuring arrays whilst preserving their positional types, 
whilst its single threaded event loop lets you reuse the same DB Connection to run DB Requests in parallel without 
multi-threading issues.

## OrmLite's new Async Tasks Builder

OrmLite's new `AsyncDbTasksBuilder` provides a similar benefit of making it effortless to run multiple async DB Requests 
in parallel, which looks like:

```csharp
var results = await DbFactory.AsyncDbTasksBuilder()
    .Add(db => db.SelectAsync<Rockstar>())
    .Add(db => db.SelectAsync<Album>())
    .Add(db => db.SelectAsync<Department>())
    .Add(db => db.SelectAsync<Employee>())
    .RunAsync();
var (rockstars, albums, departments, employees) = results;
```

Which just like TypeScript's destructuring returns a positionally typed tuple of the results which can be destructured back 
into their typed variables, e.g:

```csharp
(List<Rockstar> rockstars, 
 List<Album> albums,
 List<Department> departments,
 List<Employee> employees) = results;
```

### Supports up to 8 Tasks

It allows chaining up to **8 async Tasks in parallel** as C#'s Type System doesn't allow for preserving different 
positional generic types in an unbounded collection. Instead each Task returns a new Generic Type builder which preserves
the positional types before it.

### Supports both Async `Task<T>` and `Task` APIs

Where `Task<T>` and `Task` APIs can be mixed and matched interchangeably: 

```csharp
var builder = DbFactory.AsyncDbTasksBuilder()
    .Add(db => db.InsertAsync(rockstars[0],rockstars[1]))
    .Add(db => db.SelectAsync<Rockstar>())
    .Add(db => db.InsertAsync(albums[2],albums[3]))
    .Add(db => db.SelectAsync<Album>())
    .Add(db => db.InsertAsync([department]))
    .Add(db => db.SelectAsync<Department>())
    .Add(db => db.InsertAsync([employee]))
    .Add(db => db.SelectAsync<Employee>());
```

Where to preserve the results chain, `Task` APIs return `bool` results, e.g:

```csharp
(bool r1, 
 List<Rockstar> r2, 
 bool r3, 
 List<RockstarAlbum> r4, 
 bool r5, 
 List<Department> r6, 
 bool r7, 
 List<Employee> r8) = await builder.RunAsync();
```

### Error Handling

Whilst tasks are executed in parallel when added, any Exceptions are only thrown when the task is awaited:

```csharp
using var Db = await OpenDbConnectionAsync();

var builder = DbFactory.AsyncDbTasksBuilder()
    .Add(db => db.InsertAsync(rockstars[0]))
    .Add(db => db.InsertAsync(rockstars[0])); // <-- Duplicate PK Exception

// Exceptions are not thrown until the task is awaited
try
{
    var task = builder.RunAsync();
}
catch (Exception e)
{
    throw;
}
```

## RDBMS Background Jobs

We're excited to announce that we've ported our much loved [Background Jobs](https://docs.servicestack.net/background-jobs)
feature for SQLite to the popular **PostgreSQL**, **SQL Server** and **MySQL** RDBMS's.

Whilst we love [SQLite + Litestream](https://docs.servicestack.net/ormlite/litestream) for its low dev ops maintenance
allowing us to break free from 
[expensive cloud hosting hosts](https://docs.servicestack.net/ormlite/litestream#the-right-time-for-server-side-sqlite) 
for managed RDBMS's, it's clear many of our Customers need the features of an industrial strength RDBMS.

In future we'll also be looking at providing a great self-hosted manged solution for Customers that can be run free of 
expensive cloud hosting costs (starting with PostgreSQL). Before we can focus on this we needed to rewrite all our 
SQLite-only features to work with OrmLite's other premier supported RDBMS's. 

The new **DatabaseJobFeature** is a new implementation purpose built for PostgreSQL, SQL Server and MySQL backends that's 
a drop-in replacement for SQLite's **BackgroundsJobFeature** which can be applied to an existing .NET 8+ project by 
[mixing in](https://docs.servicestack.net/mix-tool) the **db-identity** or **db-jobs** gist files to your host project.

### Install

For [ServiceStack ASP.NET Identity Auth](https://servicestack.net/start) Projects:

:::sh
x mix db-identity
:::

Which replaces `Configure.BackgroundJobs.cs` and `Configure.RequestLogs.cs` with an equivalent
version that uses the new `DatabaseJobFeature` for sending Application Emails and `DbRequestLogger` 
for API Request Logging.

All other .NET 8+ ServiceStack Apps should instead use:

:::sh
x mix db-jobs
:::

Which replaces `Configure.BackgroundJobs.cs` to use `DatabaseJobFeature`:

```csharp
public class ConfigureBackgroundJobs : IHostingStartup
{
    public void Configure(IWebHostBuilder builder) => builder
        .ConfigureServices(services => {
            services.AddPlugin(new CommandsFeature());
            services.AddPlugin(new DatabaseJobFeature {
                // NamedConnection = "<alternative db>"
            });
            services.AddHostedService<JobsHostedService>();
         }).ConfigureAppHost(afterAppHostInit: appHost => {
            var services = appHost.GetApplicationServices();
            var jobs = services.GetRequiredService<IBackgroundJobs>();
            // Example of registering a Recurring Job to run Every Hour
            //jobs.RecurringCommand<MyCommand>(Schedule.Hourly);
        });
}

public class JobsHostedService(ILogger<JobsHostedService> log, IBackgroundJobs jobs) : BackgroundService
{
    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
    {
        await jobs.StartAsync(stoppingToken);
        
        using var timer = new PeriodicTimer(TimeSpan.FromSeconds(3));
        while (!stoppingToken.IsCancellationRequested && await timer.WaitForNextTickAsync(stoppingToken))
        {
            await jobs.TickAsync();
        }
    }
}
```

Fortunately we were able reuse the same `IBackgroundJobs` interface, Data Models, and API Service Contracts 
which greatly simplifies any migration efforts from SQLite's **ServiceStack.Jobs** implementation.

By implementing the same API Service Contracts (i.e. Request/Response DTOs) we're also able to reuse the same 
[built-in](/auto-ui) Management UI to provide real-time monitoring, inspection and management of background jobs:

:::youtube 2Cza_a_rrjA
Durable C# Background Jobs and Scheduled Tasks for .NET
:::

## RDBMS Optimizations

A key benefit of using SQLite for Background Jobs was the ability to easily maintain completed and failed job history in 
separate **monthly databases**. This approach prevented the main application database from growing unbounded by archiving 
historical job data into isolated monthly SQLite database files (e.g., `jobs_2025-01.db`, `jobs_2025-02.db`). 
These monthly databases could be easily backed up, archived to cold storage, or deleted after a retention period, 
providing a simple yet effective data lifecycle management strategy.

For the new **DatabaseJobFeature** supporting PostgreSQL, SQL Server, and MySQL, we've replicated this monthly 
partitioning strategy using **monthly partitioned SQL tables** for the `CompletedJob` and `FailedJob` archive tables.

### PostgreSQL - Native Table Partitioning

PostgreSQL provides native support for table partitioning, allowing us to automatically create monthly partitions using 
`PARTITION BY RANGE` on the `CreatedDate` column. The `DatabaseJobFeature` automatically creates new monthly partitions 
as needed, maintaining the same logical separation as SQLite's monthly .db's while keeping everything within a single 
Postgres DB:

```sql
CREATE TABLE CompletedJob (
    -- columns...
    CreatedDate TIMESTAMP NOT NULL,
    PRIMARY KEY ("Id","CreatedDate")
) PARTITION BY RANGE ("CreatedDate");

-- Monthly partitions are automatically created, e.g.:
CREATE TABLE CompletedJob_2025_01 PARTITION OF CompletedJob
    FOR VALUES FROM ('2025-01-01') TO ('2025-02-01');
```

This provides excellent query performance since PostgreSQL can use partition pruning to only scan relevant monthly partitions 
when filtering by `CreatedDate`.

### SQLServer / MySQL - Manual Partition Management

For **SQL Server** and **MySQL**, monthly partitioned tables need to be created **out-of-band** 
(either manually or via cronjob scripts) since they don't support the same level of automatic 
partition management as PostgreSQL. However, this still works well in practice as it uses:

1. **Write-Only Tables** - The `CompletedJob` and `FailedJob` tables are write-only append tables. Jobs are never updated after completion or failure, only inserted.

2. **CreatedDate Index** - All queries against these tables use the `CreatedDate` indexed column for filtering and sorting, ensuring efficient access patterns even as the tables grow.

The indexed `CreatedDate` column ensures that queries remain performant regardless of table size, and the write-only 
nature means there's no complex update logic to manage across partitions.

This approach maintains the same benefits as SQLite's monthly databases - easy archival, manageable table sizes,
and efficient queries - while leveraging the scalability and features of enterprise RDBMS systems.

### Separate Jobs Database

Or if preferred, you can maintain background jobs in a **separate database** from your main application database. 
This separation keeps the write-heavy job processing load off your primary database, allowing you to optimize 
each database independently for its specific workload patterns like maintaining different backup strategies
for your critical application data vs. job history. 

```csharp
// Configure.Db.cs
services.AddOrmLite(options => options.UsePostgres(connectionString))
        .AddPostgres("jobs", jobsConnectionString);

// Configure.BackgroundJobs.cs
services.AddPlugin(new DatabaseJobFeature {
    NamedConnection = "jobs"
});
```

### Real Time Admin UI

The Jobs Admin UI provides a real time view into the status of all background jobs including their progress, completion times, 
Executed, Failed, and Cancelled Jobs, etc. which is useful for monitoring and debugging purposes.

[![](/img/pages/jobs/jobs-dashboard.webp)](/img/pages/jobs/jobs-dashboard.webp)

View Real-time progress of queued Jobs

[![](/img/pages/jobs/jobs-queue.webp)](/img/pages/jobs/jobs-queue.webp)

View real-time progress logs of executing Jobs

[![](/img/pages/jobs/jobs-logs.webp)](/img/pages/jobs/jobs-logs.webp)

View Job Summary and Monthly Databases of Completed and Failed Jobs

[![](/img/pages/jobs/jobs-completed.webp)](/img/pages/jobs/jobs-completed.webp)

View full state and execution history of each Job

[![](/img/pages/jobs/jobs-failed.webp)](/img/pages/jobs/jobs-failed.webp)

Cancel Running jobs and Requeue failed jobs

## Usage

For even greater reuse of your APIs you're able to queue your existing ServiceStack Request DTOs
as a Background Job in addition to [Commands](https://docs.servicestack.net/commands) 
for encapsulating units of logic into internal invokable, inspectable and auto-retryable building blocks.

### Queue Commands

Any API, Controller or Minimal API can execute jobs with the `IBackgroundJobs` dependency, e.g.
here's how you can run a background job to send a new email when an API is called in
any new Identity Auth template:

```csharp
class MyService(IBackgroundJobs jobs) : Service 
{
    public object Any(MyOrder request)
    {
        var jobRef = jobs.EnqueueCommand<SendEmailCommand>(new SendEmail {
            To = "my@email.com",
            Subject = $"Received New Order {request.Id}",
            BodyText = $"""
                       Order Details:
                       {request.OrderDetails.DumptTable()}
                       """,
        });
        //...
    }
}
```

Which records and immediately executes a worker to execute the `SendEmailCommand` with the specified
`SendEmail` Request argument. It also returns a reference to a Job which can be used later to query
and track the execution of a job.

### Queue APIs

Alternatively a `SendEmail` API could be executed with just the Request DTO:

```csharp
var jobRef = jobs.EnqueueApi(new SendEmail {
    To = "my@email.com",
    Subject = $"Received New Order {request.Id}",
    BodyText = $"""
               Order Details:
               {request.OrderDetails.DumptTable()}
               """,
});
```

Although Sending Emails is typically not an API you want to make externally available and would
want to [Restrict access](https://docs.servicestack.net/auth/restricting-services) or [limit usage to specified users](https://docs.servicestack.net/auth/identity-auth#declarative-validation-attributes).

In both cases the `SendEmail` Request is persisted into the Jobs SQLite database for durability
that gets updated as it progresses through the queue.

For execution the API or command is resolved from the IOC before being invoked with the Request.
APIs are executed via the [MQ Request Pipeline](https://docs.servicestack.net/order-of-operations)
and commands executed using the [Commands Feature](https://docs.servicestack.net/commands) where
they'll also be visible in the [Commands Admin UI](https://docs.servicestack.net/commands#command-admin-ui).

### Background Job Options

The behavior for each `Enqueue*` method for executing background jobs can be customized with
the following options:

- `Worker` - Serially process job using a named worker thread
- `Callback` - Invoke another command with the result of a successful job
- `DependsOn` - Execute jobs after successful completion of a dependent job
    - If parent job fails all dependent jobs are cancelled
- `UserId` - Execute within an Authenticated User Context
- `RunAfter` - Queue jobs that are only run after a specified date
- `RetryLimit` - Override default retry limit for how many attempts should be made to execute a job
- `TimeoutSecs` - Override default timeout for how long a job should run before being cancelled
- `RefId` - Allow clients to specify a unique Id (e.g Guid) to track job
- `Tag` - Group related jobs under a user specified tag
- `CreatedBy` - Optional field for capturing the owner of a job
- `BatchId` - Group multiple jobs with the same Id
- `ReplyTo` - Optional field for capturing where to send notification for completion of a Job
- `Args` - Optional String Dictionary of Arguments that can be attached to a Job

### Feature Overview

It packs most features needed in a Background Jobs solution including:

- Use your App's existing RDBMS (no other infrastructure dependencies)
- Execute existing APIs or versatile Commands
    - Commands auto registered in IOC
- Scheduled Reoccurring Tasks
    - Track Last Job Run
- Serially execute jobs with the same named Worker
- Queue Jobs dependent on successful completion of parent Job
- Queue Jobs to be executed after a specified Date
- Execute Jobs within the context of an Authenticated User
- Auto retry failed jobs on a default or per-job limit
- Timeout Jobs on a default or per-job limit
- Cancellable Jobs
- Requeue Failed Jobs
- Execute custom callbacks on successful execution of Job
- Maintain Status, Logs, and Progress of Executing Jobs
- Execute transitive (i.e. non-durable) jobs using named workers
- Attach optional `Tag`, `BatchId`, `CreatedBy`, `ReplyTo` and `Args` with Jobs

## Schedule Recurring Tasks

In addition to queueing jobs to run in the background, it also supports scheduling recurring tasks
to execute APIs or Commands at fixed intervals.

:::youtube DtB8KaXXMCM
Schedule your Reoccurring Tasks with Background Jobs!
:::

APIs and Commands can be scheduled to run at either a `TimeSpan` or
[CRON Expression](https://github.com/HangfireIO/Cronos?tab=readme-ov-file#cron-format) interval, e.g:

## CRON Expression Examples

```csharp
// Every Minute Expression
jobs.RecurringCommand<CheckUrlsCommand>(Schedule.Cron("* * * * *"));

// Every Minute Constant
jobs.RecurringCommand<CheckUrlsCommand>(Schedule.EveryMinute, new CheckUrls {
    Urls = urls
});
```

### CRON Format

You can use any **unix-cron format** expression supported by the [HangfireIO/Cronos](https://github.com/HangfireIO/Cronos) library:

```txt
|------------------------------- Minute (0-59)
|     |------------------------- Hour (0-23)
|     |     |------------------- Day of the month (1-31)
|     |     |     |------------- Month (1-12; or JAN to DEC)
|     |     |     |     |------- Day of the week (0-6; or SUN to SAT)
|     |     |     |     |
|     |     |     |     |
*     *     *     *     *
```

The allowed formats for each field include:

| Field            | Format of valid values                     |
|------------------|--------------------------------------------|
| Minute           | 0-59                                       |
| Hour             | 0-23                                       |
| Day of the month | 1-31                                       |
| Month            | 1-12 (or JAN to DEC)                       |
| Day of the week  | 0-6 (or SUN to SAT; or 7 for Sunday)       |

#### Matching all values

To match all values for a field, use the asterisk: `*`, e.g here are two examples in which the minute field is left unrestricted:

- `* 0 1 1 1` - the job runs every minute of the midnight hour on January 1st and Mondays.
- `* * * * *` - the job runs every minute (of every hour, of every day of the month, of every month, every day of the week, because each of these fields is unrestricted too).

#### Matching a range

To match a range of values, specify your start and stop values, separated by a hyphen (-). Do not include spaces in the range. Ranges are inclusive. The first value must be less than the second.

The following equivalent examples run at midnight on Mondays, Tuesdays, Wednesdays, Thursdays, and Fridays (for all months):

- `0 0 * * 1-5`
- `0 0 * * MON-FRI`

#### Matching a list

Lists can contain any valid value for the field, including ranges. Specify your values, separated by a comma (,). Do not include spaces in the list, e.g:

- `0 0,12 * * *` - the job runs at midnight and noon.
- `0-5,30-35 * * * *` - the job runs in each of the first five minutes of every half hour (at the top of the hour and at half past the hour).

### TimeSpan Interval Examples

```csharp
jobs.RecurringCommand<CheckUrlsCommand>(
    Schedule.Interval(TimeSpan.FromMinutes(1)));

// With Example
jobs.RecurringApi(Schedule.Interval(TimeSpan.FromMinutes(1)), new CheckUrls {
    Urls = urls
});
```

That can be registered with an optional **Task Name** and **Background Options**, e.g:

```csharp
jobs.RecurringCommand<CheckUrlsCommand>("Check URLs", Schedule.EveryMinute, 
   new() {
       RunCommand = true // don't persist job
   });
```

:::info
If no name is provided, the Command's Name or APIs Request DTO will be used
:::

### Idempotent Registration

Scheduled Tasks are idempotent where the same registration with the same name will
either create or update the scheduled task registration without losing track of the
last time the Recurring Task, as such it's recommended to always define your App's
Scheduled Tasks on Startup:

```csharp
public class ConfigureBackgroundJobs : IHostingStartup
{
   public void Configure(IWebHostBuilder builder) => builder
     .ConfigureServices((context,services) => {
         //...
     }).ConfigureAppHost(afterAppHostInit: appHost => {
         var services = appHost.GetApplicationServices();
         var jobs = services.GetRequiredService<IBackgroundJobs>();
         
         // App's Scheduled Tasks Registrations:
         jobs.RecurringCommand<MyCommand>(Schedule.Hourly);
     });
}
```

## Interned Cronos

A major source of friction in .NET Libraries and most Frameworks from all platforms in general is dependency conflicts.
E.g. Conflicting versions of JSON.NET have plagued many a .NET library and framework for several years, something that 
never impacted ServiceStack Apps since we maintain our own fast/flexible JSON Serializer and have never had a dependency 
to JSON.NET.

As supply chain attacks from external OSS libraries have become more common, it's even more important to avoid 
taking dependencies on external libraries where possible.

As we now have multiple packages that referenced 
[Hangfire's Cronos](https://github.com/HangfireIO/Cronos) library we've decided to intern it in ServiceStack, 
removing the previous dependency **ServiceStack.Jobs** had to Cronos. The only issue was that
[CronParser.cs](https://github.com/HangfireIO/Cronos/blob/main/src/Cronos/CronParser.cs) uses unsafe parsing and we
don't allow `<AllowUnsafeBlocks>` in any ServiceStack package, so it was rewritten to use Spans in our interned
[CronParser.cs](https://github.com/ServiceStack/ServiceStack/blob/main/ServiceStack/src/ServiceStack.Common/Cronos/CronParser.cs) 
implementation. 

It's released under the same MIT License as Cronos so anyone else is welcome to use it, as is our port of their
[CronExpressionTests.cs](https://github.com/ServiceStack/ServiceStack/blob/main/ServiceStack/tests/ServiceStack.Common.Tests/CronExpressionTests.cs)
to NUnit.

## Background Jobs Admin UI

The last job the Recurring Task ran is also viewable in the Jobs Admin UI:

[![](/img/pages/jobs/jobs-scheduled-tasks-last-job.webp)](/img/pages/jobs/jobs-scheduled-tasks-last-job.webp)

### Executing non-durable jobs

`IBackgroundJobs` also supports `RunCommand*` methods for executing background jobs transiently
(i.e. non-durable), which is useful for commands that want to be serially executed by a named worker
but don't need to be persisted.

#### Execute in Background and return immediately

You could use this to queue system emails to be sent by the same **smtp** worker and are happy to
not have its state and execution history tracked in the Jobs database.

```csharp
var job = jobs.RunCommand<SendEmailCommand>(new SendEmail { ... }, 
    new() {
        Worker = "smtp"
    });
```

In this case `RunCommand` returns the actual `BackgroundJob` instance that will be updated by
the worker.

#### Execute in Background and wait for completion

You can also use `RunCommandAsync` if you prefer to wait until the job has been executed. Instead
of a Job it returns the **Result** of the command if it returned one.

```csharp
var result = await jobs.RunCommandAsync<SendEmailCommand>(new SendEmail {...}, 
    new() {
        Worker = "smtp"
    });
```

### Serially Execute Jobs with named Workers

By default jobs are executed immediately in a new Task, we can also change the behavior to
instead execute jobs one-by-one in a serial queue by specifying them to use the same named
worker as seen in the example above.

Alternatively you can annotate the command with the `[Worker]` attribute if you **always** want
all jobs executing the command to use the same worker:

```csharp
[Worker("smtp")]
public class SendEmailCommand(IBackgroundJobs jobs) : SyncCommand<SendEmail>
{
    //...
}
```

### Use Callbacks to process the results of Commands

Callbacks can be used to extend the lifetime of a job to include processing a callback to process its results.
This is useful where you would like to reuse the the same command but handle the results differently,
e.g. the same command can email results or invoke a webhook by using a callback:

```csharp
jobs.EnqueueCommand<CheckUrlsCommand>(new CheckUrls { Urls = allUrls },
    new() {
        Callback = nameof(EmailUrlResultsCommand),
    });

jobs.EnqueueCommand<CheckUrlsCommand>(new CheckUrls { Urls = criticalUrls },
    new() {
        Callback = nameof(WebhookUrlResultsCommand),
        ReplyTo = callbackUrl
    });
```

Callbacks that fail are auto-retried the same number of times as their jobs, which if they all fail then
the entire job is also marked as failed.

### Run Job dependent on successful completion of parent

Jobs can be queued to only run after the successful completion of another job, this is useful
for when you need to kick off multiple jobs after a long running task has finished like
generating monthly reports after monthly data has been aggregated, e.g:

```csharp
var jobRef = jobs.EnqueueCommand<AggregateMonthlyDataCommand>(new Aggregate {
    Month = DateTime.UtcNow
});

jobs.EnqueueCommand<GenerateSalesReportCommand>(new () {
   DependsOn = jobRef.Id,
});

jobs.EnqueueCommand<GenerateExpenseReportCommand>(new () {
   DependsOn = jobRef.Id,
});
```

Inside your command you can get a reference to your current job with `Request.GetBackgroundJob()`
which will have its `ParentId` populated with the parent job Id and `job.ParentJob` containing
a reference to the completed Parent Job where you can access its Request, Results, and other job
information:

```csharp
public class GenerateSalesReportCommand(ILogger<MyCommandNoArgs> log) 
    : SyncCommand
{
    protected override void Run()
    {
        var job = Request.GetBackgroundJob();
        var parentJob = job.ParentJob;
    }
}
```

### Atomic Batching Behavior

We can also use `DependsOn` to implement atomic batching behavior where from inside our
executing command we can queue new jobs that are dependent on the successful execution
of the current job, e.g:

```csharp
public class CheckUrlsCommand(IHttpClientFactory factory, IBackgroundJobs jobs)
    : AsyncCommand<CheckUrls>
{
    protected override async Task RunAsync(CheckUrls req, CancellationToken ct)
    {
        var job = Request.GetBackgroundJob();

        var batchId = Guid.NewGuid().ToString("N");
        using var client = factory.CreateClient();
        foreach (var url in req.Urls)
        {
            var msg = new HttpRequestMessage(HttpMethod.Get, url);
            var response = await client.SendAsync(msg, ct);
            response.EnsureSuccessStatusCode();
      
            jobs.EnqueueCommand<SendEmailCommand>(new SendEmail {
                To = "my@email.com",
                Subject = $"{new Uri(url).Host} status",
                BodyText = $"{url} is up",
            }, new() {
                DependsOn = job.Id,
                BatchId = batchId,
            });
        }
    }
}
```

Where any dependent jobs are only executed if the job was successfully completed.
If instead an exception was thrown during execution, the job will be failed and
all its dependent jobs cancelled and removed from the queue.

### Executing jobs with an Authenticated User Context

If you have existing logic dependent on a Authenticated `ClaimsPrincipal` or ServiceStack
`IAuthSession` you can have your APIs and Commands also be executed with that user context
by specifying the `UserId` the job should be executed as:

```csharp
var openAiRequest = new CreateOpenAiChat {
   Request = new() {
       Model = "gpt-4",
       Messages = [
           new() {
               Content = request.Question
           }
       ]
   },
}; 

// Example executing API Job with User Context
jobs.EnqueueApi(openAiRequest, 
    new() {
      UserId = Request.GetClaimsPrincipal().GetUserId(),
      CreatedBy = Request.GetClaimsPrincipal().GetUserName(),
   });

// Example executing Command Job with User Context
jobs.EnqueueCommand<CreateOpenAiChatCommand>(openAiRequest, 
    new() {
      UserId = Request.GetClaimsPrincipal().GetUserId(),
      CreatedBy = Request.GetClaimsPrincipal().GetUserName(),
   });
```

Inside your API or Command you access the populated User `ClaimsPrincipal` or
ServiceStack `IAuthSession` using the same APIs that you'd use inside your ServiceStack APIs, e.g:

```csharp
public class CreateOpenAiChatCommand(IBackgroundJobs jobs) 
    : AsyncCommand<CreateOpenAiChat>
{
    protected override async Task RunAsync(
        CreateOpenAiChat request, CancellationToken token)
    {
        var user = Request.GetClaimsPrincipal();
        var session = Request.GetSession();
        //...
    }
}
```

### Queue Job to run after a specified date

Using `RunAfter` lets you queue jobs that are only executed after a specified `DateTime`,
useful for executing resource intensive tasks at low traffic times, e.g:

```csharp
var jobRef = jobs.EnqueueCommand<AggregateMonthlyDataCommand>(new Aggregate {
       Month = DateTime.UtcNow
   }, 
   new() {
       RunAfter = DateTime.UtcNow.Date.AddDays(1)
   });
```

### Attach Metadata to Jobs

All above Background Job Options have an effect on when and how Jobs are executed.
There are also a number of properties that can be attached to a Job that can be useful
in background job processing despite not having any effect on how jobs are executed.

These properties can be accessed by commands or APIs executing the Job and are visible
and can be filtered in the Jobs Admin UI to help find and analyze executed jobs.

```csharp
var jobRef = jobs.EnqueueCommand<CreateOpenAiChatCommand>(openAiRequest, 
   new() {
      // Group related jobs under a common tag
      Tag = "ai",
      // A User-specified or system generated unique Id to track the job
      RefId = request.RefId,
      // Capture who created the job
      CreatedBy = Request.GetClaimsPrincipal().GetUserName(),
      // Link jobs together that are sent together in a batch
      BatchId = batchId,
      // Capture where to notify the completion of the job to
      ReplyTo = "https:example.org/callback",
      // Additional properties about the job that aren't in the Request  
      Args = new() {
          ["Additional"] = "Metadata"
      }
   });
```

### Querying a Job

A job can be queried by either it's auto-incrementing `Id` Primary Key or by a unique `RefId`
that can be user-specified.

```csharp
var jobResult = jobs.GetJob(jobRef.Id);

var jobResult = jobs.GetJobByRefId(jobRef.RefId);
```

At a minimum a `JobResult` will contain the Summary Information about a Job as well as the
full information about a job depending on where it's located:

```csharp
class JobResult
{
    // Summary Metadata about a Job in the JobSummary Table 
    JobSummary Summary
    // Job that's still in the BackgroundJob Queue
    BackgroundJob? Queued
    // Full Job information in Monthly DB CompletedJob Table
    CompletedJob? Completed
    // Full Job information in Monthly DB FailedJob Table
    FailedJob? Failed
    // Helper to access full Job Information
    BackgroundJobBase? Job => Queued ?? Completed ?? Failed 
}
```

### Job Execution Limits

Default Retry and Timeout Limits can be configured on the `DatabaseJobFeature`:

```csharp
services.AddPlugin(new DatabaseJobFeature
{
   DefaultRetryLimit = 2,
   DefaultTimeout = TimeSpan.FromMinutes(10),
});
```

These limits are also overridable on a per-job basis, e.g:

```csharp
var jobRef = jobs.EnqueueCommand<AggregateMonthlyDataCommand>(new Aggregate {
       Month = DateTime.UtcNow
   }, 
   new() {
      RetryLimit = 3,
      Timeout = TimeSpan.FromMinutes(30),
   });
```

### Logging, Cancellation an Status Updates

We'll use the command for checking multiple URLs to demonstrate some recommended patterns
and how to enlist different job processing features.

```csharp
public class CheckUrlsCommand(
    ILogger<CheckUrlsCommand> logger,
    IBackgroundJobs jobs,
    IHttpClientFactory clientFactory) : AsyncCommand<CheckUrls>
{
    protected override async Task RunAsync(CheckUrls req, CancellationToken ct)
    {
        // 1. Create Logger that Logs and maintains logging in Jobs DB
        var log = Request.CreateJobLogger(jobs,logger);

        // 2. Get Current Executing Job
        var job = Request.GetBackgroundJob();

        var result = new CheckUrlsResult {
            Statuses = new()
        };
        using var client = clientFactory.CreateClient();
        for (var i = 0; i < req.Urls.Count; i++)
        {
            // 3. Stop processing Job if it's been cancelled 
            ct.ThrowIfCancellationRequested();

            var url = req.Urls[i];
            try
            {
                var msg = new HttpRequestMessage(HttpMethod.Get,url);
                var response = await client.SendAsync(msg, ct);

                result.Statuses[url] = response.IsSuccessStatusCode;
                log.LogInformation("{Url} is {Status}",
                    url, response.IsSuccessStatusCode ? "up" : "down");

                // 4. Optional: Maintain explicit progress and status updates
                log.UpdateStatus(i/(double)req.Urls.Count,$"Checked {i} URLs");
            }
            catch (Exception e)
            {
                log.LogError(e, "Error checking {Url}", url);
                result.Statuses[url] = false;
            }
        }

        // 5. Send Results to WebHook Callback if specified
        if (job.ReplyTo != null)
        {
            jobs.EnqueueCommand<NotifyCheckUrlsCommand>(result,
                new() {
                    ParentId = job.Id,
                    ReplyTo = job.ReplyTo,
                });
        }
    }
}
```

We'll cover some of the notable parts useful when executing Jobs:

#### 1. Job Logger

We can use a Job logger to enable database logging that can be monitored in real-time in the
Admin Jobs UI. Creating it with both `BackgroundJobs` and `ILogger` will return a combined
logger that both Logs to standard output and to the Jobs database:

```csharp
var log = Request.CreateJobLogger(jobs,logger);
```

Or just use `Request.CreateJobLogger(jobs)` to only save logs to the database.

#### 2. Resolve Executing Job

If needed the currently executing job can be accessed with:

```csharp
var job = Request.GetBackgroundJob();
```

Where you'll be able to access all the metadata the jobs were created with including `ReplyTo`
and `Args`.

#### 3. Check if Job has been cancelled

To be able to cancel a long running job you'll need to periodically check if a Cancellation
has been requested and throw a `TaskCanceledException` if it has to short-circuit the command
which can be done with:

```csharp
ct.ThrowIfCancellationRequested();
```

You'll typically want to call this at the start of any loops to prevent it from doing any more work.

#### 4. Optionally record progress and status updates

By default Background Jobs looks at the last API or Command run and worker used to estimate
the duration and progress for how long a running job will take.

If preferred your command can explicitly set a more precise progress and optional status update
that should be used instead, e.g:

```csharp
log.UpdateStatus(progress:i/(double)req.Urls.Count, $"Checked {i} URLs");
```

Although generally the estimated duration and live logs provide a good indication for the progress
of a job.

#### 5. Notify completion of Job

Calling a Web Hook is a good way to notify externally initiated job requests of the completion
of a job. You could invoke the callback within the command itself but there are a few benefits
to initiating another job to handle the callback:

- Frees up the named worker immediately to process the next task
- Callbacks are durable, auto-retried and their success recorded like any job
- If a callback fails the entire command doesn't need to be re-run again

We can queue a callback with the result by passing through the `ReplyTo` and link it to the
existing job with:

```csharp
if (job.ReplyTo != null)
{
   jobs.EnqueueCommand<NotifyCheckUrlsCommand>(result,
       new() {
           ParentId = job.Id,
           ReplyTo = job.ReplyTo,
       });
}
```

Which we can implement by calling the `SendJsonCallbackAsync` extension method with the
Callback URL and the Result DTO it should be called with:

```csharp
public class NotifyCheckUrlsCommand(IHttpClientFactory clientFactory) 
    : AsyncCommand<CheckUrlsResult>
{
    protected override async Task RunAsync(
        CheckUrlsResult request, CancellationToken token)
    {
        await clientFactory.SendJsonCallbackAsync(
            Request.GetBackgroundJob().ReplyTo, request, token);
    }
}
```

#### Callback URLs

`ReplyTo` can be any URL which by default will have the result POST'ed back to the URL with a JSON
Content-Type. Typically URLs will contain a reference Id so external clients can correlate a callback
with the internal process that initiated the job. If the callback API is publicly available you'll
want to use an internal Id that can't be guessed so the callback can't be spoofed, like a Guid, e.g:

:::copy
`https://api.example.com?refId={RefId}`
:::

If needed the callback URL can be customized on how the HTTP Request callback is sent.

You can change the HTTP Method used by including it before the URL:

:::copy
`PUT https://api.example.com`
:::

If the auth part contains a colon `:` it's treated as Basic Auth:

:::copy
`username:password@https://api.example.com`
:::


If name starts with `http.` sends a HTTP Header

:::copy
`http.X-API-Key:myApiKey@https://api.example.com`
:::

Otherwise it's sent as a Bearer Token:

:::copy
`myToken123@https://api.example.com`
:::

Bearer Token or HTTP Headers starting with `$` is substituted with Environment Variable if exists:

:::copy
`$API_TOKEN@https://api.example.com`
:::

When needed headers, passwords, and tokens can be URL encoded if they contain any delimiter characters.

## Implementing Commands

At a minimum a command need only implement the [IAsyncCommand interface](https://docs.servicestack.net/commands#commands-feature):

```csharp
public interface IAsyncCommand<in T>
{
    Task ExecuteAsync(T request);
}
```

Which is the singular interface that can execute any command.

However commands executed via Background Jobs have additional context your commands may need to
access during execution, including the `BackgroundJob` itself, the `CancellationToken` and
an Authenticated User Context.

To reduce the effort in creating commands with a `IRequest` context we've added a number ergonomic
base classes to better capture the different call-styles a unit of logic can have including
**Sync** or **Async** execution, whether they require **Input Arguments** or have **Result Outputs**.

Choosing the appropriate Abstract base class benefits from IDE tooling in generating the method
signature that needs to be implemented whilst Async commands with Cancellation Tokens in its method
signature highlights any missing async methods that are called without the token.

### Sync Commands

- `SyncCommand` - Requires No Arguments
- `SyncCommand<TRequest>` - Requires TRequest Argument
- `SyncCommandWithResult<TResult>` - Requires No Args and returns Result
- `SyncCommandWithResult<TReq,TResult>` - Requires Arg and returns Result

```csharp
public record MyArgs(int Id);
public record MyResult(string Message);

public class MyCommandNoArgs(ILogger<MyCommandNoArgs> log) : SyncCommand
{
    protected override void Run()
    {
        log.LogInformation("Called with No Args");
    }
}

public class MyCommandArgs(ILogger<MyCommandNoArgs> log) : SyncCommand<MyArgs>
{
    protected override void Run(MyArgs request)
    {
        log.LogInformation("Called with {Id}", request.Id);
    }
}

public class MyCommandWithResult(ILogger<MyCommandNoArgs> log) 
    : SyncCommandWithResult<MyResult>
{
    protected override MyResult Run()
    {
        log.LogInformation("Called with No Args and returns Result");
        return new MyResult("Hello World");
    }
}

public class MyCommandWithArgsAndResult(ILogger<MyCommandNoArgs> log) 
    : SyncCommandWithResult<MyArgs,MyResult>
{
    protected override MyResult Run(MyArgs request)
    {
        log.LogInformation("Called with {Id} and returns Result", request.Id);
        return new MyResult("Hello World");
    }
}
```

### Async Commands

- `AsyncCommand` - Requires No Arguments
- `AsyncCommand<TRequest>` - Requires TRequest Argument
- `AsyncCommandWithResult<TResult>` - Requires No Args and returns Result
- `AsyncCommandWithResult<TReq,TResult>` - Requires Arg and returns Result

```csharp
public class MyAsyncCommandNoArgs(ILogger<MyCommandNoArgs> log) : AsyncCommand
{
    protected override async Task RunAsync(CancellationToken token)
    {
        log.LogInformation("Async called with No Args");
    }
}

public class MyAsyncCommandArgs(ILogger<MyCommandNoArgs> log) 
    : AsyncCommand<MyArgs>
{
    protected override async Task RunAsync(MyArgs request, CancellationToken t)
    {
        log.LogInformation("Async called with {Id}", request.Id);
    }
}

public class MyAsyncCommandWithResult(ILogger<MyCommandNoArgs> log) 
    : AsyncCommandWithResult<MyResult>
{
    protected override async Task<MyResult> RunAsync(CancellationToken token)
    {
        log.LogInformation("Async called with No Args and returns Result");
        return new MyResult("Hello World");
    }
}

public class MyAsyncCommandWithArgsAndResult(ILogger<MyCommandNoArgs> log) 
    : AsyncCommandWithResult<MyArgs,MyResult>
{
    protected override async Task<MyResult> RunAsync(
        MyArgs request, CancellationToken token)
    {
        log.LogInformation("Called with {Id} and returns Result", request.Id);
        return new MyResult("Hello World");
    }
}
```

## RDBMS Request Logging and Analytics

This release also restores parity to **PostgreSQL**, **SQL Server** & **MySQL** RDBMS's for our previous 
SQLite-only features with the new `DbRequestLogger` which is a drop-in replacement for 
[SQLite Request Logging](https://docs.servicestack.net/sqlite-request-logs) for persisting API Request Logs to a RDBMS.

Whilst maintaining an archive of API Requests is nice, the real value of DB Request Logging is that it unlocks the 
comprehensive API Analytics and querying Logging available that was previously limited to SQLite Request Logs. 

:::youtube kjLcm1llC5Y
In Depth and Interactive API Analytics available to all ASP .NET Core ServiceStack Apps!
:::

### Benefits of API Analytics

They provide deep and invaluable insight into your System API Usage, device distribution, its Users, API Keys and the 
IPs where most traffic generates:

- **Visibility:** Provides a clear, visual summary of complex log data, making it easier to understand API usage and performance at a glance.
- **Performance Monitoring:** Helps track key metrics like request volume and response times to ensure APIs are meeting performance expectations.
- **User Understanding:** Offers insights into how users (and bots) are interacting with the APIs (devices, browsers).
- **Troubleshooting:** Aids in quickly identifying trends, anomalies, or specific endpoints related to issues.
- **Resource Planning:** Understanding usage patterns helps in scaling infrastructure appropriately.
- **Security Insight:** Identifying bot traffic and unusual request patterns can be an early indicator of security concerns.

### Interactive Analytics

Analytics are also interactive where you're able to drill down to monitor the activity of individual APIs, Users, API Keys 
and IPs which have further links back to the request logs which the summary analytics are derived from.

As they offer significant and valuable insights the `SqliteRequestLogger` is built into all ASP.NET Core 
IdentityAuth templates, to switch it over to use a RDBMS we recommend installing `db-identity` mix gist to
also replace SQLite BackgroundJobs with the RDBMS `DatabaseJobFeature`:

:::sh
x mix db-identity
:::

Or if you just want to replace SQLite Request Logs with a RDBMS use: 

:::sh
x mix db-requestlogs
:::

Or you can copy the [Modular Startup](https://docs.servicestack.net/modular-startup) script below: 

```csharp
[assembly: HostingStartup(typeof(MyApp.ConfigureRequestLogs))]

namespace MyApp;

public class ConfigureRequestLogs : IHostingStartup
{
    public void Configure(IWebHostBuilder builder) => builder
        .ConfigureServices((context, services) => {

            services.AddPlugin(new RequestLogsFeature {
                RequestLogger = new DbRequestLogger {
                    // NamedConnection = "<alternative db>"
                },
                EnableResponseTracking = true,
                EnableRequestBodyTracking = true,
                EnableErrorTracking = true
            });
            services.AddHostedService<RequestLogsHostedService>();

            if (context.HostingEnvironment.IsDevelopment())
            {
                services.AddPlugin(new ProfilingFeature());
            }
        });
}

public class RequestLogsHostedService(ILogger<RequestLogsHostedService> log, IRequestLogger requestLogger) : BackgroundService
{
    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
    {
        using var timer = new PeriodicTimer(TimeSpan.FromSeconds(3));
        if (requestLogger is IRequireAnalytics logger)
        {
            while (!stoppingToken.IsCancellationRequested && await timer.WaitForNextTickAsync(stoppingToken))
            {
                await logger.TickAsync(log, stoppingToken);
            }
        }
    }
}
```

### RDBMS Provider

When using a remote RDBMS, network latency becomes a primary concern that any solution needs to be designed around, 
as such the API Request Logs are initially maintained in an in memory collection before being flushed to the database 
**every 3 seconds** — configurable in the `PeriodicTimer` interval above.

To reduce the number of round-trips to the database, the `DbRequestLogger` batches all pending logs into a single 
request using [OrmLite's Bulk Inserts](https://docs.servicestack.net/ormlite/bulk-inserts) which is supported by all 
major RDBMS's.

### PostgreSQL Table Partitioning

PostgreSQL provides native support for table partitioning, allowing us to automatically create monthly partitions using 
`PARTITION BY RANGE` on the `CreatedDate` column. The `DbRequestLogger` automatically creates new monthly partitions 
as needed, maintaining the same logical separation as SQLite's monthly .db's while keeping everything within a single 
Postgres DB:

```sql
CREATE TABLE "RequestLog" (
    -- columns...
    "CreatedDate" TIMESTAMP NOT NULL,
    PRIMARY KEY ("Id","CreatedDate")
) PARTITION BY RANGE ("CreatedDate");

-- Monthly partitions are automatically created, e.g.:
CREATE TABLE "RequestLog_2025_01" PARTITION OF "RequestLog"
    FOR VALUES FROM ('2025-01-01') TO ('2025-02-01');
```

### SQLServer / MySQL - Manual Partition Management

For **SQL Server** and **MySQL**, monthly partitioned tables need to be created **out-of-band**
(either manually or via cronjob scripts) since they don't support the same level of automatic
partition management as PostgreSQL. However, this still works well in practice as because `RequestLog` is an 
**Append Only** table with all querying from the Admin UIs being filtered by its indexed `CreatedDate`
in monthly viewable snapshots like it was with SQLite.

### Separate RequestLog Database

Or if preferred, you can maintain request logs in a **separate database** from your main application database.
This separation keeps the write-heavy logging load off your primary database, allowing you to optimize 
each database independently for its specific workload patterns like maintaining different backup strategies
for your critical application data vs. log history.

```csharp
// Configure.Db.cs
services.AddOrmLite(options => options.UsePostgres(connectionString))
        .AddPostgres("logs", logsConnectionString);

// Configure.RequestLogs.cs
services.AddPlugin(new RequestLogsFeature {
    RequestLogger = new DbRequestLogger {
        NamedConnection = "logs"
    },
    //...
});
```

## Queryable Admin Logging UI

This will enable a more feature rich Request Logging Admin UI which utilizes the full queryability of the 
[AutoQueryGrid](https://docs.servicestack.net/vue/autoquerygrid) component to filter, sort and export Request Logs. 

[![](/img/pages/admin-ui/sqlitelogs.webp)](/img/pages/admin-ui/sqlitelogs.webp)

## Analytics Overview

Utilizing an `DbRequestLogger` also enables the **Analytics** Admin UI in the sidebar which initially
displays the API Analytics Dashboard:

:::{.wideshot}
[![](/img/pages/admin-ui/analytics-apis1.webp)](/img/pages/admin-ui/analytics-apis1.webp)
:::

### Distribution Pie Charts

Lets you quickly understand the composition of your user base and traffic sources and the 
distribution of users across different web browsers, device types, and to identify the proportion of traffic coming from automated bots. 

### Requests per day Line Chart

Lets you monitor API usage trends and performance over time. It tracks the total number of API requests and the average response 
time day-by-day. You can easily spot trends like peak usage hours/days, identify sudden spikes or drops in traffic, 
and correlate request volume with API performance which is crucial for capacity planning and performance troubleshooting.

### API tag groups Pie Chart

Lets you understand the usage patterns across different functional categories of your APIs.
By grouping API requests based on assigned tags (like Security, Authentication, User Management, Tech, etc.), you get a 
high-level view of which *types* of functionalities are most frequently used or are generating the most load. 

### API Requests Bar Chart

Lets you identify the most and least frequently used specific API endpoints which ranks individual API endpoints by 
the number of requests they receive. This helps pinpoint:
 
- **Critical Endpoints:** The most heavily used APIs that require robust performance and monitoring.
- **Optimization Targets:** High-traffic endpoints that could benefit from performance optimization.
- **Underutilized Endpoints:** APIs that might be candidates for deprecation or require promotion.
- **Troubleshooting:** If performance issues arise (seen in the line chart), this helps narrow down which specific endpoint might be responsible.

:::{.wideshot}
[![](/img/pages/admin-ui/analytics-apis2.webp)](/img/pages/admin-ui/analytics-apis2.webp)
:::

### Total Duration Bar Chart

Identifies which API endpoints consume the most *cumulative processing time* over the selected period.
Even if an API endpoint is relatively fast per call, if it's called extremely frequently, it can contribute significantly to overall server load.
Optimizing these can lead to significant savings in server resources (CPU, memory).

### Average Duration Bar Chart

Pinpoints which API endpoints are the slowest on a *per-request* basis. APIs at the top of this list are prime candidates 
for performance investigation and optimization, as they represent potential user-facing slowness or system bottlenecks.

### Requests by Duration Ranges Histogram

Provides an overview of the performance distribution for *all* API requests.
This chart shows how many requests fall into different speed buckets and helps you understand the overall responsiveness of your API system at a glance. 

## Individual API Analytics

Clicking on an API's bar chart displays a dedicated, detailed view of a single API endpoint's behavior, isolating its performance 
and usage patterns from the overall system metrics offering immediate insight into the endpoint's traffic volume and reliability.

:::{.wideshot}
[![](/img/pages/admin-ui/analytics-api.webp)](/img/pages/admin-ui/analytics-api.webp)
:::

### Total Requests

Displays the total requests for an API during the selected month. It includes HTTP Status Breakdown which
provide **direct access to the filtered request logs**. This is a major benefit for **rapid troubleshooting**, allowing 
you to instantly view the specific log entries corresponding to successful requests or particular error codes for this API.

### Last Request Information

Provides immediate context on the most recent activity for this endpoint with *when* the last request occurred, 
the source **IP address** and device information to help understand recent usage and check if the endpoint is still active, 
or quickly investigate the very last interaction if needed.

### Duration Summary Table (Total, Min, Max)

Quantifies the performance characteristics specifically for this endpoint with the cumulative (Total) processing load, 
the best-case performance (Min), and the worst-case performance (Max) which is useful for identifying performance outliers.

### Duration Requests Histogram

Visualizes the performance distribution for this API.

### Top Users Bar Chart

Identifies which authenticated users are most frequently calling this API and relies on this endpoint the most.
This can be useful for identifying power users, potential API abuse by a specific user account, or understanding the impact of changes to this API on key users.

### Top IP Addresses Bar Chart

Shows which source IP addresses are generating the most traffic for this API.
Useful for identifying high-volume clients, specific servers interacting with this endpoint, or potentially malicious IPs.

## Users

The **Users** tab will display the top 100 Users who make the most API Requests and lets you click on a Users bar chart
to view their individual User analytics.

:::{.wideshot}
[![](/img/pages/admin-ui/analytics-users.webp)](/img/pages/admin-ui/analytics-users.webp)
:::

### Individual User Analytics

Provides a comprehensive view of a single user's complete interaction history and behavior across all APIs they've accessed, 
shifting the focus from API performance to user experience and activity.

:::{.wideshot}
[![](/img/pages/admin-ui/analytics-user.webp)](/img/pages/admin-ui/analytics-user.webp)
:::

### User Info & Total Requests

Identifies the user and quantifies their overall activity level. Clicking on their ID or Name will navigate to the Users Admin UI.
It also shows their success/error rate via the clickable status code links. This helps gauge user engagement and baseline activity.

### Last Request Information

Offers a snapshot of the user's most recent interaction for immediate context.
Knowing **when**, **what** API they called, from which **IP address**, using which **client** & **device** is valuable 
for support, identifying their last action or checking recent activity.

### HTTP Status Pie Chart

Visualizes the overall success and error rate specifically for this user's API requests.

### Performance & Request Body Summary Table

Quantifies the performance experienced by this user and the data they typically send.

### Duration Requests Histogram

Shows the distribution of response times for requests made by this user to help understand the typical performance this user experiences.

### Top APIs Bar Chart

Reveals which API endpoints this user interacts with most frequently and help understanding user behavior and which features they use most.

### Top IP Addresses Bar Chart

Identifies the primary network locations or devices the user connects from.

### User Admin UI Analytics

To assist in discoverability a snapshot of a Users Analytics is also visible in the Users Admin UI:

[![](/img/pages/admin-ui/analytics-user-adminui.webp)](/img/pages/admin-ui/analytics-user-adminui.webp)

Clicking on **View User Analytics** takes you to the Users Analytics page to access to the full Analytics features and navigation.

## API Keys

The **API Keys** tab will display the top 100 API Keys who make the most API Requests and lets you click on an API Key 
bar chart to view its individual API Key analytics.

:::{.wideshot}
[![](/img/pages/admin-ui/analytics-apikeys.webp)](/img/pages/admin-ui/analytics-apikeys.webp)
:::

### Individual API Key Analytics

Provides comprehensive API Key analytics Similar to User Analytics but limited to the API Usage of a single API Key:

:::{.wideshot}
[![](/img/pages/admin-ui/analytics-apikey.webp)](/img/pages/admin-ui/analytics-apikey.webp)
:::

## IPs

The **IP Addresses** tab will display the top 100 IPs that make the most API Requests. Click on an IP's
bar chart to view its individual analytics made from that IP Address.

:::{.wideshot}
[![](/img/pages/admin-ui/analytics-ips.webp)](/img/pages/admin-ui/analytics-ips.webp)
:::

### Individual IP Analytics

Provides comprehensive IP Address analytics Similar to User Analytics but limited to the API Usage from a single IP Address:

:::{.wideshot}
[![](/img/pages/admin-ui/analytics-ip.webp)](/img/pages/admin-ui/analytics-ip.webp)
:::

## Protect same APIs with API Keys or Identity Auth

Modern APIs need to serve different types of clients, each with distinct authentication requirements. 
Understanding when to use **Identity Auth** versus **API Keys** is crucial to optimize for security, performance, 
and user experience.

### Two Auth Paradigms for Different Use Cases

### Identity Auth: User → API

**Identity Auth** is designed for scenarios where a **human user** is interacting with your API, typically through a 
web or mobile application which:

- Requires user credentials (username/password, OAuth, etc.)
- Establishes a user session with roles and permissions
- For interactive workflows like logins, password resets & email confirmation
- Enables user-specific features like profile management and personalized UX
- Provides full access to user context, claims, and role-based authorization

### API Keys: Machine → API / User Agent → API

**API Keys** are purpose-built for **machine-to-machine** communication or **user agents** accessing your 
API programmatically, without interactive user authentication. This authentication model:

- Provides simple, token-based authentication without user sessions
- Enables fine-grained access control through scopes and features
- Supports non-interactive scenarios like scripts, services, and integrations
- Can optionally be associated with a user but doesn't run in their context
- Offers superior performance by avoiding the auth workflow overhead
- Supports project based billing and usage metrics by API Key

**Common scenarios:**
- Microservices communicating with each other
- Third-party integrations accessing your API
- CLI tools and scripts that need API access
- Mobile apps or SPAs making direct API calls without user context
- Webhooks and automated processes
- Providing API access to partners or customers with controlled permissions

Despite serving 2 different use-cases there are a few times when you may want to serve the same API with both
Identity Auth and API Keys.

### Supporting both Auth Models with 2 APIs

Previously you would've needed to maintain two separate APIs, one protected with Identity Auth and another with API Keys.
Thanks to ServiceStack's message-based APIs and [built-in Auto Mapping](https://docs.servicestack.net/auto-mapping)
this is fairly easy to do:

```csharp
// For authenticated users
[ValidateIsAuthenticated]
public class QueryOrders : QueryDb<Order> { }

// For API key access
[ValidateApiKey]
public class QueryOrdersApiKey : QueryDb<Order> { }

public class OrderService : Service
{
    public List<Order> Get(GetOrders request)
    {
        var userId = Request.GetRequiredUserId();
        // Shared business logic
    }
    
    public List<Order> Get(GetOrdersViaApiKey request) => 
        Get(request.ConvertTo<GetOrders>());
}

public static class MyExtensions
{
    public static string GetRequiredUserId(this IRequest? req) =>
        req.GetApiKey()?.UserAuthId ??
        req.GetClaimsPrincipal().GetUserId() ?? 
        throw HttpError.Unauthorized("API Key must be associated with a user");
}
```

Whilst easy to implement, the biggest draw back with this approach is that it requires maintaining 2x APIs, 
2x API endpoints, and 2x API docs.

## The Best of Both Worlds

ServiceStack's flexible [API Keys feature](https://docs.servicestack.net/auth/apikeys) now allows you to protect 
the same APIs with **both** Identity Auth and API Keys, enabling you to:

- Maintain a single API surface for all clients
- Serve the same interactive UIs protected with Identity Auth or API Keys
- Provide programmatic access via API Keys
- Maintain all the benefits of API Keys

To achieve this, users will need to have a valid API Key generated for them which would then need to be added 
to the `apikey` Claim in the `UserClaimsPrincipalFactory` to be included in their Identity Auth Cookie:

```csharp
// Program.cs
services.AddScoped<IUserClaimsPrincipalFactory<ApplicationUser>, 
    AdditionalUserClaimsPrincipalFactory>();

// Add additional claims to the Identity Auth Cookie
public class AdditionalUserClaimsPrincipalFactory(
    UserManager<ApplicationUser> userManager,
    RoleManager<IdentityRole> roleManager,
    IApiKeySource apiKeySource,
    IOptions<IdentityOptions> optionsAccessor)
    : UserClaimsPrincipalFactory<ApplicationUser,IdentityRole>(
        userManager, roleManager, optionsAccessor)
{
  public override async Task<ClaimsPrincipal> CreateAsync(ApplicationUser user)
  {
      var principal = await base.CreateAsync(user);
      var identity = (ClaimsIdentity)principal.Identity!;
      
      var claims = new List<Claim>();
      if (user.ProfileUrl != null)
      {
          claims.Add(new Claim(JwtClaimTypes.Picture, user.ProfileUrl));
      }
      
      // Add Users latest valid API Key to their Auth Cookie's 'apikey' claim
      var latestKey = (await apiKeySource.GetApiKeysByUserIdAsync(user.Id))
          .OrderByDescending(x => x.CreatedDate)
          .FirstOrDefault();
      if (latestKey != null)
      {
          claims.Add(new Claim(JwtClaimTypes.ApiKey, latestKey.Key));
      }
      
      identity.AddClaims(claims);
      return principal;
  }
}
```

After which Authenticated Users will be able to access `[ValidateApiKey]` protected APIs where it attaches the 
API Key in the `apikey` Claim to the request - resulting in the same behavior had they sent their API Key with the request.

```csharp
// For authenticated users or API Keys
[ValidateApiKey]
public class QueryOrders : QueryDb<Order> { }
```

## AI Chat

We're excited to introduce **AI Chat** — a refreshingly simple solution for integrating AI into your applications 
by unlocking the full value of the OpenAI Chat API. Unlike most other OpenAI SDKs and Frameworks, all of AI Chat's 
features are centered around arguably the most important API in our time - OpenAI's simple [Chat Completion API](https://platform.openai.com/docs/api-reference/chat)
i.e. the primary API used to access Large Language Models (LLMs).

We've had several attempts at adding a valuable layer of functionality for harnessing AI into our Apps, including:
- [GptAgentFeature](https://servicestack.net/posts/chat-gpt-agents) - Use Semantic Kernel to implement Autonomous agents with Chain-of-Thought reasoning
- [TypeScript TypeChat](https://servicestack.net/posts/typescript-typechat-examples) - Use Semantic Kernel to implement all of TypeScript's TypeChat examples in .NET
- [ServiceStack.AI](https://servicestack.net/posts/servicestack-ai) - TypeChat providers and unified Abstractions over AWS, Azure and Google AI Providers

The problem being that we wouldn't consider any of these solutions to be relevant today, any "smarts" or opinionated
logic added look to become irrelevant as AI models get more capable and intelligent. 

## The Problem with Complex Abstractions

Over the years, we've seen AI integration libraries grow in complexity. Take 
[Microsoft Semantic Kernel](https://github.com/microsoft/semantic-kernel) - a sprawling codebase 
that maintains its own opinionated abstractions that aren't serializable and has endured several breaking changes 
over the years. After investing development effort in catching up with their breaking changes we're now told to
[Migrate to Agent Framework](https://learn.microsoft.com/en-us/agent-framework/migration-guide/from-semantic-kernel/).

The fundamental issue? These complex abstractions didn't prove to be reusable. Microsoft's own next competing solution
[Agent Framework](https://github.com/microsoft/agent-framework) - doesn't even use Semantic Kernel Abstractions. 
Instead, it maintains its own non-serializable complex abstractions, repeating the same architectural issues.

This pattern of building heavyweight, non-portable abstractions creates vendor lock-in, adds friction, hinders reuse,
and limits how and where it can be used. After getting very little value from Semantic Kernel, we don't plan for any 
rewrites to follow adoption of their next over-engineered framework. 

## Back to OpenAI Chat

The only AI Abstraction we feel confident that has any longevity in this space, that wont be subject to breaking changes 
and rewrites is the underlying OpenAI Chat Completion API itself. 

The API with the most utility, with all the hard work of having AI Providers adopt this common API already 
done for us, we just have to facilitate calling it.

Something so simple that it can be easily called from a shell script:

```bash
RESPONSE=$(curl https://api.openai.com/v1/chat/completions \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5",
    "messages": [{"role": "user", "content": "Capital of France?"}]
  }')

echo "$RESPONSE" | jq -r '.choices[0].message.content'
```

Shouldn't require complex libraries over several NuGet packages to make use of. 

The simplest and obvious solution is design around the core `ChatCompletion` DTO itself - a simple, serializable, 
implementation-free data structure that maps directly to the OpenAI Chat API request body maintained in 
[ChatCompletion.cs](https://github.com/ServiceStack/ServiceStack/blob/main/ServiceStack/src/ServiceStack.AI.Chat/ChatCompletion.cs)
with all its functionality encapsulated (no third-party dependencies) within the new **ServiceStack.AI.Chat** NuGet package.

Using DTOs gives us all the natural [advantages of message-based APIs](https://docs.servicestack.net/advantages-of-message-based-web-services) 
whose clean POCO models helps us [fight against complexity](https://docs.servicestack.net/service-complexity-and-dto-roles).

### Why This Matters

Because `ChatCompletion` is a plain serializable DTO, you can:

- **Store it in a database** - Save conversation history, audit AI requests, or implement retry logic
- **Use it in client workflows** - Pass the same DTO between frontend and backend without transformations
- **Send it through message queues** - Build asynchronous AI processing pipelines with RabbitMQ and others
- **Debug easily** - Inspect the exact JSON being sent to OpenAI
- **Test easily** - Mock AI responses with simple DTOs or JSON payloads
- **Use it outside the library** - The DTO works independently of any specific client implementation

More importantly, because it's a **Request DTO**, we unlock a wealth of ServiceStack features for free, 
since most of ServiceStack's functionality is designed around Request DTOs — which we'll explore later.

## Install

AI Chat can be added to any .NET 8+ project by installing the **ServiceStack.AI.Chat** NuGet package and configuration with:

:::sh
x mix chat
:::

Which drops this simple [Modular Startup](https://docs.servicestack.net/modular-startup) that adds the `ChatFeature`
and registers a link to its UI on the [Metadata Page](https://docs.servicestack.net/metadata-page) if you want it:

```csharp
public class ConfigureAiChat : IHostingStartup
{
    public void Configure(IWebHostBuilder builder) => builder
        .ConfigureServices(services => {
            services.AddPlugin(new ChatFeature());
             
            services.ConfigurePlugin<MetadataFeature>(feature => {
                feature.AddPluginLink("/chat", "AI Chat");
            });
       });
}
```

#### Prerequisites:

As AI Chat protects its APIs and UI with Identity Auth or API Keys, you'll need to enable the [API Keys Feature](https://docs.servicestack.net/auth/apikeys) if you haven't already:

:::sh
x mix apikeys
:::

## Simple, Not Simplistic

How simple is it to use? It's just as you'd expect, your App logic need only bind to a simple `IChatClient` interface
that accepts a Typed `ChatCompletion` Request DTO and returns a Typed `ChatResponse` DTO:

```csharp
public interface IChatClient
{
    Task<ChatResponse> ChatAsync(
        ChatCompletion request, CancellationToken token=default);
}
```

An impl-free easily substitutable interface for calling any OpenAI-compatible Chat API, using clean
Typed `ChatCompletion` and `ChatResponse` DTOs.

Unfortunately since the API needs to be typed and .NET Serializers don't have support for de/serializing union types
yet, the DTO adopts OpenAI's more verbose and flexible multi-part Content Type which looks like: 

```csharp
IChatClient client = CreateClient();

var request = new ChatCompletion
{
    Model = "gpt-5",
    Messages = [
        new() {
            Role = "user",
            Content = [
                new AiTextContent {
                    Type = "text", Text = "Capital of France?"
                }
            ],
        }
    ]
};

var response = await client.ChatAsync(request);
```

To improve the UX we've added a [Message.cs](https://github.com/ServiceStack/ServiceStack/blob/main/ServiceStack/src/ServiceStack.AI.Chat/Message.cs) helper
which encapsulates the boilerplate of sending **Text**, **Image**, **Audio** and **Files** into more 
succinct and readable code where you'd typically only need to write: 

```csharp
var request = new ChatCompletion
{
    Model = "gpt-5",
    Messages = [
        Message.SystemPrompt("You are a helpful assistant"),
        Message.Text("Capital of France?"),
    ]
};
var response = await client.ChatAsync(request);
string? answer = response.GetAnswer(); 
```

### Same ChatCompletion DTO, Used Everywhere

That's all that's required for your internal App Logic to access your App's configured AI Models. However, as 
AI Chat also makes its own OpenAI Compatible API available, your external .NET Clients can use the 
**same exact DTO** to get the **same Response** by calling your API with a 
[C# Service Client](https://docs.servicestack.net/csharp-client):

```csharp
var client = new JsonApiClient(BaseUrl) {
    BearerToken = apiKey
};
var response = await client.SendAsync(request);
```

### Support for Text, Images, Audio & Files

For Multi-modal LLMs which support it, you can also send Images, Audio & File attachments with your AI Request
using **URLs**, e.g:

```csharp
var image = new ChatCompletion
{
    Model = "qwen2.5vl",
    Messages = [
        Message.Image(imageUrl:"https://example.org/image.webp",
            text:"Describe the key features of the input image"),
    ]
}

var audio = new ChatCompletion
{
    Model = "gpt-4o-audio-preview",
    Messages = [
        Message.Audio(data:"https://example.org/speaker.mp3",
            text:"Please transcribe and summarize this audio file"),
    ]
};

var file = new ChatCompletion
{
    Model = "gemini-flash-latest",
    Messages = [
        Message.File(
            fileData:"https://example.org/order.pdf",
            text:"Please summarize this document"),
    ]
};
```

#### Relative File Path

If a [VirtualFiles Provider](https://docs.servicestack.net/virtual-file-system) was configured, you can specify a relative path instead:

```csharp
var image = new ChatCompletion
{
    Model = "qwen2.5vl",
    Messages = [
        Message.Image(imageUrl:"/path/to/image.webp",
            text:"Describe the key features of the input image"),
    ]
};
```

#### Manual Download & Embedding

Alternatively you can embed and send the raw Base64 Data or Data URI yourself:

```csharp
var bytes = await "https://example.org/image.webp".GetBytesFromUrlAsync();
var dataUri = $"data:image/webp;base64,{Convert.ToBase64String(bytes)}";
var image = new ChatCompletion
{
    Model = "qwen2.5vl",
    Messages = [
        Message.Image(imageUrl:dataUri,
            text:"Describe the key features of the input image"),
    ]
};
```

Although sending references to external resources allows keeping AI Requests payloads small, making them 
easier to store in Databases, send in MQs and client workflows, etc.

This illustrates some of the "value-added" features of AI Chat where it will automatically download any URL Resources
and embed it as Base64 Data in the `ChatCompletion` Request DTO.

### Configure Downloads

Relative paths can be enabled by configuring a `VirtualFiles` Provider to refer to a safe path that you want to allow 
access to.

Whilst URLs are downloaded by default, but its behavior can be customized with `ValidateUrl` or replaced entirely with 
`DownloadUrlAsBase64Async`: 

```csharp
services.AddPlugin(new ChatFeature {
    // Enable Relative Path Downloads
    VirtualFiles = new FileSystemVirtualFiles(assetDir),

    // Validate URLs before download
    ValidateUrl = url => {
        if (!IsAllowedUrl(url))
            throw HttpError.Forbidden("URL not allowed");
    },
    
    // Use Custom URL Downloader
    // DownloadUrlAsBase64Async = async (provider, url) => {
    //     var (base64, mimeType) = await MyDownloadAsync(url);
    //     return (base64, mimeType);
    // },
});
```

## Configure AI Providers

By default AI Chat is configured with a list of providers in its `llms.json`
which is pre-configured with the best models from the leading LLM providers.

The easiest way to use a custom `llms.json` is to add a local modified copy of
[llms.json](https://github.com/ServiceStack/ServiceStack/blob/main/ServiceStack/src/ServiceStack.AI.Chat/chat/llms.json) 
to your App's `/wwwroot/chat` folder:

```files
/wwwroot
  /chat
    llms.json
```

If you just need to change which providers are enabled you can specify them in `EnableProviders`:

```csharp
services.AddPlugin(new ChatFeature {
    // Specify which providers you want to enable
    EnableProviders =
    [
        "openrouter_free",
        "groq",
        "google_free",
        "codestral",
        "ollama",
        "openrouter",
        "google",
        "anthropic",
        "openai",
        "grok",
        "qwen",
        "z.ai",
        "mistral",
    ],

    // Use custom llms.json configuration
    ConfigJson = vfs.GetFile("App_Data/llms.json").ReadAllText(),
});
```

Alternatively you can use `ConfigJson` to load a custom JSON provider configuration from a different source, which 
you'll want to use if you prefer to keep your provider configuration and API Keys all in `llms.json`.

### llms.json - OpenAI Provider Configuration

[llms.json](https://github.com/ServiceStack/ServiceStack/blob/main/ServiceStack/src/ServiceStack.AI.Chat/chat/llms.json)
contains a list of OpenAI Compatible Providers you want to make available along with a user-defined **model alias**
you want to use for model routing along with the provider-specific model name it maps to when the model is used 
with that provider, e.g:

```json
{
  "providers": {
    "openrouter": {
      "enabled": false,
      "type": "OpenAiProvider",
      "base_url": "https://openrouter.ai/api",
      "api_key": "$OPENROUTER_API_KEY",
      "models": {
        "grok-4": "x-ai/grok-4",
        "glm-4.5-air": "z-ai/glm-4.5-air",
        "kimi-k2": "moonshotai/kimi-k2",
        "deepseek-v3.1:671b": "deepseek/deepseek-chat",
        "llama4:400b": "meta-llama/llama-4-maverick"
      }
    },
    "anthropic": {
      "enabled": false,
      "type": "OpenAiProvider",
      "base_url": "https://api.anthropic.com",
      "api_key": "$ANTHROPIC_API_KEY",
      "models": {
        "claude-sonnet-4-0": "claude-sonnet-4-0"
      }
    },
    "ollama": {
      "enabled": false,
      "type": "OllamaProvider",
      "base_url": "http://localhost:11434",
      "models": {},
      "all_models": true
    },
    "google": {
      "enabled": false,
      "type": "GoogleProvider",
      "api_key": "$GOOGLE_API_KEY",
      "models": {
        "gemini-flash-latest": "gemini-flash-latest",
        "gemini-flash-lite-latest": "gemini-flash-lite-latest",
        "gemini-2.5-pro": "gemini-2.5-pro",
        "gemini-2.5-flash": "gemini-2.5-flash",
        "gemini-2.5-flash-lite": "gemini-2.5-flash-lite"
      },
      "safety_settings": [
        {
          "category": "HARM_CATEGORY_DANGEROUS_CONTENT",
          "threshold": "BLOCK_ONLY_HIGH"
        }
      ],
      "thinking_config": {
        "thinkingBudget": 1024,
        "includeThoughts": true
      }
    },
    //...
  }
}
```

The only non-OpenAI Chat Provider AI Chat supports is `GoogleProvider`, where an exception was made to add explicit 
support for Gemini's Models given its low cost and generous free quotas.

### Provider API Keys

API Keys can be either be specified within the `llms.json` itself, alternatively API Keys starting with `$` like 
`$GOOGLE_API_KEY` will first try to resolve it from `Variables` before falling back to checking Environment Variables.

```csharp
services.AddPlugin(new ChatFeature {
    EnableProviders =
    [
        "openrouter",
        "anthropic",
        "google",
    ],
    Variables =
    {
        ["OPENROUTER_API_KEY"] = secrets.OPENROUTER_API_KEY,
        ["ANTHROPIC_API_KEY"] = secrets.ANTHROPIC_API_KEY,
        ["GOOGLE_API_KEY"] = secrets.GOOGLE_API_KEY,
    }
});
```

### Model Routing and Failover

Providers are invoked in the order they're defined in `llms.json` that supports the requested model. 
If a provider fails, it tries the next available provider.

This enables scenarios like:
- Routing different request types to different providers
- Optimize by Cost, Performance, Reliability, or Privacy
- A/B testing different models
- Added resilience with fallback when a provider is unavailable

The model aliases don't need to identify a model directly, e.g. you could use your own artificial names for use-cases 
you need like `image-captioner`, `audio-transcriber`, `pdf-extractor` then map them to different models different providers 
should use to achieve the desired task.

#### Use Model Routing with Fallback

To make use of the model routing and fallback you would call `ChatAsync` on `IChatClient` directly:

```csharp
class MyService(IChatClient client)
{
    public async Task<object> Any(DefaultChat request)
    {
        return await client.ChatAsync(new ChatCompletion {
            Model = "glm-4.6",
            Messages = [
                Message.Text(request.UserPrompt)
            ],
        });
    }
}
```

#### Use Specific Provider

Alternatively to use a specific provider, you can use `IChatClients` dependency `GetClient(providerId)` method 
to resolve the provider then calling `ChatAsync` will only use that provider:

```csharp
class MyService(IChatClients clients)
{
    public async Task<object> Any(ProviderChat request)
    {
        var groq = clients.GetClient("groq");
        return await groq.ChatAsync(new ChatCompletion {
            Model = "kimi-k2",
            Messages = [
                Message.Text(request.UserPrompt)
            ],
        });
    }
}
```

## Persist AI Chat History

By default AI Chat is designed to be minimally invasive and doesn't require anything other than the API Keys
needed to access the AI Models it should use. 

If preferred you can choose to persist AI Chat History made through the external ChatCompletion API with the
`OnChatCompletionSuccessAsync` and `OnChatCompletionFailedAsync` callbacks which can be used to store successful
and failed requests in your preferred data store using the included 
[ChatCompletionLog](https://github.com/ServiceStack/ServiceStack/blob/main/ServiceStack/src/ServiceStack.AI.Chat/ChatCompletionLog.cs)
or your own data model:

```csharp
public class ConfigureAiChat : IHostingStartup
{
    public void Configure(IWebHostBuilder builder) => builder
        .ConfigureServices(services => {
            services.AddPlugin(new ChatFeature
            {
                OnChatCompletionSuccessAsync = async (request, response, req) => {
                    using var db = await req.Resolve<IDbConnectionFactory>().OpenAsync();
                    await db.InsertAsync(req.ToChatCompletionLog(request, response));
                },
                OnChatCompletionFailedAsync = async (request, exception, req) => {
                    using var db = await req.Resolve<IDbConnectionFactory>().OpenAsync();
                    await db.InsertAsync(req.ToChatCompletionLog(request, exception));
                },
            });
       }).ConfigureAppHost(appHost => {
            using var db = appHost.Resolve<IDbConnectionFactory>().Open();
            db.CreateTableIfNotExists<ChatCompletionLog>();
       });
}
```

### Compatible with llms.py 

The other benefit of simple configuration and simple solutions, is that they're easy to implement. A perfect example
of this being that this is the 2nd implementation done using this configuration. The same configuration, UI, APIs
and functionality is also available in our [llms.py](https://github.com/ServiceStack/llms) Python CLI and server gateway we've developed 
in order to have a dependency-free LLM Gateway solution needed in our ComfyUI Agents.  

:::sh
pip install llms-py
:::

This also means you can use and test your own custom `llms.json` configuration on the command-line or in shell 
automation scripts:

```sh
# Simple question
llms "Explain quantum computing"

# With specific model
llms -m gemini-2.5-pro "Write a Python function to sort a list"

# With system prompt
llms -s "You are a helpful coding assistant" "Reverse a string in Python?"

# With image (vision models)
llms --image image.jpg "What's in this image?"
llms --image https://example.com/photo.png "Describe this photo"

# Display full JSON Response
llms "Explain quantum computing" --raw

# Start the UI and an OpenAI compatible API on port 8000:
llms --serve 8000
```

Incidentally as [llms.py UI](https://servicestack.net/posts/llms-py-ui) and AI Chat utilize the same UI you can 
use its **import/export** features to transfer your AI Chat History between them.

Checkout the [llms.py GitHub repo](https://github.com/ServiceStack/llms) for even more features.

## AI Chat UI

Another major value proposition of [AI Chat](https://servicestack.net/posts/ai-chat) is being able to offer a ChatGPT-like UI to your users where you're able to control the API Keys, billing, and sanctioned providers your users can access to maintain your own **Fast, Local, and Private** access to AI from within your own organization.

### Identity Auth or Valid API Key

AI Chat makes of ServiceStack's new [API Keys or Identity Auth APIs](https://servicestack.net/posts/apikey_auth_apis) which allows usage
for both Authenticated Identity Auth users otherwise unauthenticated users will need to provide a valid API Key:

:::{.shadow}
[![](/img/pages/ai-chat/ai-chat-ui-apikey.webp)](/img/pages/ai-chat/ai-chat-ui-apikey.webp)
:::

If needed `ValidateRequest` can be used to further restrict access to AI Chat's UI and APIs, e.g. you can restrict access to API Keys with the `Admin` scope with:

```csharp
services.AddPlugin(new ChatFeature {
    ValidateRequest = async req => 
        req.GetApiKey()?.HasScope(RoleNames.Admin) == true 
            ? null 
            : HttpResult.Redirect("/admin-ui"),
});
```

### Import / Export

All data is stored locally in the users local browser's IndexedDB. When needed you can backup and transfer your
entire chat history between different browsers using the **Export** and **Import** features on the home page.

:::{.wideshot}
[![llms-home.webp](/img/pages/ai-chat/llms-home.webp)](/img/pages/ai-chat/llms-home.webp)
:::

## Simple and Flexible UI

Like all of [ServiceStack's built-in UIs](https://servicestack.net/auto-ui), AI Chat is also [naturally customizable](https://docs.servicestack.net/locode/custom-overview)
where you can override any of [AI Chat's Vue Components](https://github.com/ServiceStack/ServiceStack/tree/main/ServiceStack/src/ServiceStack.AI.Chat/chat)
and override them with your own by placing them in your
[/wwwroot/chat](https://github.com/ServiceStack/ServiceStack/tree/main/ServiceStack/tests/AdhocNew/wwwroot/chat) folder:

```files
/wwwroot
  /chat
    Brand.mjs
    Welcome.mjs
```

Where you'll be able to customize the appearance and behavior of AI Chat's UI to match your App's branding and needs.

:::{.wideshot}
[![](/img/pages/ai-chat/ai-chat-custom-ui.webp)](/img/pages/ai-chat/ai-chat-custom-ui.webp)
:::

## Customize

The built-in [ui.json](https://github.com/ServiceStack/ServiceStack/blob/main/ServiceStack/src/ServiceStack.AI.Chat/chat/ui.json)
configuration can be overridden with your own to use your preferred system prompts and other defaults by adding them to your local folder:

```files
/wwwroot
  /chat
    llms.json
    ui.json
```

Alternatively `ConfigJson` and `UiConfigJson` can be used to load custom JSON configuration from a different source, e.g:

```csharp
services.AddPlugin(new ChatFeature {
    // Use custom llms.json configuration
    ConfigJson = vfs.GetFile("App_Data/llms.json").ReadAllText(),

    // Use custom ui.json configuration
    UiConfigJson = vfs.GetFile("App_Data/ui.json").ReadAllText(),
});

```

## Rich Markdown & Syntax Highlighting

To maximize readability there's full support for Markdown and Syntax highlighting for the most popular programming
languages.

:::{.wideshot}
[![llms-syntax.webp](/img/pages/ai-chat/llms-syntax.webp)](/img/pages/ai-chat/llms-syntax.webp)
:::

To quickly and easily make use of AI Responses, **Copy Code** icons are readily available on hover of all messages
and code blocks.

## Rich, Multimodal Inputs

The Chat UI goes beyond just text and can take advantage of the multimodal capabilities of modern LLMs
with support for Image, Audio, and File inputs.

### 🖼️ 1. Image Inputs & Analysis

Images can be uploaded directly into your conversations with vision-capable models for comprehensive image analysis.

Visual AI Responses are highly dependent on the model used. This is a typical example of the visual analysis provided by the latest Gemini Flash of our [ServiceStack Logo](/img/logo.png):

:::{.wideshot}
[![llms-image.webp](/img/pages/ai-chat/llms-image.webp)](/img/pages/ai-chat/llms-image.webp)
:::

### 🎤 2. Audio Input & Transcription

Likewise you can upload Audio files and have them transcribed and analyzed by multi-modal models with audio capabilities.

:::{.wideshot}
[![llms-audio.webp](/img/pages/ai-chat/llms-audio.webp)](/img/pages/ai-chat/llms-audio.webp)
:::

Example of processing audio input. Audio files can be uploaded with system and user prompts
to instruct the model to transcribe and summarize its content where its
multi-modal capabilities are integrated right within the chat interface.

### 📎 3. File and PDF Attachments

In addition to images and audio, you can also upload documents, PDFs, and other files to
capable models to extract insights, summarize content or analyze.

**Document Processing Use Cases:**
- **PDF Analysis**: Upload PDF documents for content extraction and analysis
- **Data Extraction**: Extract specific information from structured documents
- **Document Summarization**: Get concise summaries of lengthy documents
- **Query Content**: Ask questions about specific content in documents
- **Batch Processing**: Upload multiple files for comparative analysis

Perfect for research, document review, data analysis, and content extractions.

:::{.wideshot}
[![llms-files.webp](/img/pages/ai-chat/llms-files.webp)](/img/pages/ai-chat/llms-files.webp)
:::

## Custom AI Chat Requests

Send Custom Chat Completion requests through the settings dialog, allowing Users to fine-tune
their AI requests with advanced options including:

- **Temperature** `(0-2)` for controlling response randomness
- **Max Completion Tokens** to limit response length
- **Seed** values for deterministic sampling
- **Top P** `(0-1)` for nucleus sampling
- **Frequency** & **Presence Penalty** `(-2.0 to 2.0)` for reducing repetition
- **Stop** Sequences to control where the API stops generating
- **Reasoning Effort** constraints for reasoning models
- **Top Logprobs** `(0-20)` for token probability analysis
- **Verbosity** settings

:::{.wideshot}
[![llms-settings.webp](/img/pages/ai-chat/llms-settings.webp)](/img/pages/ai-chat/llms-settings.webp)
:::

## Enable / Disable Providers

**Admin** Users can manage which providers they want enabled or disabled at runtime.
Providers are invoked in the order they're defined in `llms.json` that supports the requested model.
If a provider fails, it tries the next available one.

By default `llms.json` defines providers with Free tiers first, followed by local providers and then 
premium cloud providers which can all be enabled or disabled from the UI:

:::{.wideshot}
[![llms-providers.webp](/img/pages/ai-chat/llms-providers.webp)](/img/pages/ai-chat/llms-providers.webp)
:::

## Search History

Quickly find past conversations with built-in search:

:::{.wideshot}
[![llms-search-python.webp](/img/pages/ai-chat/llms-search-python.webp)](/img/pages/ai-chat/llms-search-python.webp)
:::

## Smart Autocomplete for Models & System Prompts

Autocomplete components are used to quickly find and select the preferred model and system prompt.

Only models from enabled providers will appear in the drop down, which will be available immediately after
providers are enabled.

:::{.wideshot}
[![llms-autocomplete.webp](/img/pages/ai-chat/llms-autocomplete.webp)](/img/pages/ai-chat/llms-autocomplete.webp)
:::

## Comprehensive System Prompt Library

Access a curated collection of 200+ professional system prompts designed for various use cases, from technical assistance to creative writing.

:::{.wideshot}
[![llms-system-prompt.webp](/img/pages/ai-chat/llms-system-prompt.webp)](/img/pages/ai-chat/llms-system-prompt.webp)
:::

System Prompts be can added, removed & sorted in your `ui.json`

```json
{
  "prompts": [
    {
      "id": "it-expert",
      "name": "Act as an IT Expert",
      "value": "I want you to act as an IT expert. You will be responsible..."
    },
    ...
  ]
}
```

### Reasoning

Access the thinking process of advanced AI models with specialized rendering for reasoning and chain-of-thought responses:

:::{.wideshot}
[![llms-reasoning.webp](/img/pages/ai-chat/llms-reasoning.webp)](/img/pages/ai-chat/llms-reasoning.webp)
:::

We're excited to get AI Chat in customers hands. Please [let us know](https://servicestack.net/ideas) of any other missing features you'd love to see implemented.

## Creating a custom Explorer UI for OpenAIs Chat API

Anyone who's used ServiceStack's built-in [API Explorer](https://docs.servicestack.net/api-explorer) or 
[Auto HTML API](https://docs.servicestack.net/auto-html-api) UIs know that not all API Explorer UIs are created equal.

The differences are more pronounced as APIs get larger and more complex which we can see by comparing it with 
Swagger UI for rendering [AI Chat's](https://servicestack.net/posts/ai-chat) `ChatCompletion` API:

[![](/img/pages/ai-chat/ai-chat-swagger-form.webp)](/img/pages/ai-chat/ai-chat-swagger-form.webp)

This is just the tip of the iceberg, the [full-length Swagger UI Screenshot](/img/pages/ai-chat/ai-chat-swagger-long.webp)
is absurdly long, past the point of being usable. 

As expected from a generic UI we get very little assistance from the UI on what values are allowed, the numeric fields aren't number inputs and the only dropdowns we see are for `bool` properties to select from their `true` 
and `false` values. There's not going to be any chance for it to be able to show App-specific options like 
which models are currently enabled.

## API Explorer UI

By contrast here is the same API rendered with ServiceStack's [API Explorer](https://docs.servicestack.net/api-explorer):

[![](/img/pages/ai-chat/ai-chat-form.webp)](/img/pages/ai-chat/ai-chat-form.webp)

This is much closer to what you'd expect from a hand-crafted Application UI and far more usable. 

#### Properties use optimized UI Components

It renders an optimized UI for each property, with the **Model**, **Reasoning Effort**, **Service Tier** and **Verbosity** properties all using a [Combobox](https://docs.servicestack.net/vue/combobox) component for 
quickly searching through a list of supported options, or they can choose to enter a custom value. 

**Bool** properties use Checkboxes whilst Numeric fields use **number** inputs, with integer properties only allowing
integer values and floating point properties being able to step through fractional values.

#### UI-specific text hints

Each property also contains **placeholder** text and **help** text hints that's more focused and concise than the 
verbose API documentation.

#### HTML client-side validation

Client-side HTML validation ensure properties are valid and within any configured min/max values before any request is sent.

[![](/img/pages/ai-chat/ai-chat-form-completed.webp)](/img/pages/ai-chat/ai-chat-form-completed.webp)

### Custom Components for Complex Properties

The only property that doesn't use a built-in component is `Messages` which is rendered with a custom
`ChatMessages` component purpose-built to populate the `List<AiMessage> Messages` property. It uses a **Markdown Editor** 
for the UserPrompt, a collapsible Textarea for any System Prompt and the ability to attach **image**, **audio** & **file** 
document attachments to the API request.

## How is it done?

The entire UI is driven by these [declarative annotations](https://docs.servicestack.net/locode/declarative) added on the 
[ChatCompletion](https://github.com/ServiceStack/ServiceStack/blob/main/ServiceStack/src/ServiceStack.AI.Chat/ChatCompletion.cs)
Request DTO:

```csharp
[Description("Chat Completions API (OpenAI-Compatible)")]
[Notes("The industry-standard, message-based interface for interfacing with Large Language Models.")]
public class ChatCompletion : IPost, IReturn<ChatResponse>
{
    [DataMember(Name = "messages")]
    [Input(Type = "ChatMessages", Label=""), FieldCss(Field = "col-span-12")]
    public List<AiMessage> Messages { get; set; } = [];
    
    [DataMember(Name = "model")]
    [Input(Type = "combobox", EvalAllowableValues = "Chat.Models", Placeholder = "e.g. glm-4.6", Help = "ID of the model to use")]
    public string Model { get; set; }

    [DataMember(Name = "reasoning_effort")]
    [Input(Type="combobox", EvalAllowableValues = "['low','medium','high','none','default']", Help = "Constrains effort on reasoning for reasoning models")]
    public string? ReasoningEffort { get; set; }

    [DataMember(Name = "service_tier")]
    [Input(Type = "combobox", EvalAllowableValues = "['auto','default']", Help = "Processing type for serving the request")]
    public string? ServiceTier { get; set; }
    
    [DataMember(Name = "safety_identifier")]
    [Input(Type = "text", Placeholder = "e.g. user-id", Help = "Stable identifier to help detect policy violations")]
    public string? SafetyIdentifier { get; set; }
    
    [DataMember(Name = "stop")]
    [Input(Type = "tag", Max = "4", Help = "Up to 4 sequences for the API to stop generating tokens")]
    public List<string>? Stop { get; set; }
    
    [DataMember(Name = "modalities")]
    [Input(Type = "tag", Max = "3", Help = "The output types you would like the model to generate")]
    public List<string>? Modalities { get; set; }
    
    [DataMember(Name = "prompt_cache_key")]
    [Input(Type = "text", Placeholder = "e.g. my-cache-key", Help = "Used by OpenAI to cache responses for similar requests")]
    public string? PromptCacheKey { get; set; }
    
    [DataMember(Name = "tools")]
    public List<Tool>? Tools { get; set; }
    
    [DataMember(Name = "verbosity")]
    [Input(Type = "combobox", EvalAllowableValues = "['low','medium','high']", Placeholder = "e.g. low", Help = "Constrains verbosity of model's response")]
    public string? Verbosity { get; set; }
    
    [DataMember(Name = "temperature")]
    [Input(Type = "number", Step = "0.1", Min = "0", Max = "2", Placeholder = "e.g. 0.7", Help = "Higher values more random, lower for more focus")]
    public double? Temperature { get; set; }

    [DataMember(Name = "max_completion_tokens")]
    [Input(Type = "number", Value = "2048", Step = "1", Min = "1", Placeholder = "e.g. 2048", Help = "Max tokens for completion (inc. reasoning tokens)")]
    public int? MaxCompletionTokens { get; set; }

    [DataMember(Name = "top_logprobs")]
    [Input(Type = "number", Step = "1", Min = "0", Max = "20", Placeholder = "e.g. 5", Help = "Number of most likely tokens to return with log probs")]
    public int? TopLogprobs { get; set; }
    
    [DataMember(Name = "top_p")]
    [Input(Type = "number", Step = "0.1", Min = "0", Max = "1", Placeholder = "e.g. 0.5", Help = "Nucleus sampling - alternative to temperature")]
    public double? TopP { get; set; }

    [DataMember(Name = "frequency_penalty")]
    [Input(Type = "number", Step = "0.1", Min = "0", Max = "2", Placeholder = "e.g. 0.5", Help = "Penalize tokens based on frequency in text")]
    public double? FrequencyPenalty { get; set; }
    
    [DataMember(Name = "presence_penalty")]
    [Input(Type = "number", Step = "0.1", Min = "0", Max = "2", Placeholder = "e.g. 0.5", Help = "Penalize tokens based on presence in text")]
    public double? PresencePenalty { get; set; }
    
    [DataMember(Name = "seed")]
    [Input(Type = "number", Placeholder = "e.g. 42", Help = "For deterministic sampling")]
    public int? Seed { get; set; }
    
    [DataMember(Name = "n")]
    [Input(Type = "number", Placeholder = "e.g. 1", Help = "How many chat choices to generate for each input message")]
    public int? N { get; set; }
    
    [Input(Type = "checkbox", Help = "Whether or not to store the output of this chat request")]
    [DataMember(Name = "store")]
    public bool? Store { get; set; }
    
    [DataMember(Name = "logprobs")]
    [Input(Type = "checkbox", Help = "Whether to return log probabilities of the output tokens")]
    public bool? Logprobs { get; set; }
    
    [DataMember(Name = "parallel_tool_calls")]
    [Input(Type = "checkbox", Help = "Enable parallel function calling during tool use")]
    public bool? ParallelToolCalls { get; set; }
    
    [DataMember(Name = "enable_thinking")]
    [Input(Type = "checkbox", Help = "Enable thinking mode for some Qwen providers")]
    public bool? EnableThinking { get; set; }
    
    [DataMember(Name = "stream")]
    [Input(Type = "hidden")]
    public bool? Stream { get; set; }
}
```

Which uses the [[Input] attribute](https://docs.servicestack.net/locode/declarative#custom-fields-and-inputs) 
to control the HTML Input rendered for each property whose `Type` can reference any 
HTML Input or any [ServiceStack Vue Component](https://docs.servicestack.net/vue/form-inputs) that's either built-in
or registered with the Component library.

In addition, you also have control to the css of the containing **Field**, **Input** and **Label** elements with the 
[[FieldCss] attribute](https://docs.servicestack.net/locode/declarative#field) 
which uses `[FieldCss(Field="col-span-12")]` to render the field to span the full width of the form.

The `[Input(Type="hidden")]` is used to hide the `Stream` property from the UI since it is invalid from an API Explorer UI.

### Combobox Values

The Combobox `EvalAllowableValues` can reference any JavaScript expression which is evaluated with 
[#Script](https://sharpscript.net) with the results embedded in the API Metadata that API Explorer uses to render its UI.

All combo boxes references a static JS Array except for `Model` which uses `EvalAllowableValues = "Chat.Models"` to
invoke the registered `Chat` instance `Models` property which returns an ordered list of all available models from all enabled providers:  

```csharp
appHost.ScriptContext.Args[nameof(Chat)] = new Chat(this);

public class Chat(ChatFeature feature)
{
    public List<string> Models => feature.Providers.Values
        .SelectMany(x => x.Models.Keys)
        .Distinct()
        .OrderBy(x => x)
        .ToList();
}
```

### Custom ChatMessages Component

The only property that doesn't use a built-in component is:

```csharp
[Input(Type = "ChatMessages", Label=""), FieldCss(Field = "col-span-12")]
public List<AiMessage> Messages { get; set; } = [];
```

Which makes use of a custom `ChatMessages` component in
[/modules/ui/components/ChatMessages.mjs](https://github.com/ServiceStack/ServiceStack/blob/main/ServiceStack/src/ServiceStack.AI.Chat/modules/ui/components/ChatMessages.mjs). 

Custom Components can be added to API Explorer in the same way as 
[overriding any built-in API Explorer](https://docs.servicestack.net/locode/custom-overview#ui) 
component by adding it to your local `/wwwroot` folder:

```files
/modules
  /ui
    /components
      ChatMessages.mjs
```

All components added to the `/components` folder will be automatically registered and available for use.

That's all that's needed to customize the `ChatCompletion` Form UI in API Explorer, for more features and
customizations see the [API Explorer Docs](https://docs.servicestack.net/api-explorer).

## XSS Vulnerability fixed in HtmlFormat.html

Late in this release cycle a Customer has reported a DOM XSS vulnerability in ServiceStack's built-in 
[Auto HTML API](/auto-html-api) page that has been fixed in [this commit](https://github.com/ServiceStack/ServiceStack/commit/76df4609410f7b440c3fb153371a1d29b9c06ac0) and available from this ServiceStack v8.9+ release.

Alternatively it can also be prevented by rejecting requests with `"` in its path:

```csharp
GlobalRequestFilters.Add((req, res, dto) => {
    if (req.OriginalPathInfo.IndexOf('"') >= 0)
        throw HttpError.Forbidden("Illegal characters in path");
});
```

By reverting to the use the old HTML Format:

```csharp
ServiceStack.Templates.HtmlTemplates.HtmlFormatName = "HtmlFormatLegacy.html";
```

Or by disabling the auto rendering of HTML API responses:

```csharp
SetConfig(new HostConfig {
    EnableAutoHtmlResponses = false
})
```

To improve visibility of future security issues we've also created a [Security Vulnerabilities Watchlist](https://github.com/ServiceStack/Discuss/discussions/150), please follow this thread to get notified of any updates.


# Release Notes History
Source: https://docs.servicestack.net/release-notes-history

## 2025

- [v8.9](/releases/v8_09)
- [v8.8](/releases/v8_08)
- [v8.7](/releases/v8_07)
- [v8.6](/releases/v8_06)

## 2024

- [v8.5](/releases/v8_05)
- [v8.4](/releases/v8_04)
- [v8.3](/releases/v8_03)
- [v8.2](/releases/v8_02)
- [v8.1](/releases/v8_01)

## 2023

- [v8](/releases/v8_00)
- [v6.11](/releases/v6_11)
- [v6.10](/releases/v6_10)
- [v6.9](/releases/v6_09)
- [v6.8](/releases/v6_08)
- [v6.7](/releases/v6_07)
- [v6.6](/releases/v6_06)

## 2022

- [v6.5](/releases/v6_05)
- [v6.4](/releases/v6_04)
- [v6.3](/releases/v6_03)
- [v6.2](/releases/v6_02)
- [v6.1](/releases/v6_01)
- [v6](/releases/v6_00)

## 2021

- [v5.13](/releases/v5_13)
- [v5.12](/releases/v5_12)
- [v5.11](/releases/v5_11)

## 2020

 - [v5.10](/releases/v5_10)
 - [v5.9](/releases/v5_9)
 - [v5.8](/releases/v5_8)

## 2019

 - [v5.7](/releases/v5_7)
 - [v5.6](/releases/v5_6)
 - [v5.5](/releases/v5_5)

## 2018

 - [v5.4](/releases/v5_4)
 - [v5.2](/releases/v5_2)
 - [v5.1.0](/releases/v5_1_0)
 - [v5.0.2](/releases/v5_0_0)

## 2017

 - [v5.0.0](/releases/v5_0_0#v5-release-notes)
 - [v4.5.14](/releases/v4_5_14)
 - [v4.5.10](/releases/v4_5_10)
 - [v4.5.8](/releases/v4_5_8)
 - [v4.5.6](/releases/v4_5_6)

## 2016 

 - [v4.5.2](/releases/v4_5_2)
 - [v4.5.0](/releases/v4_5_0)
 - [v4.0.62](/releases/v4_0_62)
 - [v4.0.60](/releases/v4_0_60)
 - [v4.0.56](/releases/v4_0_56)
 - [v4.0.54](/releases/v4_0_54)
 - [v4.0.52](/releases/v4_0_52)

## 2015

 - [v4.0.50](/releases/v4_0_50)
 - [v4.0.48](/releases/v4_0_48)
 - [v4.0.46](/releases/v4_0_46)
 - [v4.0.44](/releases/v4_0_44)
 - [v4.0.42](/releases/v4_0_42)
 - [v4.0.40](/releases/v4_0_40)
 - [v4.0.38](/releases/v4_0_38)
 - [v4.0.36](/releases/v4_0_36)

## 2014

 - [v4.0.35](/releases/v4_0_35)
 - [v4.0.34](/releases/v4_0_34)
 - [v4.0.33](/releases/v4_0_33)
 - [v4.0.32](/releases/v4_0_32)
 - [v4.0.31](/releases/v4_0_31)
 - [v4.0.30](/releases/v4_0_30)
 - [v4.0.24](/releases/v4_0_24)
 - [v4.0.23](/releases/v4_0_23)
 - [v4.0.22](/releases/v4_0_22)
 - [v4.0.21](/releases/v4_0_21)
 - [v4.0.19](/releases/v4_0_19)
 - [v4.0.18](/releases/v4_0_18)
 - [v4.0.15](/releases/v4_0_15)
 - [v4.0.12](/releases/v4_0_12)
 - [v4.0.11](/releases/v4_0_11)
 - [v4.0.10](/releases/v4_0_10)
 - [v4.0.09](/releases/v4_0_09)
 - [v4.0.08](/releases/v4_0_08)
 - [v4.0.06](/releases/v4_0_06)
 - [v4.0.0](/releases/v4_0_0)

## 2013 and prior

 - [Older v3 Release Notes](/release-notes-v3)


# Pre Release NuGet Packages
Source: https://docs.servicestack.net/pre-release

## ServiceStack Pre-Release NuGet Packages

Our interim pre-release NuGet packages in between major releases on NuGet are published to [Feedz.io](https://feedz.io/).

::: tip
If preferred, the pre-release packages are also available in our [MyGet](/myget) or [GitHub Packages Registry](/gh-nuget)
:::

### Add using Mix

If you have the [dotnet x tool](/dotnet-tool) installed, you can configure your projects by downloading `NuGet.Config` in the same folder as your **.sln**

:::sh
x mix feedz
:::

### Add using VS .NET

Instructions to add ServiceStack's Pre-Release packages feed to VS .NET are:

  1. Go to **Tools** > **Options** > **Nuget Package Manager** > **Package Sources**
  2. Add the Source `https://f.feedz.io/servicestack/pre-release/nuget/index.json` with the name of your choice, 
  e.g. `ServiceStack Pre-Release`

After registering the feed it will show up under NuGet package sources when opening the NuGet package manager dialog:

![NuGet Package Manager](https://raw.githubusercontent.com/ServiceStack/Assets/master/img/wikis/myget/package-manager-ui.png)

Which will allow you to search and install pre-release packages from the selected Pre Release packages feed.

### Adding Pre-Release NuGet feed without VS .NET

If you're not using or don't have VS .NET installed, you can add the MyGet feed to your NuGet.config at `%AppData%\NuGet\NuGet.config`:

```xml
<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <packageSources>
    <add key="ServiceStack Pre-Release" value="https://f.feedz.io/servicestack/pre-release/nuget/index.json" />
    <add key="nuget.org" value="https://api.nuget.org/v3/index.json" protocolVersion="3" />
  </packageSources>
</configuration>
```

## Redownloading Pre Release packages

If you've already packages with the **same version number** from Feedz previously installed, you will 
need to manually delete the NuGet `/packages` folder for NuGet to pull down the latest packages.

### Clear NuGet Package Cache

You can clear your local NuGet packages cache in any OS by running the command-line below in your favorite Terminal:

:::sh
nuget locals all -clear
:::

If `nuget` is not in your Systems `PATH`, it can also be invoked from the `dotnet` tool:

:::sh
dotnet nuget locals all --clear
:::

Within VS .NET you can clear them from **Tools** > **Options** > **Nuget Package Manager** and click **Clear All NuGet Cache(s)**:

![Clear Packages Cache](https://raw.githubusercontent.com/ServiceStack/Assets/master/img/wikis/myget/clear-package-cache.png)

Alternatively on Windows you can delete the Cached NuGet packages manually with:

:::sh
del %LOCALAPPDATA%\NuGet\Cache\*.nupkg /q
:::

### Full Package Clean

In most cases clearing the NuGet packages cache will suffice, sometimes you'll also need to manually delete other local packages caches

delete all NuGet packages in `/packages` folder:

:::sh
rd /q /s packages 
:::

delete `/bin` and `/obj` folders in host project

:::sh
rd /q /s bin obj
:::

## Versioning Scheme

::include versioning-scheme.md::


# Create your first WebService
Source: https://docs.servicestack.net/create-your-first-webservice

This is a quick walkthrough of getting your first web service up and running whilst having a look at the how some of the different components work. 

## Step 1: Install the x dotnet tool

First we want to install the [x dotnet tool](/dotnet-tool):

:::sh
dotnet tool install --global x 
:::

The [dotnet tools](/dotnet-tool) are ServiceStack's versatile companion giving you quick access to a lot of its high-level features including 
generating mobile, web & desktop DTOs with [Add ServiceStack Reference](/add-servicestack-reference) generating [gRPC Clients and proto messages](/grpc/),
quickly [apply gists](/mix-tool) to your project enabled by ServiceStack's effortless [no-touch Modular features](/modular-startup), 
[command-line API access](/post-command), it even includes a [lisp REPL](https://sharpscript.net/lisp/) should you need to explore your [remote .NET Apps in real-time](https://sharpscript.net/lisp/#techstacks-tcp-lisp-repl-demo).

## Step 2: Selecting a template

Importantly, the dotnet tools lets you create [.NET 6, .NET Framework](/dotnet-new) and [ASP.NET Core on .NET Framework](/templates/corefx) projects.
Unless you're restricted to working with .NET Framework you'll want to start with a [.NET 6 project template](/templates/dotnet-new#usage), for this example
we'll start with the Empty [web](https://github.com/NetCoreTemplates/web) template which implicitly uses the folder name for the Project Name:

:::sh
x new web WebApp
:::

## Step 3: Run your project

Press `Ctrl+F5` to run your project!

You should see an already working API integration using [@servicestack/client](/javascript-client) library to call your App's 
[JavaScript DTOs](/javascript-add-servicestack-reference) and links to calling your API from [API Explorer](/api-explorer):

<a href="https://web.web-templates.io"><img class="max-w-lg" src="/img/pages/overview/web-hello.png"></a>

#### Watched builds

A recommended alternative to running your project from your IDE is to run a watched build using `dotnet watch` from a terminal:

:::sh
dotnet watch
:::

Where it will automatically rebuild & restart your App when it detects any changes to your App's source files.

### How does it work?

Now that your new project is running, let's have a look at what we have. The template comes with a single web service route which comes from the Request DTO (Data Transfer Object) which is located in the [Hello.cs](https://github.com/NetCoreTemplates/web/blob/master/MyApp.ServiceModel/Hello.cs) file:

```csharp
[Route("/hello/{Name}")]
public class Hello : IReturn<HelloResponse>
{
    public string Name { get; set; }
}

public class HelloResponse
{
    public string Result { get; set; }
}
```

The `Route` attribute is specifying what path `/hello/{Name}` where `{Name}` binds its value to the public string property of **Name**.

Let's access the route to see what comes back. Go to the following URL in your address bar:

    /hello/world

You will see a snapshot of the Result in a HTML response format. To change the return format to Json, simply add `?format=json` to the end of the URL. You'll learn more about [formats](/formats), endpoints (URLs, etc) when you continue reading the documentation.

If we go back to the solution and find the WebApplication1.ServiceInterface and open the **MyServices.cs** file, we can have a look at the code that is responding to the browser, giving us the **Result** back.

```csharp
public class MyServices : Service
{
    public object Any(Hello request)
    {
        return new HelloResponse { Result = $"Hello, {request.Name}!" };
    }
}
```

If we look at the code above, there are a few things to note. The name of the method `Any` means the server will run this method for any of the valid HTTP Verbs. Service methods are where you control what returns from your service.

## Step 4: Exploring the ServiceStack Solution

The Recommended structure below is built into all ServiceStackVS VS.NET Templates where creating any new ServiceStack 
project will create a solution with a minimum of 4 projects below ensuring ServiceStack solutions starts off from an optimal 
logical project layout, laying the foundation for growing into a more maintainable, cohesive and reusable code-base:

<img align="right" src="/img/pages/solution-layout.png" />

### Host Project

The Host project contains your AppHost which references and registers all your App's concrete dependencies in its IOC and is the central location where all App configuration and global behavior is maintained. It also references all Web Assets like Razor Views, JS, CSS, Images, Fonts, etc. that's needed to be deployed with the App. The AppHost is the top-level project which references all dependencies used by your App whose role is akin to an orchestrator and conduit where it decides what functionality is made available and which concrete implementations are used. By design it references all other (non-test) projects whilst nothing references it and as a goal should be kept free of any App or Business logic.

### ServiceInterface Project

The ServiceInterface project is the implementation project where all Business Logic and Services live which typically references every other project except the Host projects. Small and Medium projects can maintain all their implementation here where logic can be grouped under feature folders. Large solutions can split this project into more manageable cohesive and modular projects which we also recommend encapsulates any dependencies they might use.

### ServiceModel Project

The ServiceModel Project contains all your Application's DTOs which is what defines your Services contract, keeping them isolated from any Server implementation is how your Service is able to encapsulate its capabilities and make them available behind a remote facade. There should be only one ServiceModel project per solution which contains all your DTOs and should be implementation, dependency and logic-free which should only reference the impl/dep-free **ServiceStack.Interfaces.dll** contract assembly to ensure Service contracts are decoupled from its implementation, enforces interoperability ensuring that your Services don't mandate specific client implementations and will ensure this is the only project clients need to be able to call any of your Services by either referencing the **ServiceModel.dll** directly or downloading the DTOs from a remote ServiceStack instance using [Add ServiceStack Reference](/add-servicestack-reference):

![](/img/pages/dtos-role.png)

### Test Project

The Unit Test project contains all your Unit and Integration tests. It's also a Host project that typically references all other non-Host projects in the solution and contains a combination of concrete and mock dependencies depending on what's being tested. See the [Testing Docs](/testing) for more information on testing ServiceStack projects.

## Learn ServiceStack Guide

If you're new to ServiceStack we recommend stepping through [ServiceStack's Getting Started Guide](https://servicestack.net/start/project-overview)
to get familiar with the basics.

## API Client Examples

### jQuery Ajax

ServiceStack's clean Web Services makes it simple and intuitive to be able to call ServiceStack Services from any ajax client, e.g. from a traditional [Bootstrap Website using jQuery](https://github.com/ServiceStack/Templates/blob/master/src/ServiceStackVS/BootstrapWebApp/BootstrapWebApp/default.cshtml):

```html
<input class="form-control" id="Name" type="text" placeholder="Type your name">
<p id="result"></p>
<script>
$('#Name').keyup(function () {
    let name = $(this).val()
    $.getJSON('/hello/' + name)
        .success(function (response) {
            $('#result').html(response.Result)
        })
})
</script>
```

### Rich JsonApiClient & Typed DTOs

The modern recommended alternative to jQuery that works in all modern browsers is using your APIs built-in [JavaScript typed DTOs](/javascript-add-servicestack-reference) with the [@servicestack/client](/javascript-client) library 
from a [JavaScript Module](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules).

We recommend using an [importmap](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script/type/importmap) 
to specify where **@servicestack/client** should be loaded from, e.g:

```html
<script async src="https://ga.jspm.io/npm:es-module-shims@1.6.3/dist/es-module-shims.js"></script><!--safari-->
<script type="importmap">
{
    "imports": {
        "@servicestack/client":"https://unpkg.com/@servicestack/client@2/dist/servicestack-client.mjs"
    }
}
</script>
```

This lets us reference the **@servicestack/client** package name in our source code instead of its physical location:
    
```html
<input type="text" id="txtName">
<div id="result"></div>
```

```html
<script type="module">
import { JsonServiceClient, $1, on } from '@servicestack/client'
import { Hello } from '/types/mjs'

const client = new JsonServiceClient()
on('#txtName', {
    async keyup(el) {
        const api = await client.api(new Hello({ name:el.target.value }))
        $1('#result').innerHTML = api.response.result
    }
})
</script>
```

### Enable static analysis and intelli-sense 

For better IDE intelli-sense during development, save the annotated Typed DTOs to disk with the [x dotnet tool](/dotnet-tool):

:::sh
x mjs
:::

Then reference it instead to enable IDE static analysis when calling Typed APIs from JavaScript:

```js
import { Hello } from '/js/dtos.mjs'
client.api(new Hello({ name }))
```
    
To also enable static analysis for **@servicestack/client**, install the dependency-free library as a dev dependency:
    
:::sh
npm install -D @servicestack/client
:::

Where only its TypeScript definitions are used by the IDE during development to enable its type-checking and intelli-sense.

### Rich intelli-sense support

Where you'll be able to benefit from rich intelli-sense support in smart IDEs like [Rider](https://www.jetbrains.com/rider/) for 
both the client library:

![](/img/pages/mix/init-rider-ts-client.png)

As well as your App's server generated DTOs:

![](/img/pages/release-notes/v6.6/mjs-intellisense.png)

So even simple Apps without complex bundling solutions or external dependencies can still benefit from a rich typed authoring 
experience without any additional build time or tooling complexity.

## Create Empty ServiceStack Apps

::include empty-projects.md::

### Any TypeScript or JavaScript Web, Node.js or React Native App

The same TypeScript [JsonServiceClient](/javascript-client) can also be used in more sophisticated JavaScript Apps like 
[React Native](/typescript-add-servicestack-reference#react-native-jsonserviceclient) to [Node.js Server Apps](https://github.com/ServiceStackApps/typescript-server-events) such as this example using TypeScript & [Vue Single-File Components](https://vuejs.org/guide/scaling-up/sfc.html):

```html
<template>
  <div v-if="api.error" class="ml-2 text-red-500">{{ error.message }}</div>
  <div v-else class="ml-3 mt-2 text-2xl">{{ api.loading ? 'Loading...' : api.response.result }}</div>
</template>

<script setup lang="ts">
import { JsonServiceClient } from "@servicestack/client"
import { Hello } from "@/dtos"

const props = defineProps<{ name: string }>()
const client = new JsonServiceClient()

const api = client.api(new Hello({ name: props.name }))
</script>
```

Compare and contrast with other major SPA JavaScript Frameworks:

 - [Vue 3 HelloApi.mjs](https://github.com/NetCoreTemplates/blazor-vue/blob/main/MyApp/wwwroot/posts/components/HelloApi.mjs)
 - [Vue SSG using swrClient](https://github.com/NetCoreTemplates/vue-ssg/blob/main/ui/src/components/HelloApi.vue)
 - [Next.js with swrClient](https://github.com/NetCoreTemplates/nextjs/blob/main/ui/components/intro.tsx)
 - [React HelloApi.tsx](https://github.com/NetCoreTemplates/react-spa/blob/master/MyApp/src/components/Home/HelloApi.tsx)
 - [Angular HelloApi.ts](https://github.com/NetCoreTemplates/angular-spa/blob/master/MyApp/src/app/home/HelloApi.ts)
 - [Svelte Home.svelte](https://github.com/NetCoreTemplates/svelte-spa/blob/master/MyApp/src/components/Home.svelte)

### Web, Mobile and Desktop Apps

Use [Add ServiceStack Reference](/add-servicestack-reference) to enable typed integrations for the most popular languages to develop Web, Mobile & Desktop Apps.

### Full .NET Project Templates

The above `init` projects allow you to create a minimal web app, to create a more complete ServiceStack App with the recommended project structure, start with one of our C# project templates instead:

### [C# Project Templates Overview](/templates/)

## Simple, Modern Razor Pages & MVC Vue 3 Tailwind Templates

The new Tailwind Razor Pages & MVC Templates enable rapid development of Modern Tailwind Apps without the [pitfalls plaguing SPAs](https://servicestack.net/posts/javascript):

<lite-youtube class="w-full mx-4 my-4" width="560" height="315" videoid="SyppvQB7IPs" style="background-image: url('https://img.youtube.com/vi/SyppvQB7IPs/maxresdefault.jpg')"></lite-youtube>

All Vue Tailwind templates are pre-configured with our rich [Vue 3 Tailwind Components](/vue/) library for maximum productivity:

<lite-youtube class="w-full mx-4 my-4" width="560" height="315" videoid="YIa0w6whe2U" style="background-image: url('https://img.youtube.com/vi/YIa0w6whe2U/maxresdefault.jpg')"></lite-youtube>

## Advanced JAMStack Templates

For more sophisticated Apps that need the best web tooling that npm can offer checkout our JAMStack Vite Vue & SSG templates:

<lite-youtube class="w-full mx-4 my-4" width="560" height="315" videoid="D-rU0lU_B4I" style="background-image: url('https://img.youtube.com/vi/D-rU0lU_B4I/maxresdefault.jpg')"></lite-youtube>

Or if you prefer Modern React Apps checkout the Next.js template:

<lite-youtube class="w-full mx-4 my-4" width="560" height="315" videoid="3pPLRyPsO5A" style="background-image: url('https://img.youtube.com/vi/3pPLRyPsO5A/maxresdefault.jpg')"></lite-youtube>

For Blazor WASM and Server checkout our comprehensive [Blazor projects & Tailwind components](/templates/blazor-tailwind).

### Integrated in Major IDEs and popular Mobile & Desktop platforms

ServiceStack Services are also [easily consumable from all major Mobile and Desktop platforms](/why-servicestack#generate-instant-typed-apis-from-within-all-major-ides) including native iPhone and iPad Apps on iOS with Swift, Mobile and Tablet Apps on Android with Java or Kotlin, OSX Desktop Applications as well as targeting the most popular .NET Mobile and Desktop platforms including Xamarin.iOS, Xamarin.Android, Windows Store, WPF and WinForms.

## Instant Client Apps

Generate working native client apps for your live ServiceStack services, in a variety of languages, instantly with our free managed service.

This tool enables your developers, and even your customers, to open a working example native application straight from the web to their favorite IDE.

<lite-youtube class="w-full mx-4 my-4" width="560" height="315" videoid="GTnuMhvUayg" style="background-image: url('https://img.youtube.com/vi/GTnuMhvUayg/maxresdefault.jpg')"></lite-youtube>

## Fundamentals - AppHost and Configuration

Walk through configuring your ServiceStack Application's `AppHost`:

<lite-youtube class="w-full mx-4 my-4" width="560" height="315" videoid="mOpx5mUGoqI" style="background-image: url('https://img.youtube.com/vi/mOpx5mUGoqI/maxresdefault.jpg')"></lite-youtube>

## Community Resources

  - [Creating A Simple Service Using ServiceStack](https://www.c-sharpcorner.com/UploadFile/shashijeevan/creating-a-simple-service-using-servicestack779/) by [Shashi Jeevan](http://shashijeevan.net/author/shashijeevan/)
  - [Introducing ServiceStack](https://www.dotnetcurry.com/aspnet/1056/introducing-service-stack-tutorial) by [@dotnetcurry](https://twitter.com/DotNetCurry)
  - [Create web services in .NET in a snap with ServiceStack](https://www.techrepublic.com/article/create-web-services-in-net-in-a-snap-with-servicestack/) by [@techrepublic](https://twitter.com/techrepublic)
  - [How to build web services in MS.Net using ServiceStack](https://kborra.wordpress.com/2014/07/29/how-to-build-web-services-in-ms-net-using-service-stack/) by [@kishoreborra](http://kborra.wordpress.com/about/)
  - [Getting started with ServiceStack – Creating a service](https://dilanperera.wordpress.com/2014/02/22/getting-started-with-servicestack-creating-a-service/)
  - [ServiceStack Quick Start](https://debuggers.domains/post/servicestack-quick-start/) by [@aarondandy](https://github.com/aarondandy) 
  - [Getting Started with ASP.NET MVC, ServiceStack and Bootstrap](https://www.pluralsight.com/courses/getting-started-aspdotnet-mvcservice-stack-bootstrap) by [@pluralsight](http://twitter.com/pluralsight)
  - [Building Web Applications with Open-Source Software on Windows](https://www.pluralsight.com/courses/building-web-application-open-source-software-on-windows) by [@pluralsight](http://twitter.com/pluralsight)
  - [ServiceStack the way I like it](https://www.antonydenyer.co.uk/2012-09-20-servicestack-the-way-i-like-it/) by [@tonydenyer](https://twitter.com/tonydenyer)
  - [Generating a RESTful Api and UI from a database with LLBLGen](https://www.mattjcowan.com/funcoding/2013/03/10/rest-api-with-llblgen-and-servicestack/) by [@mattjcowan](https://twitter.com/mattjcowan)
  - [ServiceStack: Reusing DTOs](https://korneliuk.blogspot.com/2012/08/servicestack-reusing-dtos.html) by [@korneliuk](https://twitter.com/korneliuk)
  - [ServiceStack, Rest Service and EasyHttp](https://blogs.lessthandot.com/index.php/WebDev/ServerProgramming/servicestack-restservice-and-easyhttp) by [@chrissie1](https://twitter.com/chrissie1)
  - [Building a Web API in SharePoint 2010 with ServiceStack](https://www.mattjcowan.com/funcoding/2012/05/04/building-a-web-api-in-sharepoint-2010-with-servicestack/)
  - [REST Raiding. ServiceStack](https://dgondotnet.blogspot.com/2012/04/rest-raiding-servicestack.html) by [Daniel Gonzalez](http://www.blogger.com/profile/13468563783321963413)
  - [JQueryMobile and ServiceStack: EventsManager tutorial](https://kylehodgson.com/2012/04/21/jquerymobile-and-service-stack-eventsmanager-tutorial-post-2/) / [Part 3](https://kylehodgson.com/2012/04/23/jquerymobile-and-service-stack-eventsmanager-tutorial-post-3/) by Kyle Hodgson
  - [Like WCF: Only cleaner!](https://kylehodgson.com/2012/04/18/like-wcf-only-cleaner-9/) by Kyle Hodgson
  - [ServiceStack I heart you. My conversion from WCF to SS](https://www.philliphaydon.com/2012/02/21/service-stack-i-heart-you-my-conversion-from-wcf-to-ss/) by [@philliphaydon](https://twitter.com/philliphaydon)
  - [ServiceStack vs WCF Data Services](https://codealoc.wordpress.com/2012/03/24/service-stack-vs-wcf-data-services/)
  - [Buildiing a Tridion WebService with jQuery and ServiceStack](https://www.curlette.com/?p=161) by [@robrtc](https://twitter.com/#!/robrtc)
  - [Anonymous type + Dynamic + ServiceStack == Consuming cloud has never been easier](https://www.ienablemuch.com/2012/05/anonymous-type-dynamic-servicestack.html) by [@ienablemuch](https://twitter.com/ienablemuch)
  - [Handful of examples of using ServiceStack based on the ServiceStack.Hello Tutorial](https://github.com/jfoshee/TryServiceStack) by [@82unpluggd](https://twitter.com/82unpluggd)


# Your first Web Service Explained
Source: https://docs.servicestack.net/your-first-webservice-explained

Let's look a bit deeper into the [Hello World service](/create-your-first-webservice#how-does-it-work) you created:

As you have seen, the convention for response DTO is `RequestDTO` and  `RequestDTOResponse`. **Note, request and response DTO should be in the same namespace if you want ServiceStack to recognize the DTO pair**.

To support automatic exception handling, you also need to add a `ResponseStatus` property to the response DTO:

```csharp
// Request DTO
public class Hello : IReturn<HelloResponse>
{
    public string Name { get; set; }
}

// Response DTO (follows naming convention)
public class HelloResponse
{
    public string Result { get; set; }

    public ResponseStatus ResponseStatus { get; set; } //Automatic exception handling
}
```

Services are implemented in a class that either inherits from the `Service` base class or implements the `IService` empty marker interface. Inheriting from the convenient `Service` base class provides easy access to the most common functionality.  

```csharp
public class HelloService : Service
{
    public object Any(Hello request)
    {
        return new HelloResponse { Result = $"Hello, {request.Name}" };
    }
}
```

The above service can be called with **Any** HTTP Verb (e.g. GET, POST,..) from any endpoint or format (e.g. JSON, XML, etc). You can also choose to handle a specific Verb by changing the method name to suit. 

E.g. you can limit the Service to only handle HTTP **GET** requests by using the `Get` method:

```csharp
public class HelloService : Service
{
    public object Get(Hello request) => new HelloResponse { Result = $"Hello, {request.Name}" };
}
```

## Calling Web Services

Thanks to the above `IReturn<T>` interface marker you'll be able to use the terse, typed Service Client APIs, e.g:

```csharp
var client = new JsonApiClient(BaseUri);

HelloResponse response = client.Get(new Hello { Name = "World" }); 
```

Request DTOs that don't implement `IReturn<T>` will need to explicitly specify the Response DTO on their call-site, e.g:

```csharp
HelloResponse response = client.Get<HelloResponse>(new Hello { Name = "World" }); 
HelloResponse response = client.Get<HelloResponse>("/hello/World!"); 
```

Alternatively you could use a general purpose HTTP Client like [HTTP Utils](/http-utils):

```csharp
HelloResponse response = "http://base.url/hello/World"
    .GetJsonFromUrl()
    .FromJson<HelloResponse>();
```

We highly recommend annotating Request DTO's with the above `IReturn<T>` marker as it enables a generic typed API without clients having to know and specify the Response at each call-site, which would be invalidated and need to be manually updated if the Service Response Type changes.

More details on the Service Clients is available on the [C#/.NET Service Clients page](/csharp-client).

### Registering Custom Routes

If no routes are defined the .NET Service Clients will use the [pre-defined Routes](/routing#pre-defined-routes).
You can annotate your Request DTO with the `[Route]` attribute to register additional Custom Routes, e.g:

```csharp
//Request DTO
[Route("/hello")]
[Route("/hello/{Name}")]
public class Hello : IReturn<HelloResponse>
{
    public string Name { get; set; }
}
```

The .NET ServiceClients will then use the best matching Route based on the populated properties on the Request DTO.

### Routing Tips

No **?queryString** or POST Form Data should be included in the route as ServiceStack automatically populates Request DTOs with all matching params, e.g:

```csharp
[Route("/hello")]
```

Matches both `/hello` and `/hello?name=World` with the latter populating the `Name` Request DTO **public property**.

When the route includes a variable, e.g:

```csharp
[Route("/hello/{Name}")]
```

It only matches:

```
/hello/name
```

Whereas using a wildcard:

```csharp
[Route("/hello/{Name*}")]
```

Matches all routes:

```
/hello
/hello/name
/hello/my/name/is/ServiceStack 
```

More details about Routing is available on the [Routing page](/routing).


# ServiceStack API design
Source: https://docs.servicestack.net/api-design

The primary difference between developing RPC vs ServiceStack's [Message-based Services](/what-is-a-message-based-web-service) is that the Services entire contract
is defined by its typed messages, specifically the Request DTO which defines both the System inputs and identifies the System output. Typically both are POCO DTOs 
however the [response can be any serializable object](/service-return-types).

The simplest Service example that does this is:

```csharp
public class MyRequest : IReturn<MyRequest> {}

public class MyServices : Service
{
    public object Any(MyRequest request) => request;
}
```

As only the `Any()` wildcard method is defined, it will get executed whenever the `MyRequest` Service is invoked via **any HTTP Verb**, [gRPC](/grpc/), [MQ](/messaging) or [SOAP](/soap-support) Request. 

The Request DTO is also all that's required to invoke it via any [Typed Generic Service Client](/clients-overview) in any supported language, e.g:

```csharp
MyRequest response = client.Get(new MyRequest());
```

All Services are accessible by their [pre-defined routes](/routing#pre-defined-routes), we can turn it into a functional data-driven Service by annotating it with a [user-defined route](/routing) and changing the implementation to return all App Contacts:

```csharp
public class Contact 
{
    public int Id { get; set; }
    public string Name { get; set; }
}

[Route("/contacts")]
public class GetContacts : IReturn<List<Contact>> { }

public class ContactsService : Service
{
    public object Get(GetContacts request) => Db.Select<Contact>();
}
```

Which your C# clients will still be able to call with:

```csharp
List<Contact> response = client.Get(new GetContacts());
```

This will make a **GET** call to the custom `/contacts` URL and returns all rows from the `Contact` Table in the configured RDBMS using [OrmLite](https://github.com/ServiceStack/ServiceStack.OrmLite)
`Select()` extension method on the `base.Db` ADO.NET `IDbConnection` property on ServiceStack's convenience `Service` base class. 

Using `Get()` limits access to this service from HTTP **GET** requests only, all other HTTP Verbs requests to `/contacts` will return a **404 NotFound** HTTP Error Response.

### Using explicit Response DTO

Our recommendation instead of returning naked collections is returning an explicit predictable Response DTO, e.g:

```csharp
[Route("/contacts")]
public class GetContacts : IReturn<GetContactsResponse> { }

public class GetContactsResponse 
{
    public List<Contact> Results { get; set; }
    public ResponseStatus ResponseStatus { get; set; }
}

public class ContactsService : Service
{
    public object Get(GetContacts request) => new GetContactsResponse {
        Results = Db.Select<Contact>()
    };
}
```

Whilst slightly more verbose this style benefits from [more resilience in evolving and versioning](https://stackoverflow.com/a/12413091/85785) message-based Services
and more coarse-grained APIs as additional results can be added to the Response DTO without breaking existing clients. 

You'll also need to follow the above convention if you also wanted to [support SOAP endpoints](/soap-support) or if you want to be able to handle Typed [Response Messages in MQ Services](/messaging#message-workflow).

### All APIs have a preferred default method

Like the `Send*` APIs before them, both [API Explorer](/api-explorer) and the new [`Api*` methods](/csharp-client.html#high-level-api-and-apiasync-methods) send API requests using an APIs **preferred HTTP Method** which can be defined either:

 - Explicitly annotating Request DTOs with `IGet`, `IPost`, etc. **IVerb** interface markers
 - Using the verb specified in its user-defined `[Route]` attribute (if single verb specified)
 - Implicitly when using AutoQuery/CRUD Request DTOs
 - Using the Services **Verb()** implementation method if not using **Any()**

If the HTTP Method can't be inferred, it defaults to using HTTP **POST**. But as good API documentation practice, we recommend specifying the HTTP Method each API should use, preferably using the `IVerb` interface marker, so it's embedded into the APIs Services Contract shared with clients (not required for AutoQuery APIs).

## ServiceStack's API Design

We'll walk through a few examples here but for a more detailed look into the usages and capabilities of ServiceStack's API design checkout its
[Comprehensive Test Suite](https://github.com/ServiceStack/ServiceStack/blob/master/tests/RazorRockstars.Console.Files/ReqStarsService.cs)

At a minimum ServiceStack Services only need to implement the `IService` empty interface:

```csharp
public interface IService {}
```

The interface is used as a Marker interface that ServiceStack uses to find, register and auto-wire your existing services. Although you're more likely going to want to inherit from ServiceStack's convenience concrete `Service` class which contains easy access to ServiceStack's providers:

```csharp
public class Service : IService 
{
    IRequest Request { get; }                          // HTTP Request Context
    IResponse Response { get; }                        // HTTP Response Context
    IServiceGateway Gateway { get; }                   // Built-in Service Gateway
    IMessageProducer MessageProducer { get; }          // Message Producer for Registered MQ Server
    void PublishMessage(T message);                    // Publish messages to Registered MQ Server
    IVirtualPathProvider VirtualFileSources { get; }   // Virtual FileSystem Sources
    IVirtualFiles VirtualFiles { get; }                // Writable Virtual FileSystem
    ICacheClient Cache { get; }                        // Registered Caching Provider
    ICacheClientAsync CacheAsync { get; }              // Registered Async Caching Provider (or sync wrapper)
    MemoryCacheClient LocalCache { get; }              // Local InMemory Caching Provider
    IDbConnection Db { get; }                          // Registered ADO.NET IDbConnection
    IRedisClient Redis { get; }                        // Registered RedisClient 
    ValueTask<IRedisClientAsync> GetRedisAsync();      // Registered Async RedisClient 
    IAuthRepository AuthRepository { get; }            // Registered User Repository
    IAuthRepositoryAsync AuthRepositoryAsync { get; }  // Registered Async User Repository
    ISession SessionBag { get; }                       // Dynamic Session Bag
    ISessionAsync SessionBagAsync { get; }             // Dynamic Async Session Bag
    Task<TUserSession> SessionAsAsync<TUserSession>(); // Resolve Typed UserSession Async
    TUserSession SessionAs<TUserSession>();            // Resolve Typed UserSession
    IAuthSession GetSession() { get; }                 // Resolve base IAuthSession
    Task<IAuthSession> GetSessionAsync();              // Resolve base IAuthSession Async
    bool IsAuthenticated { get; }                      // Is Authenticated Request
    T TryResolve<T>();                                 // Resolve dependency at runtime
    T ResolveService<T>();                             // Resolve an auto-wired service
    T GetPlugin<T>();                                  // Resolve optional registered Plugin
    T AssertPlugin<T>();                               // Resolve required registered Plugin
    void Dispose();                                    // Override to implement custom IDispose
    ValueTask DisposeAsync();                          // implement IAsyncDisposable (.NET v4.7.2+)
}
```

### Basic example - Handling Any HTTP Verb

Lets revisit the Simple example from earlier:

```csharp
[Route("/contacts")]
public class GetContacts : IReturn<List<Contact>> { }

public class ContactsService : Service
{
    public object Get(GetContacts request) => Db.Select<Contact>();
}
```

ServiceStack maps HTTP Requests to your Services **Actions**. An Action is any method that:

  - Is `public` 
  - Only contains a **single argument - the typed Request DTO**
  - Has a Method name matching a **HTTP Method** or **Any** (the fallback that can handle "ANY" method)
    - Methods can have **Format** suffix to handle specific formats, e.g. if exists `GetJson` will handle **GET JSON** requests
  - Can specify either `T` or `object` Return type, both have same behavior 

### Content-Type Specific Service Implementations

Service methods can also use `Verb{Format}` method names to provide a different implementation for handling a specific Content-Type. 

The Service below defines several different implementation for handling the same Request:

```csharp
[Route("/my-request")]
public class MyRequest 
{
    public string Name { get; set; }
}

public class ContentTypeServices : Service
{
    public object GetJson(MyRequest request) => ..; // Handles GET /my-request for JSON responses

    public object GetHtml(MyRequest request) =>     // Handles GET /my-request for HTML Responses
        $@"<html>
            <body>
                <h1>GetHtml {request.Name}</h1>
            </body>
        </html>";

    public object AnyHtml(MyRequest request) =>     // Handles other POST/PUT/etc Verbs for HTML Responses
        $@"<html>
            <body>
                <h1>AnyHtml {request.Name}</h1>
            </body>
        </html>";

    public object Any(MyRequest request) => ...;    // Handles all other unspecified Verbs/Formats
}
```

### Optional *Async Suffixes

In addition your Services can optionally have the `*Async` suffix which by .NET Standard (and ServiceStack) guidelines is preferred for Async methods to telegraph to client call sites that its response should be awaited.


```csharp
[Route("/contacts")]
public class GetContacts : IReturn<List<Contact>> { }

public class ContactsService : Service
{
    public async Task<object> GetAsync(GetContacts request) => 
        await Db.SelectAsync<Contact>();

    public object GetHtmlAsync(MyRequest request) =>
        $@"<html>
            <body>
                <h1>GetHtml {request.Name}</h1>
            </body>
        </html>";
}
```

If both exists (e.g. `Post()` and `PostAsync()`) the `*Async` method will take precedence and be invoked instead. 

Allowing both is useful if you have internal services directly invoking other Services using `HostContext.ResolveService<T>()` where you can upgrade your Service to use an Async implementation without breaking existing clients, e.g. this is used in [RegisterService.cs](https://github.com/ServiceStack/ServiceStack/blob/master/src/ServiceStack/Auth/RegisterService.cs):

```csharp
[Obsolete("Use PostAsync")]
public object Post(Register request)
{
    try
    {
        var task = PostAsync(request);
        return task.GetResult();
    }
    catch (Exception e)
    {
        throw e.UnwrapIfSingleException();
    }
}

/// <summary>
/// Create new Registration
/// </summary>
public async Task<object> PostAsync(Register request)
{
    //... async impl
}            
```

To change to use an async implementation whilst retaining backwards compatibility with existing call sites, e.g:

```csharp
using var service = HostContext.ResolveService<RegisterService>(Request);
var response = service.Post(new Register { ... });
```

This is important if the response is ignored as the C# compiler wont give you any hints to await the response which can lead to timing issues where the Services is invoked but User Registration hasn't completed as-is often assumed.

Alternatively you can rename your method to use `*Async` suffix so the C# compiler will fail on call sites so you can replace the call-sites to `await` the async `Task` response, e.g:

```csharp
using var service = HostContext.ResolveService<RegisterService>(Request);
var response = await service.PostAsync(new Register { ... });
```

### Group Services by Tag

Related Services by can be grouped by annotating **Request DTOs** with the `[Tag]` attribute where they'll enable functionality in a number of ServiceStack's metadata services where they'll be used to [Group Services in Open API](https://swagger.io/docs/specification/grouping-operations-with-tags/).

This feature could be used to tag which Services are used by different platforms:

```csharp
[Tag("web")]
public class WebApi : IReturn<MyResponse> {}

[Tag("mobile")]
public class MobileApi : IReturn<MyResponse> {}

[Tag("web"),Tag("mobile")]
public class WebAndMobileApi : IReturn<MyResponse> {}
```

Where they'll appear as a tab to additionally filter APIs in metadata pages:

![](/img/pages/metadata/tag-groups.webp)

They're also supported in [Add ServiceStack Reference](/add-servicestack-reference) where it can be used in the [IncludeTypes](/csharp-add-servicestack-reference#includetypes) DTO customization option where tags can be specified using braces in the format `{tag}` or `{tag1,tag2,tag3}`, e.g:

```
/* Options:
IncludeTypes: {web,mobile}
```

Or individually:

```
/* Options:
IncludeTypes: {web},{mobile}
```

It works similar to [Dependent Type References wildcard syntax](/csharp-add-servicestack-reference#include-request-dto-and-its-dependent-types) where it expands all Request DTOs with the tag to include all its reference types so including a `{web}` tag would be equivalent to including all Request DTOs & reference types with that reference, e.g:

```
/* Options:
IncludeTypes: WebApi.*,WebAndMobileApi.*
```


### Micro ORMs and ADO.NET's IDbConnection

Code-First Micro ORMS like [OrmLite](https://github.com/ServiceStack/ServiceStack.OrmLite) and 
[Dapper](https://github.com/StackExchange/Dapper) provides a pleasant high-level experience whilst working directly against ADO.NET's low-level `IDbConnection`. They both support all major databases so you immediately have access to a flexible RDBMS option out-of-the-box. At the same time you're not limited to using the providers contained in the `Service` class and can continue to use your own register IOC dependencies (inc. an alternate IOC itself). 

### Micro ORM POCOs make good DTOs

The POCOs used in Micro ORMS are particularly well suited for re-using as DTOs since they don't contain any circular references that the Heavy ORMs have (e.g. EF). OrmLite goes 1-step further and borrows pages from NoSQL's playbook where any complex property e.g. `List<MyPoco>` is transparently blobbed in a schema-less text field, promoting the design of frictionless **Pure POCOS** that are uninhibited by RDBMS concerns. In many cases these POCO data models already make good DTOs and can be returned directly instead of mapping to domain-specific DTOs.

### Calling Services from a Typed C# Client

In Service development your services DTOs provides your technology agnostic **Service Layer** which you want to keep clean and as 'dependency-free' for maximum accessibility and potential re-use. Our recommendation is to follow our [Recommended Physical Project Structure](/physical-project-structure) and keep your DTOs in a separate ServiceModel project which ensures a well-defined
ServiceContract [decoupled from their implementation and accessible from any client](/service-complexity-and-dto-roles#data-transfer-objects---dtos). This recommended Physical project structure is embedded in each [ServiceStack VS.NET Template](/templates/).

One of ServiceStack's strengths is its ability to re-use your Server DTOs on the client enabling ServiceStack's productive end-to-end typed API. 
ServiceStack's use of Typed DTOs in its message-based design enable greater resiliency for your Services where the exact DTOs aren't needed, only the shape of the DTOs is important and clients can also opt to use partial DTOs containing just the fields they're interested in. In the same way extending existing Services with new optional properties wont break existing clients using older DTOs.

When developing both Server and Client applications the easiest way to call typed Services from clients is to just have them reference the same ServiceModel .dll the Server uses to define its Service Contract, or for clients that only need to call a couple of Service you can choose to 
instead copy the class definitions as-is, in both cases calling Services is exactly the same where the Request DTO can be used with any of the generic [C#/.NET Service Clients](/csharp-client) to call Services using a succinct typed API, e.g:

#### Service Model Classes

```csharp
[Route("/contacts")]
public class GetContacts : IReturn<List<Contact>> { }
public class Contact { ... }
```

Which can used in any ServiceClient with:

```csharp
var client = new JsonApiClient(BaseUri);
List<Contact> response = client.Get(new GetContacts());
```

Which makes a **GET** web request to the `/contacts` route. Custom Routes on Request DTO's are also not required as when none are defined the client automatically falls back to using ServiceStack's [pre-defined routes](/routing#pre-defined-routes).

### Generating Typed DTOs

In addition to being able to share your `ServiceModel.dll` on .NET Clients enable a typed end-to-end API without code-gen, clients 
can alternatively choose to use [Add ServiceStack Reference](/csharp-add-servicestack-reference) support to provide an 
alternative way to get the Services typed DTOs on the client. In both cases the exact same source code is used to call the Services:

```csharp
var client = new JsonApiClient(BaseUri);
var response = client.Get(new GetContacts());
```

Add ServiceStack Reference is also available for [most popular languages](/add-servicestack-reference) used in developing Web, Mobile and Desktop Apps.

#### Custom API Requests

When preferred, you can also use the previous more explicit client API (ideal for when you don't have the `IReturn<>` marker) which 
lets you call the Service using just its route:

```csharp
var response = client.Get<List<Contact>>("/contacts");
```

::: info
All these Service Client APIs **have async equivalents** with an `*Async` suffix
:::


### API QueryParams

ServiceStack's message-based design is centered around sending a single message which is all that's required to invoke any Typed API, however there may be times when you need to send additional params where you can't change the API's Request DTO definition or in AutoQuery's case its [Implicit Conventions](/autoquery/rdbms#implicit-conventions) would require too many permutations to be able to type the entire surface area on each Request DTO.

Typically this would inhibit being able to invoke these Services from a typed Service Client API that would instead need to either use the untyped [`Get<T>(relativeUrl)`](https://reference.servicestack.net/api/ServiceStack/IRestClient/#-gettresponsestring) ServiceClient APIs or [HTTP Utils](/http-utils) to construct the API Request path manually.

Alternatively Request DTOs can implement `IHasQueryParams` where any entries will be sent as additional query params along with the typed DTO:

```csharp
public interface IHasQueryParams
{
    Dictionary<string, string> QueryParams { get; set; }
}
```

Which is available in all AutoQuery DTOs where it's added as a non-serializable property so it's only included in the QueryString:

```csharp
[DataContract]
public abstract class QueryBase : IQuery, IHasQueryParams
{
    //...
    [IgnoreDataMember]
    public virtual Dictionary<string, string> QueryParams { get; set; }
}
```

Which allows using existing ServiceClient typed APIs to send a combination of untyped queries in AutoQuery requests, e.g:

```csharp
var api = await client.ApiAsync(new QueryContacts {
  IdsIn = new[]{ 1, 2, 3 },
  QueryParams = new() {
    ["LastNameStartsWith"] = "A"
  }
});
```

## Everything centered around Request DTOs

A nice property of ServiceStack's message-based design is all functionality is centered around Typed Request DTOs which easily lets you take advantage of high-level value-added functionality like [Auto Batched Requests](/auto-batched-requests) or [Encrypted Messaging](/auth/encrypted-messaging) which are enabled automatically without any effort or easily opt-in to enhanced functionality by decorating Request DTOs or thier Services with Metadata and [Filter Attributes](/filter-attributes) and everything works together, binded against typed models naturally.

E.g. you can take advantage of [ServiceStack's Razor support](https://razor.netcore.io/) and create a web page for this service by just adding a Razor view with the same name as the Request DTO in the `/Views` folder,
which for the `GetContacts` Request DTO you can just add `/Views/GetContacts.cshtml` and it will get rendered with the Services Response DTO as its View Model when the Service is called from a browser (i.e. HTTP Request with `Accept: text/html`). 

Thanks to ServiceStack's built-in Content Negotiation you can fetch the HTML contents calling the same url: 

```csharp
var html = $"{BaseUri}/contacts".GetStringFromUrl(accept:"text/html");
```

This [feature is particularly nice](https://razor.netcore.io/#unified-stack) as it lets you **re-use your existing services** to serve both Web and Native Mobile and Desktop clients.

### Action Filters

Service actions can also contain fine-grained application of Request and Response filters, e.g:

```csharp
public class ContactsService : Service
{
    [ClientCanSwapTemplates]
    public object Get(GetContacts request) => Db.Select<Contact>();
}
```

This Request Filter allows the client to [change the selected Razor **View** and **Template**](https://razor.netcore.io/#unified-stack) used at runtime. By default the view with the same name as the **Request** or **Response** DTO is used.

## Handling different HTTP Verbs

ServiceStack Services lets you handle any HTTP Verb in the same way, e.g this lets you respond with CORS headers to a HTTP **OPTIONS** request with:

```csharp
public class ContactsService : Service
{
    [EnableCors]
    public void Options(GetContact request) {}
}
```

Which if you now make an OPTIONS request to the above service, will emit the default `[EnableCors]` headers:

```csharp
var webReq = (HttpWebRequest)WebRequest.Create(Host + "/contacts");
webReq.Method = "OPTIONS";
using var webRes = webReq.GetResponse();
webRes.Headers["Access-Control-Allow-Origin"]     // *
webRes.Headers["Access-Control-Allow-Methods"]    // GET, POST, PUT, DELETE, OPTIONS
webRes.Headers["Access-Control-Allow-Headers"]    // Content-Type
```

### PATCH request example

Handling a PATCH request is just as easy, e.g. here's an example of using PATCH to handle a partial update of a Resource:

```csharp
[Route("/contacts/{Id}", "PATCH")]
public class UpdateContact : IReturn<Contact>
{
    public int Id { get; set; }
    public int Age { get; set; }
}

public Contact Patch(UpdateContact request)
{
    var Contact = request.ConvertTo<Contact>();
    Db.UpdateNonDefaults(Contact);
    return Db.SingleById<Contact>(request.Id);
}
```

And the client call is just as easy as you would expect:

```csharp
var response = client.Patch(new UpdateContact { Id = 1, Age = 18 });
```

Although sending different HTTP Verbs are unrestricted in native clients, they're unfortunately not allowed in some web browsers and proxies. So to simulate a PATCH from an AJAX request you need to set the **X-Http-Method-Override** HTTP Header.

## Structured Error Handling

When following the [explicit Response DTO Naming convention](/error-handling#error-response-types) ServiceStack will automatically populate the `ResponseStatus` property with a structured Error Response otherwise if returning other DTOs like naked collections ServiceStack will instead return a generic `ErrorResponse`, although this is mostly a transparent technical detail you don't need to know about as for schema-less formats like JSON they return the exact same wire-format.

[Error Handling](/error-handling) works naturally in ServiceStack where you can simply throw C# Exceptions, e.g:

```csharp
public List<Contact> Post(Contact request)
{
    if (!request.Age.HasValue)
        throw new ArgumentException("Age is required");

    Db.Insert(request.ConvertTo<Contact>());
    return Db.Select<Contact>();
}
```

This will result in an Error thrown on the client if it tried to create an empty Contact:

```csharp
try
{
    var response = client.Post(new Contact());
}
catch (WebServiceException webEx)
{
    webEx.StatusCode                    // 400
    webEx.StatusDescription             // ArgumentException
    webEx.ResponseStatus.ErrorCode      // ArgumentException
    webEx.ResponseStatus.Message        // Age is required
    webEx.ResponseDto is ErrorResponse  // true
}
```

The same Service Clients Exception handling is also used to handle any HTTP error generated in or outside of your service, e.g. here's how to detect if a HTTP Method isn't implemented or disallowed:

```csharp
try
{
    var response = client.Send(new SearchContacts());
}
catch (WebServiceException webEx)
{
    webEx.StatusCode                   // 405
    webEx.StatusDescription            // Method Not Allowed
}
```

In addition to standard C# exceptions your services can also return multiple, rich and detailed validation errors as enforced by [Fluent Validation's validators](/validation).

### Overriding the default Exception handling

You can override the default exception handling in ServiceStack by registering a `ServiceExceptionHandlers`, e.g:

```csharp
void Configure(Container container) 
{
    this.ServiceExceptionHandlers.Add((req, reqDto, ex) => {
        return ...;
    });
}
```

## Smart Routing

For the most part you won't need to know about this as ServiceStack's routing works as you would expect. Although this should still serve as a good reference to describe the resolution order of ServiceStack's Routes:

  1. Any exact Literal Matches are used first
  2. Exact Verb match is preferred over All Verbs
  3. The more variables in your route the less weighting it has
  4. When Routes have the same weight, the order is determined by the position of the Action in the service or Order of Registration (FIFO)

These Rules only come into play when there are multiple routes that matches the pathInfo of an incoming request.

Lets see some examples of these rules in action using the routes defined in the [API Design test suite](https://github.com/ServiceStack/ServiceStack/blob/master/tests/RazorRockstars.Console.Files/ReqStarsService.cs):

```csharp
[Route("/contacts")]
public class Contact {}

[Route("/contacts", "GET")]
public class GetContacts {}

[Route("/contacts/{Id}", "GET")]
public class GetContact {}

[Route("/contacts/{Id}/{Field}")]
public class ViewContact {}

[Route("/contacts/{Id}/delete")]
public class DeleteContact {}

[Route("/contacts/{Id}", "PATCH")]
public class UpdateContact {}

[Route("/contacts/reset")]
public class ResetContact {}

[Route("/contacts/search")]
[Route("/contacts/aged/{Age}")]
public class SearchContacts {}
```

These are results for these HTTP Requests

```
GET   /contacts           =>	GetContacts
POST  /contacts           =>	Contact
GET   /contacts/search    =>	SearchContacts
GET   /contacts/reset     =>	ResetContact
PATCH /contacts/reset     =>	ResetContact
PATCH /contacts/1         =>	UpdateContact
GET   /contacts/1         =>	GetContact
GET   /contacts/1/delete  =>	DeleteContact
GET   /contacts/1/foo     =>	ViewContact
```

And if there were multiple of the exact same routes declared like:

```csharp
[Route("/req/{Id}", "GET")]
public class Req2 {}

[Route("/req/{Id}", "GET")]
public class Req1 {}

public class MyService : Service {
    public object Get(Req1 request) { ... }		
    public object Get(Req2 request) { ... }		
}
```

The Route on the Action that was declared first gets selected, i.e:

```
GET /req/1              => Req1
```

### Populating Complex Type Properties on QueryString

ServiceStack uses the [JSV-Format](/jsv-format) (JSON without quotes) to parse QueryStrings.

JSV lets you embed deep object graphs in QueryString as seen [this example url](https://test.servicestack.net/json/reply/StoreLogs?Loggers=%5B%7BId:786,Devices:%5B%7BId:5955,Type:Panel,TimeStamp:1199303309,Channels:%5B%7BName:Temperature,Value:58%7D,%7BName:Status,Value:On%7D%5D%7D,%7BId:5956,Type:Tank,TimeStamp:1199303309,Channels:%5B%7BName:Volume,Value:10035%7D,%7BName:Status,Value:Full%7D%5D%7D%5D%7D%5D):

```
https://test.servicestack.net/json/reply/StoreLogs?Loggers=[{Id:786,Devices:[{Id:5955,Type:Panel,
    Channels:[{Name:Temperature,Value:58},{Name:Status,Value:On}]},
    {Id:5956,Type:Tank,TimeStamp:1199303309,
    Channels:[{Name:Volume,Value:10035},{Name:Status,Value:Full}]}]}]
```

## Advanced Usages

### Custom Hooks

The ability to extend ServiceStack's service execution pipeline with Custom Hooks is an advanced customization feature that for most times is not needed as the preferred way to add composable functionality to your services is to use [Request / Response Filter attributes](/filter-attributes) or apply them globally with [Global Request/Response Filters](/request-and-response-filters).

### Custom Serialized Responses

The new `IHttpResult.ResultScope` API provides an opportunity to execute serialization within a custom scope, e.g. this can
be used to customize the serialized response of adhoc services that's different from the default global configuration with:

```csharp
return new HttpResult(dto) {
    ResultScope = () => JsConfig.With(new Config { IncludeNullValues =  true })
};
```

Which enables custom serialization behavior by performing the serialization within the custom scope, equivalent to:

```csharp
using (JsConfig.With(new Config { IncludeNullValues =  true }))
{
    var customSerializedResponse = Serialize(dto);
}
```

### Request and Response Converters

The [Encrypted Messaging Feature](/auth/encrypted-messaging) takes advantage of Request and Response Converters that let you change the Request DTO and Response DTO's that get used in ServiceStack's Request Pipeline where:

#### Request Converters

Request Converters are executed directly after any [Custom Request Binders](/serialization-deserialization#create-a-custom-request-dto-binder):

```csharp
appHost.RequestConverters.Add(async (req, requestDto) => {
    //Return alternative Request DTO or null to retain existing DTO
});
```

#### Response Converters

Response Converters are executed directly after the Service:

```csharp
appHost.ResponseConverters.Add(async (req, response) =>
    //Return alternative Response or null to retain existing Service response
});
```

### Intercept Service Requests

As an alternative to creating a [Custom Service Runner](#using-a-custom-servicerunner) to intercept
different events when processing ServiceStack Requests, you can instead override the `OnBeforeExecute()`, `OnAfterExecute()` and `OnExceptionAsync()`
callbacks in your `Service` class (or base class) to intercept and modify Request DTOs, Responses or Error Responses, e.g:

```csharp
class MyServices : Service
{
    // Log all Request DTOs that implement IHasSessionId
    public override void OnBeforeExecute(object requestDto)
    {
        if (requestDto is IHasSessionId dtoSession)
        {
            Log.Debug($"{nameof(OnBeforeExecute)}: {dtoSession.SessionId}");
        }
    }

    //Return Response DTO Name in HTTP Header with Response
    public override object OnAfterExecute(object response)
    {
        return new HttpResult(response) {
            Headers = {
                ["X-Response"] = response.GetType().Name
            }
        };
    }

    //Return custom error with additional metadata
    public override Task<object> OnExceptionAsync(object requestDto, Exception ex)
    {
        var error = DtoUtils.CreateErrorResponse(requestDto, ex);
        if (error is IHttpError httpError)
        {                
            var errorStatus = httpError.Response.GetResponseStatus();
            errorStatus.Meta = new Dictionary<string,string> {
                ["InnerType"] = ex.InnerException?.GetType().Name
            };
        }
        return Task.FromResult(error);
    }
}
```

#### Async Callbacks

For async callbacks your Services can implement `IServiceBeforeFilterAsync` and `IServiceAfterFilterAsync`, e.g:

```csharp
public class MyServices : Service, IServiceBeforeFilterAsync, IServiceAfterFilterAsync
{
    public async Task OnBeforeExecuteAsync(object requestDto)
    {
        //...
    }

    public async Task<object> OnAfterExecuteAsync(object response)
    {
        //...
        return response;
    }
}
```

If you're implementing `IService` instead of inheriting the concrete `Service` class, you can implement the interfaces directly:

```csharp
// Handle all callbacks
public class MyServices : IService, IServiceFilters
{
    //..
}

// Or individually, just the callbacks you want
public class MyServices : IService, IServiceBeforeFilter, IServiceAfterFilter, IServiceErrorFilter
{
    //..
}
```

### Custom Service Runner

The [IServiceRunner](https://github.com/ServiceStack/ServiceStack/blob/master/src/ServiceStack.Interfaces/Web/IServiceRunner.cs) decouples the execution of your service from the implementation of it which provides an alternative custom hook which lets you add custom behavior to all Services without needing to use a base Service class. 

To add your own Service Hooks you just need to override the default Service Runner in your AppHost from its default implementation:

```csharp
public virtual IServiceRunner<TRequest> CreateServiceRunner<TRequest>(ActionContext actionContext)
{           
    return new ServiceRunner<TRequest>(this, actionContext); //Cached per Service Action
}
```

With your own:

```csharp
public override IServiceRunner<TRequest> CreateServiceRunner<TRequest>(ActionContext actionContext)
{           
    return new MyServiceRunner<TRequest>(this, actionContext); //Cached per Service Action
}
```

Where `MyServiceRunner<T>` is just a custom class implementing the custom hooks you're interested in, e.g:

```csharp
public class MyServiceRunner<T> : ServiceRunner<T> 
{
    public override OnBeforeExecute(IRequest req, TRequest request, object service) {
      // Called just before any Action is executed
    }

    public override Task<object> ExecuteAsync(IRequest req, object instance, TRequest requestDto) {
        // Called to execute the Service instance with the requestDto
        return base.ExecuteAsync(req, serviceInstance, requestDto);
    }

    public override object OnAfterExecute(IRequest req, object response, object service) {
      // Called just after any Action is executed, you can modify the response returned here as well
    }

    public override Task<object> HandleExceptionAsync(IRequest req, TRequest requestDto, Exception ex, object instance) {
      // Called whenever an exception is thrown in your Services Action
    }
}
```

## Limitations

One limitation of Services is that you can't split the handling of a single Resource (i.e. Request DTO) over multiple service implementations. If you find you need to do this because your service is getting too big, consider using partial classes to spread the implementation over multiple files. Another option is encapsulating some of the re-usable functionality into Logic dependencies and inject them into your service.

## Other Notes

Although they're not needed or used anywhere [you can also use HTTP Verb interfaces](https://github.com/ServiceStack/ServiceStack/blob/34acc429ee04053ea766e4fb183e7aad7321ef5e/src/ServiceStack.Interfaces/IService.cs#L27) to enforce the correct signature required by the services, e.g:

```csharp
public class MyService : Service, IAny<GetContacts>, IGet<SearchContacts>, IPost<Contact>
{
    public object Any(GetContacts request) { .. }
    public object Get(SearchContacts request) { .. }
    public object Post(Contact request) { .. }
}
```

This has no effect to the runtime behaviour and your services will work the same way with or without the added interfaces.


# Service Return Types
Source: https://docs.servicestack.net/service-return-types

From a birds-eye view ServiceStack can return any of:

  - Any **DTO** object -> serialized to Response ContentType
  - `HttpResult`, `HttpError`, `CompressedResult` or other `IHttpResult` for Customized HTTP response

#### Services should only return Reference Types

If a Value Type like `int` or `long` response is needed, it's recommended to wrap the Value Type in a Response DTO, e.g:

```csharp
public class MyResponse
{
    public int Result { get; set; }
}
```

Alternatively you can return a naked Value Type response by returning it as a `string`, e.g:

```csharp
public object Any(MyRequest request) => "1";
```

## Different Return Types

The following types are not converted (to different Content-Types) but get written directly to the Response Stream:

  - `String`
  - `Stream`
  - `IStreamWriter`
  - `byte[]` - with the `application/octet-stream` Content Type
  - `ReadOnlyMemory<char>`
  - `ReadOnlyMemory<byte>`
  
From the [HelloWorld ServiceStack.UseCase](https://github.com/ServiceStack/ServiceStack.UseCases/blob/master/HelloWorld/Global.asax.cs) demo:

```csharp
public class HelloService : Service
{
    public HelloResponse Get(Hello request)
    {
        return new HelloResponse { Result = $"Hello, {request.Name}!" };

        //C# client can call with:
        //var response = client.Get(new Hello { Name = "ServiceStack" });
    }

    public string Get(HelloHtml request)
    {
        return $"<h1>Hello, {request.Name}!</h1>";
    }

    [AddHeader(ContentType = "text/plain")]
    public string Get(HelloText request)
    {
        return $"<h1>Hello, {request.Name}!</h1>";
    }

    [AddHeader(ContentType = "image/png")]
    public Stream Get(HelloImage request)
    {
        var width = request.Width.GetValueOrDefault(640);
        var height = request.Height.GetValueOrDefault(360);
        var bgColor = request.Background != null ? Color.FromName(request.Background) : Color.ForestGreen;
        var fgColor = request.Foreground != null ? Color.FromName(request.Foreground) : Color.White;

        var image = new Bitmap(width, height);
        using (var g = Graphics.FromImage(image))
        {
            g.Clear(bgColor);

            var drawString = $"Hello, {request.Name}!";
            var drawFont = new Font("Times", request.FontSize.GetValueOrDefault(40));
            var drawBrush = new SolidBrush(fgColor);
            var drawRect = new RectangleF(0, 0, width, height);

            var drawFormat = new StringFormat {
                LineAlignment = StringAlignment.Center,
                Alignment = StringAlignment.Center };

            g.DrawString(drawString, drawFont, drawBrush, drawRect, drawFormat);

            var ms = new MemoryStream();
            image.Save(ms, ImageFormat.Png);
            return ms;
        }
    }
}
```

#### Live Examples of the above Hello Service:

  - [/hello/ServiceStack](http://bootstrapapi.apphb.com/api/hello/ServiceStack)
    - [/hello/ServiceStack?format=json](http://bootstrapapi.apphb.com/api/hello/ServiceStack?format=json)
  - [/hellotext/ServiceStack](http://bootstrapapi.apphb.com/api/hellotext/ServiceStack)
  - [/hellohtml/ServiceStack](http://bootstrapapi.apphb.com/api/hellohtml/ServiceStack)
  - [/helloimage/ServiceStack?Width=600&height=300&Foreground=Yellow](http://bootstrapapi.apphb.com/api/helloimage/ServiceStack?Width=600&height=300&Foreground=Yellow)


### Content-Type Specific Service Implementations

Service implementations can use `Verb{Format}` method names to provide a different implementation for handling a specific Content-Type, e.g. 
the Service below defines several different implementation for handling the same Request:

```csharp
[Route("/my-request")]
public class MyRequest 
{
    public string Name { get; set; }
}

public class ContentTypeServices : Service
{
    // Handles all other unspecified Verbs/Formats to /my-request
    public object Any(MyRequest request) => ...;

    // Handles GET /my-request for JSON responses
    public object GetJson(MyRequest request) => ..; 

    // Handles POST/PUT/DELETE/etc /my-request for HTML Responses
    public object AnyHtml(MyRequest request) =>  
        $@"<html>
            <body>
                <h1>AnyHtml {request.Name}</h1>
            </body>
        </html>";

    // Handles GET /my-request for HTML Responses
    public object GetHtml(MyRequest request) =>   
        $@"<html>
            <body>
                <h1>GetHtml {request.Name}</h1>
            </body>
        </html>";
}
```

This convention can be used for any of the formats listed in `ContentTypes.KnownFormats`, which by default includes:

 - json
 - xml
 - jsv
 - csv
 - html
 - protobuf
 - msgpack
 - wire

## Partial Content Support

Partial Content Support allows a resource to be split up an accessed in multiple chunks for clients that support HTTP Range Requests. This is a popular feature in download managers for resuming downloads of large files and streaming services for real-time streaming of content (e.g. consumed whilst it's being watched or listened to).

[HTTP Partial Content Support](http://benramsey.com/blog/2008/05/206-partial-content-and-range-requests/) is added in true ServiceStack-style where it's now automatically and transparently enabled for any existing services returning:

#### A Physical File

```csharp
return new HttpResult(new FileInfo(filePath), request.MimeType); 
```

#### A Virtual File

```csharp
return new HttpResult(VirtualFileSources.GetFile(virtualPath)); 
```

#### A Memory Stream

```csharp
return new HttpResult(ms, "audio/mpeg");
```

#### Raw Bytes

```csharp
return new HttpResult(bytes, "image/png");
```

#### Raw Text

```csharp
return new HttpResult(customText, "text/plain");
```

Partial Content was also added to static file downloads served directly through ServiceStack which lets you stream mp3 downloads or should you ever want to your static .html, .css, .js, etc.

You can disable Partial Content support with `Config.AllowPartialResponses = false;`.

See the [PartialContentResultTests](https://github.com/ServiceStack/ServiceStack/blob/master/tests/ServiceStack.WebHost.Endpoints.Tests/PartialContentResultTests.cs) for more examples.

## Writing directly to the Response Stream

In addition to returning plain C# objects, ServiceStack allows you to return any **Stream** or `IStreamWriterAsync` (which is a bit more flexible on how you write to the response stream):

```csharp
public interface IStreamWriterAsync
{
    Task WriteToAsync(Stream responseStream, CancellationToken token=default);
}
```

Both though allow you to write directly to the Response OutputStream without any additional conversion overhead.

### Customizing HTTP Headers

If you want to customize the HTTP headers at the same time you just need to implement [IHasOptions](https://github.com/ServiceStack/ServiceStack/blob/master/src/ServiceStack.Interfaces/Web/IHasOptions.cs) where any Dictionary Entry is written to the Response HttpHeaders.

```csharp
public interface IHasOptions
{
    IDictionary<string, string> Options { get; }
}
```

Further than that, the IHttpResult allows even finer-grain control of the HTTP output (status code, headers, ...) where you can supply a custom Http Response status code. You can refer to the implementation of the [HttpResult](https://github.com/ServiceStack/ServiceStack/blob/master/src/ServiceStack/HttpResult.cs) object for a real-world implementation of these above interfaces.

### Further customizing the HTTP Response

See the [Customize HTTP Responses](/customize-http-responses) page for more ways of customizing the HTTP Response.


# Design RESTful Services
Source: https://docs.servicestack.net/design-rest-services

ServiceStack encourages a message-based design so each Service should have its own distinct message (aka Request DTO) where it's able to use explicit properties to define what each Service accepts. Something to keep in mind 
is how you define and design your Services in ServiceStack are de-coupled in how you expose them which can be 
exposed under any custom Route. 

### Use a logical / hierarchical Url structure

We recommend adopting a logical hierarchically structured URL that represents the identifier of a resource, i.e. 
the parent path categorizes your resource and gives it meaningful context. So if you needed to design an API for  System that maintained **Events** and their **Reviews** it could adopt the following url structure:

```
/events             # all events
/events/1           # event #1
/events/1/reviews   # event #1 reviews
```

Where each of the above resource identifiers can be invoked using any HTTP **Verb** which represents the action to take on them, e.g:

```
GET    /events        # View all Events
POST   /events        # Create a new Event
PUT    /events/{Id}   # Update an existing Event
DELETE /events/{Id}   # Delete an existing Event
```

### Implementing RESTful Routes

For their implementation ServiceStack encourages a message-based design that groups all related operations based on **Response type** and **Call Context**. For an Events and Reviews system it could look something like:

```csharp
[Route("/events", "GET")]
[Route("/events/category/{Category}", "GET")]    // Optional GET example 
public class SearchEvents : IReturn<List<Event>>
{
    //resultset filter examples, e.g. ?Category=Tech&Query=servicestack
    public string Category { get; set; } 
    public string Query { get; set; }
}

[Route("/events", "POST")]
public class CreateEvent : IReturn<Event>
{
    public string Name { get; set; }
    public DateTime StartDate { get; set; }
}

[Route("/events/{Id}", "GET")]
[Route("/events/code/{EventCode}", "GET")] // Alternative Id
public class GetEvent : IReturn<Event>
{
    public int Id { get; set; }
    public string EventCode { get; set; } // Alternative to fetch Events
}

[Route("/events/{Id}", "PUT")]
public class UpdateEvent : IReturnVoid
{
    public int Id { get; set; }
    public string Name { get; set; }
    public DateTime StartDate { get; set; }
}
```

Event Reviews would follow a similar pattern:
    
```csharp
[Route("/events/{EventId}/reviews", "GET")]
public class GetEventReviews : IReturn<List<EventReview>>
{
    public int EventId { get; set; }
}

[Route("/events/{EventId}/reviews/{Id}", "GET")]
public class GetEventReview : IReturn<EventReview>
{
    public int EventId { get; set; }
    public int Id { get; set; }
}

[Route("/events/{EventId}/reviews", "POST")]
public class CreateEventReview : IReturn<EventReview>
{
    public int EventId { get; set; }
    public string Comments { get; set; }
}
```

The above REST Service examples returns naked Types and collections which 
[ServiceStack has a great story for](/api-design#structured-error-handling), however our personal preference is to 
design more coarse-grained and versionable [Message-based APIs](/design-message-based-apis) where we'd use an explicit Response DTO for each Service, e.g:

```csharp
[Route("/events/{EventId}/reviews", "GET")]
public class GetEventReviews : IReturn<GetEventReviewsResponse>
{
    public int EventId { get; set; }
}

public class GetEventReviewsResponse
{
    public List<EventReview> Results { get; set; }
}

[Route("/events/{EventId}/reviews/{Id}", "GET")]
public class GetEventReview : IReturn<GetEventReviewResponse>
{
    public int EventId { get; set; }
    public int Id { get; set; }
}

public class GetEventReviewResponse
{
    public EventReview Result { get; set; }
    public ResponseStatus ResponseStatus { get; set; }  // inject structured errors if any
}

[Route("/events/{EventId}/reviews", "POST")]
public class CreateEventReview : IReturn<CreateEventReviewResponse>
{
    public int EventId { get; set; }
    public string Comments { get; set; }
}

public class CreateEventReviewResponse 
{
    public EventReview Result { get; set; }
    public ResponseStatus ResponseStatus { get; set; }
}
```

### Notes

The implementation of each Services then becomes straight-forward based on these messages, which (depending on code-base size) we'd recommend organizing in 2 **EventsService** and **EventReviewsService** classes.

Although `UpdateEvent` and `CreateEvent` are seperate Services here, if the use-case permits they can instead be handled by a single idempotent `StoreEvent` Service.

## [Physical Project Structure](/physical-project-structure)

Ideally the root-level **AppHost** project should be kept lightweight and implementation-free. Although for small projects or prototypes with only a few services it's ok for everything to be in a single project and to simply grow your architecture when and as needed. 

For medium-to-large projects we recommend the physical structure below which for the purposes of this example we'll assume our Application is called **Events**. 

The order of the projects also show its dependencies, e.g. the top-level `Events` project references **all** sub projects whilst the last `Events.ServiceModel` project references **none**:

```
    /Events
        AppHost.cs              // ServiceStack Web or Self Host Project

    /Events.ServiceInterface    // Service implementations (akin to MVC Controllers)
        EventsService.cs
        EventsReviewsService.cs

    /Events.Logic               // For large projects: extract C# logic, data models, etc
        IGoogleCalendarGateway  // E.g of a external dependency this project could use

    /Events.ServiceModel        // Service Request/Response DTOs and DTO types
        Events.cs               // SearchEvents, CreateEvent, GetEvent DTOs 
        EventReviews.cs         // GetEventReviews, CreateEventReview
        Types/
          Event.cs              // Event type
          EventReview.cs        // EventReview type
```

With the `Events.ServiceModel` DTO's kept in their own separate implementation and dependency-free dll, you're freely able to share this dll in any .NET client project as-is - which you can use with any of the generic [C# Service Clients](/csharp-server-events-client) to provide an end-to-end typed API without any code-gen.

## More Info

 - This recommended project structure is embedded in all [ServiceStackVS VS.NET Templates](/templates/).
 - The [Simple Customer REST Example](/why-servicestack#simple-customer-database-rest-services-example) is a small self-contained, real-world example of creating a simple REST Service utilizing an RDBMS.


# Design Message-based APIs
Source: https://docs.servicestack.net/design-message-based-apis

To give you a flavor of the differences you should think about when designing message-based services in ServiceStack we'll 
look at some examples to contrast WCF/WebApi vs ServiceStack's approach:

## WCF vs ServiceStack API Design

WCF encourages you to think of web services as normal C# method calls, e.g:

```csharp
public interface IWcfCustomerService
{
    Customer GetCustomerById(int id);
    List<Customer> GetCustomerByIds(int[] id);
    Customer GetCustomerByUserName(string userName);
    List<Customer> GetCustomerByUserNames(string[] userNames);
    Customer GetCustomerByEmail(string email);
    List<Customer> GetCustomerByEmails(string[] emails);
}
```

This is what the same Service contract would look like in ServiceStack:

```csharp
public class Customers : IReturn<List<Customer>> 
{
    public int[] Ids { get; set; }
    public string[] UserNames { get; set; }
    public string[] Emails { get; set; }
}
```
    
The important concept to keep in mind is that the entire query (aka Request) is captured in the Request Message 
(i.e. Request DTO) and not in the server method signatures. The obvious immediate benefit of adopting a message-based 
design is that any combination of the above RPC calls can be fulfilled in 1 remote message, by a single service implementation 
which improves cacheability and simplifies maintenance and testing with the reduced API surface area.

## WebApi vs ServiceStack API Design

Likewise WebApi promotes a similar C#-like RPC Api that WCF does:

```csharp
public class ProductsController : ApiController 
{
    public IEnumerable<Product> GetAllProducts() 
    {
        return products;
    }

    public Product GetProductById(int id) 
    {
        var product = products.FirstOrDefault((p) => p.Id == id);
        if (product == null)
        {
            throw new HttpResponseException(HttpStatusCode.NotFound);
        }
        return product;
    }

    public Product GetProductByName(string categoryName) 
    {
        var product = products.FirstOrDefault((p) => p.Name == categoryName);
        if (product == null)
        {
            throw new HttpResponseException(HttpStatusCode.NotFound);
        }
        return product;
    }

    public IEnumerable<Product> GetProductsByCategory(string category) 
    {
        return products.Where(p => string.Equals(p.Category, category,
                StringComparison.OrdinalIgnoreCase));
    }

    public IEnumerable<Product> GetProductsByPriceGreaterThan(decimal price) 
    {
        return products.Where((p) => p.Price > price);
    }
}
```

### ServiceStack Message-Based API Design

Whilst ServiceStack encourages you to retain a Message-based Design:

```csharp
public class SearchProducts : IReturn<List<Product>> 
{
    public string Category { get; set; }
    public decimal? PriceGreaterThan { get; set; }
}

public class GetProduct : IReturn<Product> 
{
    public int? Id { get; set; }
    public string Name { get; set; }
}

public class ProductsService : Service 
{
    public object Get(SearchProducts request) 
    {
        var ret = products.AsQueryable();
        if (request.Category != null)
            ret = ret.Where(x => x.Category == request.Category);
        if (request.PriceGreaterThan.HasValue)
            ret = ret.Where(x => x.Price > request.PriceGreaterThan.Value);            
        return ret.ToList();
    }

    public Product Get(GetProduct request) 
    {
        var product = request.Id.HasValue
            ? products.FirstOrDefault(x => x.Id == request.Id.Value)
            : products.FirstOrDefault(x => x.Name == request.Name);

        if (product == null)
            throw new HttpError(HttpStatusCode.NotFound, "Product does not exist");

        return product;
    }
}
```

Again capturing the essence of the Request in the Request DTO. The message-based design is also able to condense 
**5 separate RPC** WebAPI Services into **2 message-based** ServiceStack Services. 

## Group by Call Semantics and Response Types

It's grouped into 2 different services in this example based on **Call Semantics** and **Response Types**:

Every property in each Request DTO has the same semantics that is for `SearchProducts` each property acts like a Filter 
(e.g. an AND) whilst in `GetProduct` it acts like a combinator (e.g. an OR). The Services also return `List<Product>` 
and `Product` return types which will require different handling in the call-sites of Typed APIs.

In WCF / WebAPI (and other RPC services frameworks) whenever you have a client-specific requirement you would add a new 
Server signature on the controller that matches that request. In ServiceStack's message-based approach however you're 
instead encouraged to think about where this feature intuitively fits and whether you're able to enhance existing services. 
You should also be thinking about how you can support the client-specific requirement in a **generic way** so that the 
same service could benefit other future potential use-cases.

### Separate One and Many Services

We can use the above context as a guide to design new Services. If we needed to design a Bookings System that needed an API
to return **All Bookings** and a **Single Booking** we'd use a separate Services as they'd have different Response Types, e.g. 
`GetBooking` returns 1 booking whilst `GetBookings` returns many.

### Distinguish Service Operations vs Types 

There should be a clean split between your Operations (aka Request DTOs) which is unique per service and is used to capture the 
Services' request, and the DTO types they return. Request DTOs are usually actions so they're verbs, whilst DTO types are 
entities/data-containers so they're nouns. 

### Returning naked collections

ServiceStack can return naked collections that [don't require a ResponseStatus](/error-handling#error-response-types) property 
since if it doesn't exist the generic `ErrorResponse` DTO will be thrown and serialized on the client instead which frees you 
from having your Responses contain `ResponseStatus` property. 

### Returning coarse-grained Response DTOs

However since they offer better versionability that can later be extended to return more results without breaking existing 
clients we prefer specifying explicit Response DTOs for each Service, although this is entirely optional. So our preferred 
message-based would look similar to:

```csharp
// Operations
[Route("/bookings/{Id}")]
public class GetBooking : IReturn<GetBookingResponse>
{
    public int Id { get; set; }
}

public class GetBookingResponse
{
    public Booking Result { get; set; }
    public ResponseStatus ResponseStatus { get; set; } // inject structured errors
}

[Route("/bookings/search")]
public class SeachBookings : IReturn<SeachBookingsResponse>
{      
    public DateTime BookedAfter { get; set; }
}

public class SeachBookingsResponse
{
    public List<BookingLimit> Results { get; set; }
    public ResponseStatus ResponseStatus { get; set; } // inject structured errors 
}

// Types
public class Booking
{
    public int Id { get; set; }
    public int ShiftId { get; set; }
    public DateTime StartDate { get; set; }
    public DateTime EndDate { get; set; }
    public int Limit { get; set; }
}
```

When they're not ambiguous we'll typiclly leave out specifying the **Verb** in `[Route]` definitions for **GET** Requests as its unnecessary.

### Using AutoQuery

Where possible we'll also use [AutoQuery for Search Services](/autoquery/rdbms) which require dramatically less effort whilst
offering a lot more functionality out-of-the-box. E.g. The Search Bookings Service with AutoQuery could adopt the same Customer
Route and properties:

```csharp
[Route("/bookings/search")]
public class SeachBookings : QueryDb<Booking>
{      
    public DateTime BookedAfter { get; set; }
}
```

But no implementation is needed as AutoQuery automatically creates the optimal implementation. AutoQuery also supports [Implicit Conventions](/autoquery/rdbms#implicit-conventions) where you're able to filter by any of `Booking` table columns without any additional code or effort.

### Keep a consistent Nomenclature

You should reserve the word **Get** on services which query on unique or Primary Keys fields, i.e. when a supplied value 
matches a field (e.g. Id) it only **Gets** 1 result. For "Search Services" that acts like a filter and returns multiple 
matching results which falls within a desired range we recommend using prefixing Services with the **Search** or **Find** verbs 
to signal the behavior of the Service.

### Self-describing Service Contracts

Also try to be descriptive with each of your field names, these properties are part of your **public API** and should be 
self-describing as to what it does. E.g. By just looking at the Service Contract (e.g. Request DTO) we'd have no idea what 
a plain **Date** property means, as it could mean either **BookedAfter**, **BookedBefore** or **BookedOn** if it only returned 
bookings made on that Day. 

The benefit of this is now the call-sites of your [Typed .NET clients](/csharp-client) become easier to read:

```csharp
Product product = client.Get(new GetProduct { Id = 1 });

var response = client.Get(new SearchBookings { BookedAfter = DateTime.Today });
```

## Service implementation

[Filter Attributes](/filter-attributes) can be applied on either the **class** or **method** level, so when you need to secure all Operations within a given Service you can just annotate the top-level Service class with the `[Authenticate]`, e.g:

```csharp
[Authenticate]
public class BookingsService : Service 
{ 
    public object Get(GetBooking request) => ...;

    public object Get(SearchBookings request) => ...;
}
```

## Error Handling and Validation

For info on how to add validation you either have the option to just [throw C# exceptions](/error-handling#throwing-c-exceptions) 
and apply your own customizations to them, in addition you also have the option to use the built-in 
[Declarative Validator](/declarative-validation) attributes on your Request DTO:

```csharp
[ValidateIsAuthenticated]
public class CreateBooking : IPost, IReturn<CreateBookingResponse>
{
    [ValidateNotNull]
    public DateTime? StartDate { get; set; }

    [ValidateGreatorThan(0)]
    public int ShiftId { get; set; }

    [ValidateGreatorThan(0)]
    public int Limit { get; set; }
}
```

Or for more control you can use custom [Fluent Validation](/validation) validators. Validators are no-touch and invasive free meaning you can add them using a layered approach and maintain them without modifying the service implementation or DTO classes. Since they require an extra class We'd only use them on operations with side-effects e.g. **POST** or **PUT**, as **GET** requests tend to have minimal validation so throwing C# Exceptions typically requires less boilerplate. Here's an example of a validator you could have when creating a Booking:

```csharp
public class CreateBookingValidator : AbstractValidator<CreateBooking>
{
    public CreateBookingValidator()
    {
        RuleFor(r => r.StartDate).NotEmpty();
        RuleFor(r => r.ShiftId).NotEmpty().GreaterThan(0);
        RuleFor(r => r.Limit).NotEmpty().GreaterThan(0);
    }
}
```

Depending on the use-case instead of having separate `CreateBooking` and `UpdateBooking` DTOs you could re-use the same 
`StoreBooking` Request DTO to handle both operations.


# Modular Startup
Source: https://docs.servicestack.net/modular-startup

::: info
For more information on the earlier Modular Startup in ServiceStack **v5.x** see our [Legacy Modular Startup](/modular-startup-legacy) docs
:::

Taking advantage of C# 9 top level statements and .NET 6 [WebApplication Hosting Model](https://gist.github.com/davidfowl/0e0372c3c1d895c3ce195ba983b1e03d), ServiceStack templates by utilize both these features to simplify configuring your AppHost in a modular way.

`Program.cs` becomes a script-like file since C# 9 top level statements are generating application entry point implicitly.

```csharp
var builder = WebApplication.CreateBuilder(args);

var app = builder.Build();

// Configure the HTTP request pipeline.
if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error");
    app.UseHsts();
    app.UseHttpsRedirection();
}

app.UseServiceStack(new AppHost())
app.Run();
```

The application `AppHost` hooks into startup using `HostingStartup` assembly attribute.
In ServiceStack templates, this uses the file name prefix of `Configure.*.cs` to help 
identify these startup modules.

All ServiceStack's features are loaded using .NET's `HostingStartup`, including ServiceStack's `AppHost` itself that's
now being configured in [Configure.AppHost.cs](https://github.com/NetCoreTemplates/web/blob/master/MyApp/Configure.AppHost.cs), e.g:

```csharp
[assembly: HostingStartup(typeof(MyApp.AppHost))]

namespace MyApp;

public class AppHost() : AppHostBase("MyApp"), IHostingStartup
{
    public void Configure(IWebHostBuilder builder) => builder
        .ConfigureServices(services => {
            // Configure ASP.NET Core IOC Dependencies
        });

    public override void Configure()
    {
        // Configure ServiceStack, Run custom logic after ASP.NET Core Startup
        SetConfig(new HostConfig {
        });
    }
}
```

The use of Modular Startup does not change the AppHost declaration, but enables the modular grouping of configuration concerns.
Different features are encapsulated together allowing them to be more easily updated or replaced,
e.g. each feature could be temporarily disabled by commenting out its assembly HostingStartup's attribute:

```csharp
//[assembly: HostingStartup(typeof(MyApp.AppHost))]
```

## Module composition using `mix`

This has enabled ServiceStack Apps to be easily composed with the features developers need in mind. Either at project creation with servicestack.net/start page or after a project's creation where features can easily be added and removed using the command-line [mix tool](/mix-tool) where
you can view all available mix gists that can be added to projects with:

:::sh
x mix
:::

.NET 6's idiom is incorporated into the [mix gist config files](https://gist.github.com/gistlyn/9b32b03f207a191099137429051ebde8) to adopt its `HostingStartup` which is better able to load modular Startup configuration without assembly scanning.

This is a standard ASP .NET Core feature that we can use to configure Mongo DB in any ASP .NET Core App with:

:::sh
x mix mongodb
:::

Which adds the `mongodb` gist file contents to your ASP .NET Core Host project:

```csharp
using Microsoft.AspNetCore.Hosting;
using Microsoft.Extensions.DependencyInjection;
using MongoDB.Driver;

[assembly: HostingStartup(typeof(MyApp.ConfigureMongoDb))]

namespace MyApp;

public class ConfigureMongoDb : IHostingStartup
{
    public void Configure(IWebHostBuilder builder) => builder
        .ConfigureServices((context, services) => {
            var mongoClient = new MongoClient();
            IMongoDatabase mongoDatabase = mongoClient.GetDatabase("MyApp");
            services.AddSingleton(mongoDatabase);
        });
}    
```

As it's not a ServiceStack feature it can be used to configure ASP .NET Core Apps with any feature,
e.g. we could also easily configure [Marten](https://martendb.io) in an ASP .NET Core App with:

:::sh
x mix marten
:::

The benefit of this approach is entire modules of features can be configured in a single command, e.g. An empty
ServiceStack App can be configured with MongoDB, ServiceStack Auth and a MongoDB Auth Repository with a single command:


:::sh
x mix auth auth-mongodb mongodb
:::

Likewise, you can replace MongoDB with a completely different PostgreSQL RDBMS implementation by running:

:::sh
x mix auth auth-db postgres
:::

### Services and App Customizations

Modular Startup configurations are flexible enough to encapsulate customizing ASP.NET Core's IOC and the built `WebApplication`
by registering a `IStartupFilter` which is required by the Open API v3 Modular Configuration:

:::sh
x mix openapi3
:::

```csharp
[assembly: HostingStartup(typeof(MyApp.ConfigureOpenApi))]

namespace MyApp;

public class ConfigureOpenApi : IHostingStartup
{
    public void Configure(IWebHostBuilder builder) => builder
        .ConfigureServices((context, services) =>
        {
            if (context.HostingEnvironment.IsDevelopment())
            {
                services.AddEndpointsApiExplorer();
                services.AddSwaggerGen();

                services.AddServiceStackSwagger();
                services.AddBasicAuth<Data.ApplicationUser>();
                //services.AddJwtAuth();

                services.AddTransient<IStartupFilter, StartupFilter>();
            }
        });

    public class StartupFilter : IStartupFilter
    {
        public Action<IApplicationBuilder> Configure(Action<IApplicationBuilder> next) => app =>
        {
            app.UseSwagger();
            app.UseSwaggerUI();
            next(app);
        };
    }
}
```

### ConfigureAppHost

Looking deeper, we can see where we're plugins are able to configure ServiceStack via the `.ConfigureAppHost()` extension method to 
execute custom logic on `AppHost` Startup:

```csharp
[assembly: HostingStartup(typeof(MyApp.ConfigureAutoQuery))]

namespace MyApp;

public class ConfigureAutoQuery : IHostingStartup
{
    public void Configure(IWebHostBuilder builder) => builder
        .ConfigureServices(services => {
            // Enable Audit History
            services.AddSingleton<ICrudEvents>(c =>
                new OrmLiteCrudEvents(c.GetRequiredService<IDbConnectionFactory>()));

            // For TodosService
            services.AddPlugin(new AutoQueryDataFeature());

            // For Bookings https://docs.servicestack.net/autoquery-crud-bookings
            services.AddPlugin(new AutoQueryFeature
            {
                MaxLimit = 1000,
                //IncludeTotal = true,
            });
        })
        .ConfigureAppHost(appHost => {
            appHost.Resolve<ICrudEvents>().InitSchema();
        });
}
```

### Customize AppHost at different Startup Lifecycles

By default, any AppHost configuration is called before `AppHost.Configure()` is run, but to cater for all plugins, AppHost configurations can be registered at different stages within the AppHost's initialization:

```csharp
public void Configure(IWebHostBuilder builder) => builder
    .ConfigureAppHost(
        beforeConfigure:    appHost => /* fired before AppHost.Configure() */, 
        afterConfigure:     appHost => /* fired after AppHost.Configure() */,
        afterPluginsLoaded: appHost => /* fired after plugins are loaded */,
        afterAppHostInit:   appHost => /* fired after AppHost has initialized */);
```

### Removing Features

The benefits of adopting a modular approach to AppHost configuration is the same as general organizational code structure which results
in better decoupling and cohesion where it's easier to determine all the dependencies of a feature, easier to update, less chance of
unintended side effects, easier to share standard configuration amongst multiple projects and easier to remove the feature entirely,
either temporarily if needing to isolate & debug a runtime issue by:

```csharp
// [assembly: HostingStartup(typeof(MyApp.ConfigureAuth))]
```

Or easier to permanently replace or remove features by either directly deleting the isolated `*.cs` source files or by undoing mixing in the feature
using `mix -delete`, e.g:

:::sh
x mix -delete auth auth-db postgres
:::

Which works similar to package managers where it removes all files contained within each mix gist.

::: info
Please see the [Mix HowTo](https://gist.github.com/gistlyn/9b32b03f207a191099137429051ebde8#file-mix_howto-md) to find out how you can contribute your own gist mix features
:::

## Migrating to HostingStartup

As we'll be using the new `HostingStartup` model going forward we recommend migrating your existing configuration to use them.

<lite-youtube class="w-full mx-4 my-4" width="560" height="315" videoid="WgsFl0AFUdo" style="background-image: url('https://img.youtube.com/vi/WgsFl0AFUdo/maxresdefault.jpg')"></lite-youtube>

To help with this you can refer to the [mix diff](https://github.com/ServiceStack/mix/commit/b56746622aa1879e3e6a8cbf835e634f05db30db)
showing how each of the existing mix configurations were converted to the new model.

As a concrete example, lets take a look at the steps used to migrate our Chinook example application [from NET5 using the previous `Startup : ModularStartup`, to .NET 6 `HostingStartup`](https://github.com/NetCoreApps/Chinook/commit/2758af9deae9c3aa910a27134f95167f7ec6e541).

### Step 1
Migrate your existing `ConfigureServices` and `Configure(IApplicationBuilder)` from `Startup : ModularStartup` to the top-level host builder in `Program.cs`. Eg

```csharp
var builder = WebApplication.CreateBuilder(args);
var app = builder.Build();

// Configure the HTTP request pipeline.
if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Error");
    // The default HSTS value is 30 days. 
    // You may want to change this for production scenarios, see https://aka.ms/aspnetcore-hsts.
    app.UseHsts();
    app.UseHttpsRedirection();
}

app.Run();
```

### Step 2

Move your `AppHost` class to a new `Configure.AppHost.cs` file.

### Step 3
Implement `IHostingStartup` on your AppHost with automatic initialization. Eg:

```csharp
public void Configure(IWebHostBuilder builder)
{
    builder.ConfigureServices(services => {
        // Configure ASP.NET Core IOC Dependencies
    });
}
```

### Step 4

Declare `assembly: HostingStartup` for your `AppHost` in the same `Configure.AppHost.cs`. Eg:

```csharp
[assembly: HostingStartup(typeof(Chinook.AppHost))]
```

### Step 5

Migrate each existing modular startup class that implements `IConfgiureServices` and/or `IConfigureApp` to use `IHostingStartup`. Eg:

```csharp
// net5.0 modular startup
using ServiceStack;

namespace Chinook;

public class ConfigureAutoQuery : IConfigureAppHost
{
    public void Configure(IAppHost appHost)
    {
        appHost.Plugins.Add(new AutoQueryFeature {
            MaxLimit = 1000,
            IncludeTotal = true
        });
    }
}
```

```csharp
// net8.0 modular startup using IHostingStartup
using Microsoft.AspNetCore.Hosting;
using ServiceStack;

[assembly: HostingStartup(typeof(Chinook.ConfigureAutoQuery))]

namespace Chinook;

public class ConfigureAutoQuery : IHostingStartup
{
    public void Configure(IWebHostBuilder builder) => builder
        .ConfigureServices(services => {
            services.AddPlugin(new AutoQueryFeature {
                MaxLimit = 1000,
                IncludeTotal = true
            });
        });
}
```

> Remembering also that infrastructure like your `Dockerfile` or host will likely need the runtimes/SDKs updated as well.


# ServiceStack&#x27;s .NET Core Utility Belt
Source: https://docs.servicestack.net/dotnet-tool

Our `x` and `app` dotnet tools are a versatile invaluable companion for all ServiceStack developers where it's 
jam packed with functionality to power a number of exciting scenarios where it serves as a [Sharp App](https://sharpscript.net/docs/sharp-apps) 
delivery platform where they can be run as a .NET Core Windows Desktop App with `app` or as a cross-platform Web App launcher using `web` and we've already how it's now a [`#Script` runner](https://sharpscript.net/docs/sharp-scripts) with `x run` and into a 
[Live `#Script` playground](https://sharpscript.net/docs/sharp-scripts#live-script-with-web-watch) with `x watch`.

These tools contains all the functionality ServiceStack Developers or API consumers need that can be used 
[Create ServiceStack projects](/dotnet-new), run [Gist Desktop Apps](https://sharpscript.net/sharp-apps/gist-desktop-apps) 
or generate typed endpoints for consuming ServiceStack Services by either
[Add/Update ServiceStack References](/add-servicestack-reference) or by generating [gRPC client proxies](/grpc#grpc-clients).

## Install

To access available features, install with:

:::sh
dotnet tool install --global x 
:::

### Update

Or if you had a previous version installed, update with:

:::sh
dotnet tool update -g x
:::

::: info
Both `x` and `app` have equivalent base functionality, whilst `app` has superset [Windows-only Desktop features](/netcore-windows-desktop)
:::

::: info
To update and download Add ServiceStack Reference dtos without .NET see [npx get-dtos](/npx-get-dtos)
:::

## Usage

Then run `x` without any arguments to view Usage:

:::sh
x
:::

```txt
Usage:

  x new                     List available Project Templates
  x new <template> <name>   Create New Project From Template
  x download <user>/<repo>  Download latest GitHub Repo Release
  x get <url>               Download URL to file                     (-out <file|dir>)
  x stream <url>            Stream URL contents to console stdout

  x mix                     Show available gists to mixin            (Alias '+')
  x mix <name>              Write gist files locally, e.g:           (Alias +init)
  x mix init                Create empty .NET Core ServiceStack App
  x mix [tag]               Search available gists
  x mix <gist-url>          Write all Gist text files to current directory
  x gist <gist-id>          Write all Gist text files to current directory

  x publish                 Publish Current Directory to Gist        (requires token)
  x gist-new <dir>          Create new Gist with Directory Files     (requires token)
  x gist-update <id> <dir>  Update Gist ID with Directory Files      (requires token)
  x gist-open <gist>        Download and open Gist folder            (-out <dir>)

  x <lang>                  Update all ServiceStack References in directory (recursive)
  x <file>                  Update existing ServiceStack Reference (e.g. dtos.cs)
  x <lang>     <url> <file> Add ServiceStack Reference and save to file name
  x csharp     <url>        Add C# ServiceStack Reference            (Alias 'cs')
  x typescript <url>        Add TypeScript ServiceStack Reference    (Alias 'ts')
  x swift      <url>        Add Swift ServiceStack Reference         (Alias 'sw')
  x java       <url>        Add Java ServiceStack Reference          (Alias 'ja')
  x kotlin     <url>        Add Kotlin ServiceStack Reference        (Alias 'kt')
  x dart       <url>        Add Dart ServiceStack Reference          (Alias 'da')
  x fsharp     <url>        Add F# ServiceStack Reference            (Alias 'fs')
  x vbnet      <url>        Add VB.NET ServiceStack Reference        (Alias 'vb')
  x tsd        <url>        Add TypeScript Definition ServiceStack Reference

  x proto <url>             Add gRPC .proto ServiceStack Reference
  x proto <url> <name>      Add gRPC .proto and save to <name>.services.proto
  x proto                   Update all gRPC *.services.proto ServiceStack References
  x proto-langs             Display list of gRPC supported languages
  x proto-<lang> <url>      Add gRPC .proto and generate language    (-out <dir>)
  x proto-<lang> <file|dir> Update gRPC .proto and re-gen language   (-out <dir>)
  x proto-<lang>            Update all gRPC .proto's and re-gen lang (-out <dir>)

  x open                    List of available Sharp Apps
  x open <app>              Install and run Sharp App

  x run                     Run Sharp App in current directory
  x run <name>              Run Installed Sharp App
  x run path/app.settings   Run Sharp App at directory containing specified app.settings

  x install                 List available Sharp Apps to install     (Alias 'l')
  x install <app>           Install Sharp App                        (Alias 'i')

  x uninstall               List Installed Sharp Apps
  x uninstall <app>         Uninstall Sharp App

  x alias                   Show all local gist aliases (for usage in mix or app's)
  x alias <alias>           Print local alias value
  x alias <alias> <gist-id> Set local alias with Gist Id or Gist URL
  x unalias <alias>         Remove local alias

  x shortcut                Create Shortcut for Sharp App
  x shortcut <name>.dll     Create Shortcut for .NET Core App

  x scripts                 List all available package.json scripts
  x scripts <name>          Run package.json script

  x run <name>.ss           Run #Script within context of AppHost   (or <name>.html)
  x watch <name>.ss         Watch #Script within context of AppHost (or <name>.html)
                            Language File Extensions:
                              .ss - #Script source file
                              .sc - #Script `code` source file
                              .l  - #Script `lisp` source file
  x lisp                    Start Lisp REPL

  dotnet tool update -g x   Update to latest version

Options:
    -h, --help, ?             Print this message
    -v, --version             Print this version
    -d, --debug               Run in Debug mode for Development
    -r, --release             Run in Release mode for Production
    -s, --source              Change GitHub Source for App Directory
    -f, --force               Quiet mode, always approve, never prompt   (Alias 'y')
    -e, --eval                Evaluate #Script Code
        --token               Use GitHub Auth Token
        --clean               Delete downloaded caches
        --verbose             Display verbose logging
        --ignore-ssl-errors   Ignore SSL Errors
```

### Add/Update ServiceStack References

This shows us we can Add a ServiceStack Reference with `x <lang> <baseurl>` which will let us create a TypeScript Reference 
to the new [World Validation](/world-validation) App using its `ts` file extension alias:


:::sh
x ts http://validation.web-app.io
:::

Output:
```
Saved to: dtos.ts
```

Or create a C# ServiceStack Reference with:

:::sh
x cs http://validation.web-app.io
:::

Output:
```
Saved to: dtos.cs
```

To update run `x <lang>` which will recursively update all existing ServiceStack References:

:::sh
x ts
:::

Output:
```
Updated: dtos.ts
```

### Integrate with Visual Studio

You can also easily integrate this within your VS.NET dev workflows by [adding it as an External Tool](https://docs.microsoft.com/en-us/visualstudio/ide/managing-external-tools?view=vs-2019) in the **External Tools** dialog box by choosing `Tools > External Tools`:

![](/img/pages/servicestack-reference/tool-ts-reference.png)

|  ||
|-|-|
| Title             | Update TypeScript &Reference |
| Command           | web.exe |
| Arguments         | ts |
| Initial directory | $(ProjectDir) |
|  ||

Which will then let you update all your `*dtos.ts` TypeScript References in your project by clicking on `Tools > Update TypeScript Reference` 
or using the `ALT+T R` keyboard shortcut.

If you wanted to Update your `*dtos.cs` **C# ServiceStack References** instead, just change Arguments to `cs`:

![](/img/pages/servicestack-reference/tool-cs-reference.png)

|  ||
|-|-|
| **Title**             | Update C# &Reference |
| **Command**           | web.exe |
| **Arguments**         | cs |
| **Initial directory** | $(ProjectDir) |
|  ||

Refer to the [x usage output](#usage) above for the arguments or aliases for all other supported languages.

### Integrate with Rider

Just like with VS.NET above you can [add an External Tool](https://www.jetbrains.com/help/rider/Settings_Tools_External_Tools.html) 
in [JetBrains Rider](https://www.jetbrains.com/rider/) by opening the Settings dialog with `CTRL+ALT+S` then searching for `external tools` 
under the **Tools** category:

![](/img/pages/servicestack-reference/rider-tool-ts-reference.png)

|  ||
|-|-|
| **Name**              | Update TypeScript Reference |
| **Command**           | web.exe |
| **Arguments**         | ts |
| **Working directory** | $FileParentDir$ |
|  ||

Now you can update your `*dtos.ts` TypeScript References in your project by clicking on `External Tools > Update TypeScript Reference`
in the right-click context menu:

![](/img/pages/servicestack-reference/rider-tool-ts-reference-run.png)

If you're updating references frequently you can save time by [assigning it a keyboard shortcut](https://www.jetbrains.com/help/rider/Configuring_Keyboard_and_Mouse_Shortcuts.html).

### Create new Project Templates

See [x new](/web-new) for available Project Templates you can create with:

:::sh
x new
:::

### Mix Features into existing ASP.NET Core Apps

The `x` dotnet tool is a versatile utility belt packed with a number of features to simplify discovering, installing, running and deploying 
.NET Core Apps. You can view the full list of supported commands by running `x ?`, e.g. another useful command is using [`x mix`](/mix-tool)
for generating pre-set templates:

```
x mix                     Show available gists to mixin         (Alias '+')
x mix <name>              Write gist files locally, e.g:        (Alias +init)
x mix init                Create empty .NET Core ServiceStack App
x mix [tag]               Search available gists
x gist <gist-id>          Write all Gist text files to current directory
```

View available gists with:

:::sh
x mix
:::

Where you can use `x mix nginx` to generate a common nginx template configuration for reverse proxying .NET Core Apps, making configuring 
[Linux deployment servers for your .NET Core Apps](/netcore-deploy-rsync) less tedious. 

In addition to the pre-set templates, you can create your own [public GitHub gist](https://gist.github.com) with any number of different files customized 
for your Environment that anyone can write to their current directory with **the gist id** or **gist URL**:

:::sh
`x gist <gist-id>`
:::

### Patch JSON files

The `x` dotnet tool also includes a number of utilities for patching JSON files, e.g. you can use `x patch` to patch a JSON file with a [JSON Patch](https://learn.microsoft.com/en-us/aspnet/core/web-api/jsonpatch?view=aspnetcore-7.0).

The `json.patch` file supports the following JSON Patch operations:

| Operation | Notes                                                                              |
|-----------|------------------------------------------------------------------------------------|
| add       | Add a property or array element. For existing property: set value.                 |
| remove    | Remove a property or array element.                                                |
| replace   | Same as remove followed by add at same location.                                   |
| move      | Same as remove from source followed by add to destination using value from source. |
| copy      | Same as add to destination using value from source.                                |
| test      | Return success status code if value at path = provided value.                      |

For example, we could have the following `original.json` file:

```json
{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.AspNetCore": "Warning"
    }
  },
  "SmtpConfig": {}
}
```

We need to fill this `smtp` object with settings such as username, password, host, port, and more. To automate filling these values, we can use the ServiceStack `x` tool to apply a `json.patch`. The `json.patch` file to accomplish this would look something like:

```json
[
  {
    "op": "add",
    "path": "/SmtpConfig",
    "value": {
      "UserName": "AWS_ACCESS_KEY_ID",
      "Password": "AWS_SECRET_ACCESS_KEY",
      "Host": "email-smtp.us-east-1.amazonaws.com",
      "Port": 587,
      "FromName": "From Name",
      "FromEmail": "email@address.com",
      "Bcc": "bcc email address"
    }
  }
]
```

Once this patch is applied, our `appsettings.json` transforms into:

```json
{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.AspNetCore": "Warning"
    }
  },
  "SmtpConfig": {
    "UserName": "AWS_ACCESS_KEY_ID",
    "Password": "AWS_SECRET_ACCESS_KEY",
    "Host": "email-smtp.us-east-1.amazonaws.com",
    "Port": 587,
    "From": "email address",
    "FromName": "From Name",
    "Bcc": "bcc email address"
  }
}
```

You can apply this patch using the `x` tool's `patch` command:

```bash
x patch appsettings.json.patch
```

This expects both the `appsettings.json.patch` and `appsettings.json` files to be local. Optionally, you can specify both files if their names differ.

```bash
x patch changes.json.patch appsettings.json
```

### Lisp REPL

Lisp's dynamism and extensibility makes it particularly well suited for explanatory programming whose access via a REPL is available 
`x`, `web` and `app` dotnet tools.

The quick demo below shows the kind of exploratory programming available where you can query the `scriptMethods` available, 
query an objects `props`, query the Lisp interpreter's global `symbols` table containing all its global state including all 
defined lisp functions, macros and variables:

[![](/img/pages/sharpscript/web-lisp.gif)](https://youtu.be/RR7yk6ReNnQ)

::: info YouTube
[youtu.be/RR7yk6ReNnQ](https://youtu.be/RR7yk6ReNnQ)
:::

### Annotated REPL Walk through

Here's an annotated version of the demo below which explains what each of the different expressions is doing.

Just like [Sharp Scripts](https://sharpscript.net/docs/sharp-scripts) and [Sharp Apps](https://sharpscript.net/docs/sharp-apps) the Lisp REPL runs within the 
[#Script Pages](https://sharpscript.net/docs/script-pages) ScriptContext [sandbox](https://sharpscript.net/docs/sandbox) that when run from a Sharp App folder, 
starts a .NET Core App Server that simulates a fully configured .NET Core App. 
In this case it's running in the [redis Sharp App](https://github.com/sharp-apps/redis) directory where it was able to access its static web assets
as well as its redis-server connection configured in its [app.settings](https://github.com/sharp-apps/redis/blob/master/app.settings).

```lisp
; quick lisp test!
(+ 1 2 3)

; List of ScriptMethodInfo that the ScriptContext running this Lisp Interpreter has access to
scriptMethods

; first script method
(:0 scriptMethods)

; show public properties of ScriptMethodInfo 
(props (:0 scriptMethods))

; show 1 property per line
(joinln (props (:0 scriptMethods)))

; show both Property Type and Name
(joinln (propTypes (:0 scriptMethods)))

; view the Names of all avaialble script methods
(joinln (map .Name scriptMethods))

; view all script methods starting with 'a'
(globln "a*" (map .Name scriptMethods))

; view all script methods starting with 'env'
(globln "env*" (map .Name scriptMethods))

; print environment info about this machine seperated by spaces
(printlns envOSVersion envMachineName envFrameworkDescription envLogicalDrives)

; expand logical drives
(printlns envOSVersion envMachineName envFrameworkDescription "- drives:" (join envLogicalDrives " "))

; view all current global symbols defined in this Lisp interpreter
symbols

; view all symbols starting with 'c'
(globln "c*" symbols)

; see how many symbols are defined in this interpreter
(count symbols)

; see how many script methods there are available
(count scriptMethods)

; view the method signature for all script methods starting with 'all'
(globln "all*" (map .Signature scriptMethods))

; count all files accessible from the configured ScriptContext
(count allFiles)

; view the public properties of the first IVirtualFile
(props (:0 allFiles))

; display the VirtualPath of all available files
(joinln (map .VirtualPath allFiles))

; display the method signature for all script methods starting with 'findFiles'
(globln "findFiles*" (map .Signature scriptMethods))

; see how many .html files are available to this App
(count (findFiles "*.html"))

; see how many .js files are available to this App
(count (findFiles "*.js"))

; show the VirtualPath of all .html files
(joinln (map .VirtualPath (findFiles "*.html")))

; view the VirtualPath's of the 1st and 2nd .html files
(:0 (map .VirtualPath (findFiles "*.html")))
(:1 (map .VirtualPath (findFiles "*.html")))

; view the text file contents of the 1st and 2nd .html files
(fileTextContents (:0 (map .VirtualPath (findFiles "*.html"))))
(fileTextContents (:1 (map .VirtualPath (findFiles "*.html"))))

; display the method signatures of all script methods starting with 'redis'
(globln "redis*" (map .Signature scriptMethods))

; search for all Redis Keys starting with 'urn:' in the redis-server instances this App is configured with
(redisSearchKeys "urn:*")

; display the first redis search entry
(:0 (redisSearchKeys "urn:*"))

; display the key names of all redis keys starting with 'urn:'
(joinln (map :id (redisSearchKeys "urn:*")))

; find out the redis-server data type of the 'urn:tags' key
(redisCall "TYPE urn:tags")

; view all tags in the 'urn:tags' sorted set
(redisCall "ZRANGE urn:tags 0 -1")

; view the string contents of the 'urn:question:1' key
(redisCall "GET urn:question:1")

; parse the json contents of question 1 and display its tag names
(:Tags (parseJson (redisCall "GET urn:question:1")))

; extract the 2nd tag of question 1
(:1 (:Tags (parseJson (redisCall "GET urn:question:1"))))

; clear the Console screen
clear

; exit the Lisp REPL
quit
```

#### Enable features and access resources with app.settings

You can configure the Lisp REPL with any of the resources and features that [Sharp Apps](https://sharpscript.net/docs/sharp-apps) and 
[Gist Desktop Apps](https://sharpscript.net/docs/gist-desktop-apps) have access to, by creating a plain text `app.settings` file with all the 
features and resources you want the Lisp REPL to have access to, e.g. this [Pure Cloud App app.settings](https://sharpscript.net/docs/sharp-apps#pure-cloud-apps)
allows the Lisp REPL to use [Database Scripts](https://sharpscript.net/docs/db-scripts) against a AWS PostgreSQL RDS server and query remote 
[S3 Virtual Files](/virtual-file-system) using [Virtual File System APIs](https://sharpscript.net/docs/protected-scripts#virtual-file-system-apis):

```
# Note: values prefixed with '$' are resolved from Environment Variables
name AWS S3 PostgreSQL Web App
db postgres
db.connection $AWS_RDS_POSTGRES
files s3
files.config {AccessKey:$AWS_S3_ACCESS_KEY,SecretKey:$AWS_S3_SECRET_KEY,Region:us-east-1,Bucket:rockwind}
```

See the [plugins app.settings](https://sharpscript.net/docs/sharp-apps#registering-servicestack-plugins) for examples of how to load and configure 
[ServiceStack Plugins](/plugins).

::include web-trouble.md::


# Add ServiceStack Reference using npx get-dtos
Source: https://docs.servicestack.net/npx-get-dtos

To make it easier to consume ServiceStack APIs in any language, we've added the ability to download and upload Typed DTOs 
in all languages without needing .NET installed with the new `npx get-dtos` npm script.

It has the same syntax and functionality as the `x` dotnet tool for adding and updating ServiceStack References where
in most cases you can replace `x <lang>` with `npx get-dtos <lang>` to achieve the same result.

Running `npx get-dtos` without any arguments will display the available options:

    get-dtos <lang>                  Update all ServiceStack References in directory (recursive)
    get-dtos <file>                  Update existing ServiceStack Reference (e.g. dtos.cs)
    get-dtos <lang>     <url> <file> Add ServiceStack Reference and save to file name
    get-dtos csharp     <url>        Add C# ServiceStack Reference            (Alias 'cs')
    get-dtos typescript <url>        Add TypeScript ServiceStack Reference    (Alias 'ts')
    get-dtos javascript <url>        Add JavaScript ServiceStack Reference    (Alias 'js')
    get-dtos python     <url>        Add Python ServiceStack Reference        (Alias 'py')
    get-dtos dart       <url>        Add Dart ServiceStack Reference          (Alias 'da')
    get-dtos php        <url>        Add PHP ServiceStack Reference           (Alias 'ph')
    get-dtos java       <url>        Add Java ServiceStack Reference          (Alias 'ja')
    get-dtos kotlin     <url>        Add Kotlin ServiceStack Reference        (Alias 'kt')
    get-dtos swift      <url>        Add Swift ServiceStack Reference         (Alias 'sw')
    get-dtos fsharp     <url>        Add F# ServiceStack Reference            (Alias 'fs')
    get-dtos vbnet      <url>        Add VB.NET ServiceStack Reference        (Alias 'vb')
    get-dtos tsd        <url>        Add TypeScript Definition ServiceStack Reference    
    
    Options:
        -h, --help, ?             Print this message
        -v, --version             Print tool version version
            --include <tag>       Include all APIs in specified tag group
            --qs <key=value>      Add query string to Add ServiceStack Reference URL
            --verbose             Display verbose logging
            --ignore-ssl-errors   Ignore SSL Errors

### Reusable DTOs and Reusable Clients in any language

A benefit of [Add ServiceStack Reference](/add-servicestack-reference) is that only an 
API DTOs need to be generated which can then be used to call any remote instance running that API. E.g. DTOs generated
for our deployed AI Server instance at [openai.servicestack.net](https://openai.servicestack.net) can be used to call
any self-hosted AI Server instance, likewise the same generic client can also be used to call any other ServiceStack API.

### TypeScript Example

For example you can get the TypeScript DTOs for the just released [AI Server](/ai-server/) with:

:::sh
`npx get-dtos typescript https://openai.servicestack.net`
:::

Which just like the `x` tool will add the TypeScript DTOs to the `dtos.ts` file

And later update all TypeScript ServiceStack References in the current directory with:

:::sh
`npx get-dtos typescript`
:::

### Install and Run in a single command

This can be used as a more flexible alternative to the `x` tool where it's often easier to install node in CI environments
than a full .NET SDK and easier to use npx scripts than global dotnet tools. For example you can use the `--yes` flag
to implicitly install (if needed) and run the `get-dtos` script in a single command, e.g:

:::sh
`npx --yes get-dtos typescript`
:::

### C# Example

As such you may want want to replace the `x` dotnet tool with `npx get-dtos` in your C#/.NET projects as well which
can either use the language name or its more wrist-friendly shorter alias, e.g:

:::sh
`npx get-dtos cs https://openai.servicestack.net`
:::

Then later update all C# DTOs in the current directory (including sub directories) with:

:::sh
`npx get-dtos cs`
:::


# Create Projects with &#x27;x new&#x27;
Source: https://docs.servicestack.net/dotnet-new

All ServiceStack Projects can be created using the .NET Core [x dotnet tool](https://www.nuget.org/packages/x):

## Install

:::sh
dotnet tool install --global x 
:::

### Update

Or if you had a previous version installed, update with:

:::sh
dotnet tool update -g x
:::

All features from the cross-platform `x` dotnet tool are also available from the [.NET Core Windows Desktop app](/netcore-windows-desktop) tool:

:::sh
dotnet tool install --global app 
:::

#### Usage

To view a list of projects run:

:::sh
x new
:::

Where it will display all repositories in [.NET Core](https://github.com/NetCoreTemplates), 
[.NET Framework](https://github.com/NetFrameworkTemplates) and 
[ASP.NET Core Framework](https://github.com/NetFrameworkCoreTemplates) GitHub Orgs:

:::{class="not-prose table table-striped"}

::include web-new-netcore.md::

<p>&nbsp;</p>

::include web-new-corefx.md::

<p>&nbsp;</p>

::include web-new-netfx.md::

:::

#### Usage

```bash
$ x new `<template>` `<name>`
```

For example to create a new **Vue Single Page App**, run:

:::sh
x new vue-spa ProjectName
:::

Alternatively you can write new project files directly into an empty repository using the Directory Name as the ProjectName:

```bash
$ git clone https://github.com/<User>/<ProjectName>.git
$ cd <ProjectName>
$ x new vue-spa
```

Or download a customized project template from our Getting Started Page:

### [servicestack.net/start](https://servicestack.net/start)

## Modernized Project Templates

![](/img/pages/ssvs/spa-templates-overview.png)

The ASP.NET Core Project Templates have been upgraded to use the latest external dependencies and have all been rewritten to take advantage
of the ServiceStack Features added in this release, namely:

 - **[Modular Startup](/modular-startup)** - ASP.NET Core Apps can take advantage of the modularity benefits and extensibility of `mix` features
 - **[Navigation Items](/navigation)** - Simplified maintenance and dynamic navigation items rendering using Navigation controls
 - **Auth Enabled** - Integrated Auth including dynamic menu, protected pages, auth redirect flow inc. Forbidden pages
 - **[SVG](/svg)** - Pre-configured to use `svg/` folder, ready to drop in your App's assets and go
 - **[Optimal Library Bundles](/html-css-and-javascript-minification)** - CSS/JS bundles are split into optimal hashed library and frequently changing App bundles
 - **SSL** - As it's recommended for Web Apps to use SSL, all templates now use `https://localhost:5001` and 
 configured to use Same Site Cookies by default

### Auth Enabled Project Templates

Most Project Templates are now integrated with Credentials Auth and Facebook, Google and Facebook 3rd Party OAuth providers, complete with
protected Pages and Services and auth redirect flow to Sign In and Forbidden pages. 

### vue-spa

Vue CLI Bootstrap App

[![](/img/pages/auth/signin/vue-spa.png)](https://github.com/NetCoreTemplates/vue-spa)

.NET 6+
:::sh
x new vue-spa ProjectName
:::

.NET Framework
:::sh
x new vue-spa-netfx ProjectName
:::

### react-spa

React Create App CLI Bootstrap App

[![](/img/pages/auth/signin/react-spa.png)](https://github.com/NetCoreTemplates/react-spa)


.NET 6+
:::sh
x new react-spa ProjectName
:::

.NET Framework
:::sh
x new react-spa-netfx ProjectName
:::

### svelte-spa

Svelte SPA App with Bootstrap

[![](/img/pages/auth/signin/svelte-spa.png)](https://github.com/NetCoreTemplates/svelte-spa)

.NET 6+
:::sh
x new svelte-spa ProjectName
:::

### angular-spa

Angular 12 CLI Bootstrap App

[![](/img/pages/auth/signin/angular-spa.png)](https://github.com/NetCoreTemplates/angular-spa)

.NET 6+
:::sh
x new angular-spa ProjectName
:::

.NET Framework
:::sh
x new angular-spa-netfx ProjectName
:::

### mvcauth

.NET 6.0 MVC Website integrated with ServiceStack Auth

[![](/img/pages/auth/signin/mvcauth.png)](https://github.com/NetCoreTemplates/mvcauth)

.NET 6+
:::sh
x new mvcauth ProjectName
:::

### mvcidentityserver

.NET 6.0 MVC Website integrated with ServiceStack using IdentityServer4 Auth

[![](/img/pages/auth/signin/mvcidentityserver.png)](https://github.com/NetCoreTemplates/mvcidentityserver)

.NET 6+
:::sh
x new mvcidentityserver ProjectName
:::

### vue-nuxt

Nuxt.js SPA App with Bootstrap

[![](/img/pages/auth/signin/vue-nuxt.png)](https://github.com/NetCoreTemplates/vue-nuxt)

.NET 6+
:::sh
x new vue-nuxt ProjectName
:::

.NET Framework
:::sh
x new vue-nuxt-netfx ProjectName
:::

### script

`#Script` Pages Bootstrap Website

[![](/img/pages/auth/signin/script.png)](https://github.com/NetCoreTemplates/script)

.NET 6+
:::sh
x new script ProjectName
:::

ASP.NET Core on .NET Framework
:::sh
x new script-corefx ProjectName
:::

.NET Framework
:::sh
x new script-netfx ProjectName
:::

### razor

ServiceStack.Razor Bootstrap Website

[![](/img/pages/auth/signin/razor.png)](https://github.com/NetCoreTemplates/razor)

.NET 6+
:::sh
x new razor ProjectName
:::

ASP.NET Core on .NET Framework
:::sh
x new razor-corefx ProjectName
:::

.NET Framework
:::sh
x new razor-netfx ProjectName
:::

### Create Customized Projects with mix

All new projects can be further customized with [mix](/mix-tool) dotnet tool to mix in additional "layered" features.

## Creating new .NET 5 projects

If you're not yet ready to move to .NET 6 you can still create new projects of older versions of
the [.NET Core templates](https://github.com/NetCoreTemplates/).

Which can also be created from our online Project builder at: **servicestack.net/start?tag=net5**

Otherwise our .NET Core project templates have had their last .NET 5.0 version tagged with `net5` which can be installed with 
the `x` tool by using the full URL of its Source Code **.zip** archive in place of the Template name, e.g:

:::sh
`x new https://github.com/NetCoreTemplates/<template>/archive/refs/tags/net5.zip ProjectName`
:::

### Creating new projects of older Template versions

To install any other version, explore each released Project Template version by going to its GitHub Projects `/releases` page, e.g.
[/web/releases](https://github.com/NetCoreTemplates/web/releases) then clicking on the Release `<tag>` to explore its contents. 

Once you know which release you want to create a new project of, e.g. for the `web` template 
[/v27](https://github.com/NetCoreTemplates/web/tree/v27) was the last release to target **net5.0**.

Use its full URL of its Source Code **.zip** archive 
in place of the Template name, e.g:

:::sh
mkdir ProjectName && cd ProjectName 
:::

:::sh
x new https://github.com/NetCoreTemplates/web/archive/refs/tags/v27.zip
:::

Alternatively if it's easier you can download the Release Source Code archive manually:

**https://github.com/NetCoreTemplates/web/archive/refs/tags/v27.zip**

Then either rename the project and folder names manually or copy over the original source files you want into your existing solution.

### Using older mix features

All [mix features](/mix-tool) have been rewritten to use .NET 6's new `HostingStartup` model going forward,
to help with migration please refer to the [mix diff](https://github.com/ServiceStack/mix/commit/b56746622aa1879e3e6a8cbf835e634f05db30db) 
showing how each of the existing mix configurations were converted to the new model.

To support older projects the [Existing ModularStartup configuration](https://gist.github.com/gistlyn/7362ea802aef361bbdc21097b6a99e0d)
can still be used for when running on earlier .NET Core runtimes with the mix tool by changing the gist Id in the `MIX_SOURCE` 
Environment Variable, e.g:

:::sh
MIX_SOURCE=7362ea802aef361bbdc21097b6a99e0d x mix
:::

Which will chance to use the older mix Modular Startup configuration as its source.

## Why a new project template system?

It's not often that a tool causes enough friction that it ends up requiring less effort to develop a replacement than 
it is to continue using the tool. But this has been our experience with maintaining our VS.NET Templates in the 
[ServiceStackVS](https://github.com/ServiceStack/ServiceStackVS) VS.NET Extension which has been the biggest time sink of all our
3rd Party Integrations where the iteration time to check in a change, wait for CI build, uninstall/re-install the VS.NET extension 
and create and test new projects is measured in hours not minutes. To top off the poor development experience we've now appeared to have 
reached the limits of the number of Project Templates we can bundle in our 5MB **ServiceStackVS.vsix** VS.NET Extension as a 
number of Customers have reported seeing VS.NET warning messages that ServiceStackVS is taking too long to load.

Given all the scenarios ServiceStack can be used in, we needed a quicker way to create, update and test our growing **47 starting project templates**. 
In the age of simple command-line dev tools like git and .NET Core's light weight text/human friendly projects, maintaining and creating 
new .NET project templates still feels archaic & legacy requiring packaging projects as binary blobs in NuGet packages which become stale 
the moment they're created.

## How it works

### GitHub powered Project Templates

Especially for SPA projects which need to be frequently updated, the existing .NET Project Templates system is a stale solution that doesn't offer 
much benefit over maintaining individual GitHub projects, which is exactly what the `dotnet-new` npm tool and now `x new` .NET Core are designed around.

Inside [dotnet-new](/dotnet-new) and `x new` is an easier way to create and share any kind of project templates which are easier for developers
to create, test, maintain and install. So if you're looking for a simpler way to be able to create and maintain your own value-added project templates 
with additional bespoke customizations, functionality, dependencies and configuration, using `x new` is a great way to maintain and share them.

Using GitHub for maintaining project templates yields us a lot of natural benefits:

 - Uses the same familiar development workflow to create and update Project Templates
 - Git commit history provides a public audit trail of changes
 - Publish new versions of project templates by creating a new GitHub release
 - Compare changes between Project Templates using GitHub's compare changes viewer
 - Browse and Restore Previous Project Releases
 - End users can raise issues with individual project templates and send PR contributions

A quick way to get started is to fork one of the existing [.NET Project Templates](https://github.com/NetCoreTemplates/) like the [web](https://github.com/NetCoreTemplates/web) or [empty](https://github.com/NetCoreTemplates/empty) templates.

### Always up to date

Importantly end users will always be able to view the latest list of project templates and create projects using the latest available version, 
even if using older versions of the tools as they query GitHub's public APIs to list all currently available projects that for installation
will use the latest published release (or **master** if there are no published releases), which if available, downloads, caches and 
creates new projects from the latest published `.zip` release.

### Just regular Projects

Best of all creating and testing projects are now much easier since project templates are just working projects following a simple naming convention
that when a new project is created with:

```bash
$ x new <template> ProjectName
```

### Install directly from your GitHub repo

To create projects from your own GitHub projects use its qualified `user/repo` name, e.g:

```bash
$ x new <user>/<repo> ProjectName
```

Replaces all occurrences in all text files, file and directory names, where:

 - `My_App` is replaced with `Project_Name`
 - `MyApp` is replaced with `ProjectName`
 - `My App` is replaced with `Project Name`
 - `my-app` is replaced with `project-name`
 - `myapp` is replaced with `projectname`
 - `my_app` is replaced with `project_name`

The tool installer then inspects the project contents and depending on what it finds will:

 - Restore the .NET `.sln` if it exists
 - Install npm packages if `package.json` exists
 - Install libman packages if `libman.json` exists

That after installation is complete, results in newly created projects being all setup and ready to run.

### Available project templates

One missing detail is how it finds which GitHub repo should be installed from the `<template>` name. 

This can be configured with the `APP_SOURCE_TEMPLATES` Environment variable to configure the `x` tool to use your own GitHub organizations instead, e.g:

```
APP_SOURCE_TEMPLATES=NetCoreTemplates;NetFrameworkTemplates;NetFrameworkCoreTemplates
```

Optionally you can display a friendly name next to each Organization name, e.g:

```
APP_SOURCE_TEMPLATES=NetCoreTemplates .NET Core C# Templates;
```

`x new` will then use the first GitHub Repo that matches the `<template>` name from all your GitHub Sources, so this
does require that all repos have unique names across all your configured GitHub Sources.

These are the only sources `x new` looks at to create ServiceStack projects, which by default is configured to use 
[NetCoreTemplates](https://github.com/NetCoreTemplates), [NetFrameworkTemplates](https://github.com/NetFrameworkTemplates) and 
[NetFrameworkCoreTemplates](https://github.com/NetFrameworkCoreTemplates) GitHub Organizations, whose repos will be listed when running:

:::sh
x new
:::

### Creating new Legacy Project Templates

By Setting `APP_SOURCE_TEMPLATES` environment variable to [LegacyTemplates](https://github.com/LegacyTemplates) you can can use the `x` tool 
to browse and create new legacy project templates, e.g:

:::sh
APP_SOURCE_TEMPLATES=LegacyTemplates x new
:::

::include web-trouble.md::


# .NET Core Windows Desktop Apps
Source: https://docs.servicestack.net/netcore-windows-desktop

![](/img/pages/app/netcore-chromium-splash.png)

The [app](https://www.nuget.org/packages/app) dotnet build tool contains features for "Chromitizing" any 
.NET Core Web App into a **.NET Core Windows Desktop App** by just installing the `app` dotnet tool:

:::sh
dotnet tool install -g app
:::

If you already have `app` tool installed make sure you're running the latest version with:

:::sh
dotnet tool update -g app
:::

### Launch .NET Core App inside a Windows Chromium Desktop App

Then run your .NET Core Web App with:

:::sh
app MyApp.dll
:::

Where it will run your .NET Core App and host it inside an Chromium Embedded Framework (CEF) browser.

This provides instant utility for being able to deploy .NET Core Apps end users can run locally using Chrome's leading and consistent rendering engine
within a Windows Desktop Application.

`app` includes a number of features and deep integration with GitHub that makes running .NET Core Chromium Desktop Apps a seamless experience. 

To illustrate this we can install any .NET Core project from GitHub by specifying the project's name along with the name of 
the GitHub **User** or **Organization** via the `--source` argument. If you don't have a .NET Core Application on-hand to try it on, you can use
any of [ServiceStack's .NET Core Templates](https://github.com/NetCoreTemplates) which are all functioning .NET Core projects in their own right. 

Where we can create a new [NetCoreTemplates/mvc](https://github.com/NetCoreTemplates/mvc) project with:

:::sh
app new mvc Acme --source NetCoreTemplates
:::

Which will download and unzip either the Project's **latest release**, or an archive of **master** if none exists. 

Then publish the .NET Core App as normal by going into the Host project folder using the **project name** you specified above, eg:

:::sh
cd Acme\Acme
:::
    
Create a published version of the App:

:::sh
dotnet publish -c Release
:::

Then in the `/publish` folder:

:::sh
cd bin\Release\net6.0\publish
:::

You can use `app` to run the .NET Core binary:

:::sh
app Acme.dll
:::

Where it will run the .NET Core App and launch it within a CEF Windows Application:

[![](/img/pages/app/screenshot-mvc.png)](http://mvc.web-templates.io/)

### Create Windows Desktop Shortcuts

To make the experience of running .NET Core Desktop Apps even nicer you can use the `shortcut` command to create a Windows Shortcut for your App:

:::sh
app shortcut Acme.dll
:::

Which you can either double-click to run or copy to a more accessible location like the Users Desktop:

![](/img/pages/app/app-shortcut.png)

If you wanted to use your own icon instead, copy it as `favicon.ico` in your `/publish` folder and rerun the command:

:::sh
app shortcut Acme.dll
:::

Where it will be used in both Shortcut Icon and Windows Desktop icon:

![](/img/pages/app/app-shortcut-icon.png)

### Create new Project Templates

See [x new](/web-new) for available Project Templates you can create with:

:::sh
app new
:::

### Mix Features into existing ASP.NET Core Apps

The `app` dotnet tool is a [versatile utility belt packed with a number of features](/dotnet-tool) to simplify discovering, installing, running and deploying 
.NET Core Apps. You can view the full list of supported commands by running `app ?`, e.g. another useful command is using [`app mix`](/mix-tool)
for generating pre-set templates:

```
app mix                     Show available gists to mixin         (Alias '+')
app mix <name>              Write gist files locally, e.g:        (Alias +init)
app mix init                Create empty .NET Core ServiceStack App
app mix [tag]               Search available gists
app gist <gist-id>          Write all Gist text files to current directory
```

View available gists with:

:::sh
app mix
:::

Where you can use `app mix nginx` to generate a common nginx template configuration for reverse proxying .NET Core Apps, making configuring 
[Linux deployment servers for your .NET Core Apps](/netcore-deploy-rsync) less tedious. 

In addition to the pre-set templates, you can create your own [public GitHub gist](https://gist.github.com) with any number of different files customized 
for your Environment that anyone can write to their current directory with **the gist id** or **gist URL**:

:::sh
`app gist <gist-id>`
:::

### Installing Sharp Apps

The app tool also makes it easy to install .NET Core [Sharp Apps](https://sharpscript.net/docs/sharp-apps) where you can `open` apps that are available 
to **open** or **install** with:

:::sh
app open
:::

By default this will list all [Gist Desktop Apps](https://sharpscript.net/docs/gist-desktop-apps) and 
[GitHub Sharp Apps](https://sharpscript.net/docs/gist-desktop-apps#github-sharp-apps) and available:

```
   1. redis       Simple, lightweight, versatile Redis Admin UI                                 by @ServiceStack  [redis]
   2. spirals     Explore and generate different Spirals with SVG                               by @ServiceStack  [svg]
   3. blog        Minimal, multi-user Twitter Auth blogging app                                 by @ServiceStack  [sqlite]
   4. rockwind    Example combining Rockstars website + data-driven Northwind Browser           by @ServiceStack  [example]
   5. redis-html  Redis Admin Viewer developed as server-generated HTML Website                 by @sharp-apps    [redis]
   6. plugins     Extend Apps with Plugins, ServiceStack Services and other C# extensions       by @sharp-apps    [example]
   7. chat        Extensible App with custom AppHost leveraging OAuth + SSE for real-time Chat  by @sharp-apps    [example]
   8. bare        Basic Sharp Content Website                                                   by @ServiceStack  [website]

Usage: app open <name>
```

## Custom .NET Core Desktop Apps

When running the .NET Core `MyApp.dll`, it effectively runs an external `dotnet MyApp.dll` process, pipes the output to the console and launches 
a CEF browser with the url in `ASPNETCORE_URLS`. 

The [ServiceStack.CefGlue.Win64.AspNetCore](https://github.com/ServiceStack/ServiceStack.CefGlue/tree/master/tests/ServiceStack.CefGlue.Win64.AspNetCore) 
project shows how to launch both the .NET Core App and a customized CEF browser in the same process by referencing the 
[ServiceStack.CefGlue.Win64](https://www.nuget.org/packages/ServiceStack.CefGlue.Win64) NuGet package in your **win-x64** .NET Core project:

```xml
<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <OutputType>WinExe</OutputType>
    <TargetFramework>netcoreapp3.1</TargetFramework>
    <RuntimeIdentifiers>win-x64</RuntimeIdentifiers>
    <Platforms>x64</Platforms>
    <ApplicationIcon>favicon.ico</ApplicationIcon>
    <AssemblyName>webapp</AssemblyName>
    <TrimUnusedDependencies>true</TrimUnusedDependencies>
    <TargetLatestRuntimePatch>true</TargetLatestRuntimePatch>
    <RuntimeFrameworkVersion>2.1.2</RuntimeFrameworkVersion>
    <CopyLocalLockFileAssemblies>true</CopyLocalLockFileAssemblies>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Microsoft.AspNetCore.Server.Kestrel" Version="2.*" />

    <PackageReference Include="ServiceStack.CefGlue.Win64" Version="8.*" />
  </ItemGroup>

</Project>
```

Then in your .NET Core App after calling `StartAsync()` to run your .NET Core App:

```csharp
class Program
{
    static int Main(string[] args)
    {
        var startUrl = Environment.GetEnvironmentVariable("ASPNETCORE_URLS") ?? "http://localhost:5000/";

        var host = new WebHostBuilder()
            .UseKestrel()
            .UseContentRoot(Directory.GetCurrentDirectory())
            .UseStartup<Startup>()
            .UseUrls(startUrl)
            .Build();

        host.StartAsync();
        
        var config = new CefConfig(debug:true)
        {
            Args = args,
            StartUrl = startUrl,
            HideConsoleWindow = false,
        };
        
        return CefPlatformWindows.Start(config);
    }
}
```

Call `CefPlatformWindows.Start(config)` to launch the CEF browser with your preferred customizations in a Windows 64bit OS.

[CefConfig.cs](https://github.com/ServiceStack/ServiceStack.CefGlue/blob/master/src/ServiceStack.CefGlue/CefConfig.cs) supports high-level configuration
where you can change the Window size and position, icon, title as well as the `CefSettings` and `CefBrowserSettings` the browser is launched with 
and whether to enable or disable the `ALT+LEFT/RIGHT` Navigation Keys, `F5` Refresh or `F11` Chrome Dev Tools. 

> Eventually we intend to provide different packages using the same high-level `CefConfig` settings to simplify the effort required to run 
.NET Core Desktop Apps on different Operating Systems.

### Upgrading

A nice benefit from delivering `app` as a dotnet tool is that updates are effortless as running:

:::sh
dotnet tool update -g app
:::

Which will upgrade to a newer CEF and `app` versions as they're released. `app` also lets you know if there's a newer version available
after running the `list`, `gallery` and `-v` commands.

## Chromium Desktop Apps

Chrome Desktop Apps are 
[increasingly becoming the preferred approach](https://www.theverge.com/circuitbreaker/2018/5/16/17361696/chrome-os-electron-desktop-applications-apple-microsoft-google) 
for developing Desktop Apps today, they benefit from the vast amount of resources Google invests in developing their most important 
Desktop Application in Chrome and its [Chromium](https://www.chromium.org) project which provides the Chrome rendering engine in popular 
frameworks like [CEF](https://bitbucket.org/chromiumembedded/cef) and [Electron](https://electronjs.org) that's used to power many of the actively developed Desktop Apps today like VS Code, GitHub Desktop, Twitch.tv, WhatsApp, Slack, Skype, Discord, Signal, Microsoft Teams, 
Microsoft SQL Operations Studio and [hundreds more](https://electronjs.org/apps). Whilst CEF is used to render Web content in popular native Desktop Apps like Spotify, Stream, Facebook Messenger, Adobe Acrobat, Adobe Creative Cloud, Amazon Music, Battle.net, Evernote as well as game engines like 
Unity3D and Unreal Engine.

Ultimately what "Web Desktop Apps" provide most is value, with easy access to advanced Web technologies, rich layout and design techniques, live debugging inspector, navigation, deep-linking and offer [significantly greater ROI](https://dev.to/bitario/in-defense-of-electron) when needing to support multiple Operating Systems or an online hosted version of your Software. Even without the code-reuse of targeting multiple platforms they offer a leap in productivity for many classes of Apps, e.g. the depth and velocity of [VS Code's frequent releases](https://code.visualstudio.com/updates/v1_27) are rarely seen in Native Desktop Apps. 

Of course if you can offer software hosted on the Internet that would typically be the preferred approach for increased accessibility, maintainability 
and reach to your Software. But there's a number of use-cases that would benefit from a Desktop App, e.g. any offline tasks, management of personal data, 
access to Native Desktop features, local computing and infrastructure resources or to avoid maintenance and management of a central hosted server. 

Places where you're using Windows Services could be better served as a unified Packaged Desktop App where you can ensure consistent behavior
by using the same tested Chrome rendering engine to run your App, mitigating any environment, versions and cross-browser issues.

## Desktop Sharp Apps

Whilst `app` is useful for running any Windows .NET Core Desktop App, it provides the greatest value for running .NET Core 
[Sharp Apps](https://sharpscript.net/docs/sharp-apps) - a revolutionary new simplified development model for developing .NET Core Apps 
which eliminates much of the friction .NET developers have historically had to face. [Sharp Apps](https://sharpscript.net/docs/sharp-apps) 
are built with [#Script](https://sharpscript.net) and require no builds/compilation, wait times, complicated build tooling, configuration, 
incompatible dependencies, dev tools or IDE's. 

The simplicity of being able to use the same executable for running all [Sharp Apps](https://sharpscript.net/docs/sharp-apps) allows us more 
flexibility to provide even greater value-added functionality than what's otherwise possible. By contrast Sharp Apps can be developed with any 
text editor in an iterative, live-development environment that updates itself on save, whilst the App is running. It utilizes a familiar 
[JavaScript and Handlebars syntax](https://sharpscript.net/docs/syntax) in a high-level dynamic language that late-binds to .NET APIs using 
Compiled Expressions for avoiding runtime reflection.

**Sharp Apps** are highly customizable by nature as they're delivered and run in source code form, requires no external dependencies or dev tools as they 
can be edited by any text editor whilst the app is running. They're also significantly smaller than normal Web Apps since the `app` tool already 
contains the shared binaries that all Sharp Apps use - making them easier to deploy, install and update.

### Installing Sharp Apps

As [sharp-apps](https://github.com/sharp-apps) is the default `APP_SOURCE`, running:

:::sh
app list
:::

Will return the list of publicly available Sharp Apps:

```
   1. bare            Basic Bootstrap + jQuery multi-page Content Website with dynamic Menu Navigation + API pages
   2. blog            Minimal, multi-user Twitter OAuth blogging platform that can create living, powerful pages
   3. chat            Highly extensible App with custom AppHost leveraging OAuth + SSE for real-time Chat
   4. plugins         Extend WebApps with Plugins, Filters, ServiceStack Services and other C# extensions
   5. redis           Redis Admin Viewer developed as Vue Client Single Page App
   6. redis-html      Redis Admin Viewer developed as server-generated HTML Website
   7. rockwind        Example Sharp App combining multi-layout Rockstars website + data-driven Northwind Browser
   8. rockwind-aws    Rockwind Cloud Sharp App on AWS
   9. rockwind-azure  Rockwind Cloud Sharp App on Azure
  10. spirals         Explore and generate different Spirals with SVG

Usage: app install <name>
```

### Include your Sharp App in the Gallery

We've also made it easy to list your App in the App gallery, by running:

:::sh
app gallery
:::

Which opens the [Sharp App Gallery Gist](https://gist.github.com/gistlyn/f555677c98fb235dccadcf6d87b9d098) where you can request for your Web App
to be listed in the gallery by commenting on the gist with a link to your project. We'll review it and if it's acceptable we'll fork it in 
[sharp-apps](https://github.com/sharp-apps) which creates a "link" to your project where it will be automatically listed. 

All existing `app` installs will be immediately able to install your App, which either installs the latest published release or from **master** if it 
hasn't published any releases.

### Installing blog

Installing an App is then just selecting the **name** of the app to install:

:::sh
app install blog
:::

Where it will download the latest `.zip` release (**36kb**) and extracts it into a folder named after the project:

```
Installing blog...

Installation successful, run with:

cd blog && app

Shortcut: blog\Blog Web App
```

Which can either be run on the command-line with:

:::sh
cd blog && app
:::

Or by double-clicking the **Blog Web App** Desktop shortcut.

Running the **blog** App for the first time will create a new `blog.sqlite` database seeded with meta content describing itself:

[![](/img/pages/app/blog-screenshot.png)](http://blog.web-app.io)

Despite it's small `36kb` size it [packs a punch](http://blog.web-app.io/#blog-app-features): 

 - Multi User Blogging Platform - Authenticated with Twitter
 - Rich Dynamic Content - Each post can contain the same [powerful language](https://sharpscript.net) used to build the app
 - Rich Markdown Editor
 - Auto saved drafts
 - Live Previews - showing rendered content as you type
 - Database dump of SQLite tables

At the bottom of each individual post shows the content used to create it, e.g. the [Live Document Example](http://blog.web-app.io/posts/live-document-example) shows an example of maintaining a live budget with a dynamic list of projected savings.

### Installing redis

From SQLite powered blog, lets install something entirely different - a Redis Admin UI!

:::sh
app install redis
:::

The `redis` app includes some additional customizations which controls how the App looks and behaves when run as a Desktop App in its 
[app.settings](https://github.com/sharp-apps/redis/blob/master/app.settings):

```
debug true
name Redis Web App
redis.connection localhost:6379
icon assets/img/redis.ico
CefConfig { Width:1200, Height:1200 }
```

Where `icon` is used to point to the App Icon and `CefConfig` is used to configure the CEF browser, allowing any 
[CefConfig.cs](https://github.com/ServiceStack/ServiceStack.CefGlue/blob/master/src/ServiceStack.CefGlue/CefConfig.cs) 
to be configured using a JavaScript object literal. On install the specified icon and name is used to create the Desktop shortcut:

![](/img/pages/app/redis-install.png)

Where it will open a [Redis Admin UI](http://redis.web-app.io) connected to your `localhost:6379` redis instance:

[![](/img/pages/app/redis-screenshot.png)](http://redis.web-app.io)

#### Customizing CEF Browser

Likewise we can also configure any nested `CefConfig.CefSettings` using an object literal. We can use this to view verbose logging messages by
telling `app` not to hide the Console Window and changing CEF's LogSeverity to Verbose:

```
CefConfig { Width:1200, Height:1200, HideConsoleWindow:false }
CefConfig.CefSettings { LogSeverity:'Verbose' }
```

Now when running the App we can see the CEF's verbose logging messages mixed in with request logs from .NET Core:

![](/img/pages/app/app-cef-verbose.png)

Which in this case shows messages written to Chrome's `console.log()` which is from Vue.js telling us we're running a development build of Vue.js. 
To run the production version of our app we can either set `debug false` in the `app.settings` or by running `app --release` which takes precedence:

:::sh
app -r
:::

This flag changes whether to use `vue.js` or `vue.min.js` in the [_layout.html](https://github.com/sharp-apps/redis/blob/master/_layout.html) page:

::: v-pre
```html
<script src="../assets/js/vue{{ '.min' | if(!debug) }}.js"></script>
```
:::

> To instead force running the App in debug mode use `app --debug` or `app -d`

#### Compact and easy to Customize

The `redis` App has all the features you'd expect from a Redis Admin UI:

  - Change connection to any Redis instance / database
  - Live Search of Redis Keyspace (updated as you type)
  - Management of all Redis's core String, List, Set, Sorted Set and Hash Key types
  - Execute any arbitrary Redis command
  - Display blobbed JSON value data in human-friendly UI
  - Redis Server Info List
  - Breadcrumbs
  - Deep Linking + Browser Navigation (ALT+LEFT Back, ALT+RIGHT Forward, F5 Refresh)

What differs this from other Redis Admin UI's is its terse implementation where its entire custom UI is contained within a single [index.html](https://github.com/sharp-apps/redis/blob/master/index.html) page thanks to the expressiveness of both Vue and `#Script`.

Its minimal size makes it easy for curious and advanced Users to customize and add features since they can make them locally and see their changes 
in real-time. Its simpler implementation makes contributions easier as they only have 1 page to edit and can paste their changes directly using 
[GitHub's Edit UI](https://github.com/sharp-apps/redis/edit/master/index.html) to easily create a pull-request where it can be reviewed and merged.

### Simple Updates

Thanks to the easy distribution all users can update to the latest version of any installed App by re-running:

:::sh
app install redis
:::
 
Which will replace their existing version with the latest release. 

## Creating Desktop Sharp Apps

Now that we've seen how easy it is to Install and use existing [Sharp Apps](https://sharpscript.net/docs/sharp-apps), 
lets walk through how easy it to create one of our own.

<lite-youtube class="w-full mx-4 my-4" width="560" height="315" videoid="Cf-vstYXrmY" style="background-image: url('https://img.youtube.com/vi/Cf-vstYXrmY/maxresdefault.jpg')"></lite-youtube>

For this example we'll create a small App that leverages one of the advanced Web technologies in SVG that would be cumbersome to create using a native GUI toolkit. To start let's create a folder for our app called `spirals` and initialize and empty Sharp App with `app init`:

:::sh
mkdir spirals
:::

:::sh
cd spirals && app init
:::

We could have started from one of the [more complete Sharp App Templates](https://sharpscript.net/docs/sharp-apps#getting-started) but this gives
us a minimal App generated from [this gist](https://gist.github.com/gistlyn/5c9ee9031e53cd8f85bd0e14881ddaa8).

Now let's open the folder up for editing in our preferred text editor, VS Code:

:::sh
code .
:::

![](/img/pages/app/app-init-code.png)

To start developing our App we just have to run `app` on the command-line which in VS Code we can open with `Terminal > New Terminal` or the **Ctrl+Shift+`** shortcut key. This will open our minimal App:

![](/img/pages/app/app-init-run.png)

The [_layout.html](https://gist.github.com/gistlyn/5c9ee9031e53cd8f85bd0e14881ddaa8#file-_layout-html) shown above is currently where all 
the action is which we'll quickly walk through:

::: v-pre
```html
<i hidden>{{ '/js/hot-fileloader.js' | ifDebugIncludeScript }}</i>
```
:::

This gives us a Live Development experience in `debug` mode where it injects a script that will detect file changes **on Save** and automatically reload the page at the current scroll offset.

::: v-pre
```html
{{ 'menu' | partial({ 
        '/':           'Home',
        '/metadata':   '/metadata',
    }) 
}}
```
:::

This evaluates the included [_menu-partial.html](https://gist.github.com/gistlyn/5c9ee9031e53cd8f85bd0e14881ddaa8#file-_menu-partial-html) with the links
to different routes we want in our Menu on top of the page.

::: v-pre
```html
<div id="body" class="container">
    <h2>{{title}}</h2>
    
    {{ page }}
</div>
```
:::

The body of our App is used to render the title and contents of each page.

::: v-pre
```html
{{ scripts | raw }}
```
:::

If pages include any `scripts` they'll be rendered in the bottom of the page.

> The `raw` filter prevents the output from being HTML encoded.

The other 2 files included is [app.settings](https://gist.github.com/gistlyn/5c9ee9031e53cd8f85bd0e14881ddaa8#file-app-settings) containing the 
name of our App and `debug true` setting to run our App in Debug mode:

```
debug true
name My App
```

The template only has one page [index.html](https://gist.github.com/gistlyn/5c9ee9031e53cd8f85bd0e14881ddaa8#file-index-html) containing the `title` 
of the page in a page argument which the `_layout.html` has access to without evaluating the page, anything after is the page contents:

```html
<!-- 
title: Home Page
-->

This is the home page.
```

We can now **save** changes to any of the pages and see our changes reflected instantly in the running App. But we also have access to an even better 
live-development experience than **preview as you save** with **preview as you type** :)

### Live Previews

To take advantage of this we can exploit one of the features available in all ServiceStack Apps by clicking on `/metadata` Menu Item to view the 
[Metadata page](/metadata-page) containing links to our Apps Services, links to Metadata Services and any registered plugins:

![](/img/pages/app/app-init-metadata.png)

Then click on [Debug Inspector](/debugging#debug-inspector) to open a real-time REPL, which is normally used to get rich insights from a running App:

![](/img/pages/app/app-init-debug-inspector.png)

But can also be used for executing ad hoc Template Scripts. Here we can drop in any mix of HTML and templates to view results in real-time. 

In this case we want to generate SVG spirals by drawing a `circle` at each point along a 
[Archimedean spiral function](https://stackoverflow.com/a/6824451/85785) which was initially used as a base and with the help of the live REPL was 
quickly able to apply some constants to draw the **tall & narrow** spirals we want:

::: v-pre
```hbs
<svg height="640" width="240">
{{#each range(180) }}
  {{ 120 + 100 * cos((1) * it * 0.02827) | assignTo: x }}
  {{ 320 + 300 * sin((1) * it * 0.02827) | assignTo: y }}
  <circle cx="{{x}}" cy="{{y}}" r="10" fill="rgb(0,100,0)" stroke="black" stroke-width="1"/>
{{/each}} 
</svg>
```
:::

We can further explore different spirals by modifying `x` and `y` cos/sin constants:

![](/img/pages/app/spirals/single.gif)

Out of the spirals we've seen lets pick one of the interesting ones and add it to our `index.html`, let's also enhance them by modifying the `fill` and
`radius` properties with different weightings and compare them side-by-side:

::: v-pre
```hbs
<svg height="640" width="240">
{{#each range(180) }}
  {{ 120 + 100 * cos((5) * it * 0.02827) | assignTo: x }}
  {{ 320 + 300 * sin((1) * it * 0.02827) | assignTo: y }}
  <circle cx="{{x}}" cy="{{y}}" r="10" fill="rgb(0,100,0)" stroke="black" stroke-width="1"/>
{{/each}} 
</svg>

<svg height="640" width="240">
{{#each range(180) }}
  {{ 120 + 100 * cos((5) * it * 0.02827) | assignTo: x }}
  {{ 320 + 300 * sin((1) * it * 0.02827) | assignTo: y }}
  <circle cx="{{x}}" cy="{{y}}" r="10" fill="rgb(0,{{it*1.4}},0)" stroke="black" stroke-width="1"/>
{{/each}} 
</svg>

<svg height="640" width="240">
{{#each range(180) }}
  {{ 120 + 100 * cos((5) * it * 0.02827) | assignTo: x }}
  {{ 320 + 300 * sin((1) * it * 0.02827) | assignTo: y }}
  <circle cx="{{x}}" cy="{{y}}" r="{{it*0.1}}" fill="rgb(0,{{it*1.4}},0)" stroke="black" stroke-width="1"/>
{{/each}} 
</svg>
```
:::

> You can use `ALT+LEFT` + `ALT+RIGHT` shortcut keys to navigate back and forward to the home page.

Great, hitting `save` again will show us the effects of each change side-by-size:

[![](/img/pages/app/spirals/single-fill-radius.png)](http://spirals.web-app.io)

### Multiplying

Now that we have the effect that we want, let's go back to the debug inspector and see what a number of different spirals look side-by-side
by wrapping our last svg snippet in another each block:

::: v-pre
```hbs
<table>{{#each i in range(0, 4) }}
<svg height="640" width="240">
{{#each range(180) }}
  {{ 120 + 100 * cos((1)   * it * 0.02827) | assignTo: x }}
  {{ 320 + 300 * sin((1+i) * it * 0.02827) | assignTo: y }}
  <circle cx="{{x}}" cy="{{y}}" r="{{it*0.1}}" fill="rgb(0,{{it*1.4}},0)" stroke="black" stroke-width="1"/>
{{/each}} 
</svg>
{{/each}}
```
:::

We can prefix our snippet with `<table>` as a temp workaround to force them to display side-by-side in Debug Inspector. In order to 
for spirals to distort we'll only change 1 of the axis, as they're tall & narrow lets explore along the y-axis:

![](/img/pages/app/spirals/multi-01.png)

We're all setup to begin our pattern explorer expedition where we can navigate across the `range()` index both incrementally and logarithmically across
to quickly discover new aesthetically pleasing patterns :)

![](/img/pages/app/spirals/multi.gif)

Let's go back to our App and embody our multi spiral viewer in a new `multi.html` page containing:

::: v-pre
```hbs
{{#each i in range(0, 4) }}
<svg height="640" width="240">
{{#each range(180) }}
  {{ 120 + 100 * cos((5)   * it * 0.02827) | assignTo: x }}
  {{ 320 + 300 * sin((1+i) * it * 0.02827) | assignTo: y }}
  <circle cx="{{x}}" cy="{{y}}" r="{{it*0.1}}" fill="rgb(0,{{it*1.4}},0)" stroke="black" stroke-width="1"/>
{{/each}} 
</svg>
{{/each}}
```
:::


Then make it navigable by adding a link to our new page in the `_layout.html` menu:

::: v-pre
```hbs
{{ 'menu' | partial({
     '/':           'Home',
     '/multi':      'Multi',
     '/metadata':   '/metadata',
   })
}}
```
:::

Where upon save, our creation will reveal itself in the App's menu:

[![](/img/pages/app/spirals/multi.png)](http://spirals.web-app.io/multi)

### Animating

With the help of SVG's [`<animate>`](https://developer.mozilla.org/en-US/docs/Web/SVG/Element/animate) we can easily bring our spirals to life
by animating different properties on the generated SVG circles.

As we have to wait for the animation to complete before trying out different effects, we won't benefit from Debug Inspector's live REPL
so let's jump straight in and create a new `animated.html` and add a link to it in the menu:

::: v-pre
```hbs
{{ 'menu' | partial({
     '/':           'Home',
     '/multi':      'Multi',
     '/animated':   'Animated',
     '/metadata':   '/metadata',
   })
}}
```
:::

Then populate it with a copy of `multi.html` and sprinkle in some `<animate>` elements to cycle through different `<circle>` property values. 
We're entering the "creative process" of our App where we can try out different values, hit **Save** and watch the effects of our tuning eventually 
arriving at a combination we like:

::: v-pre
```hbs
{{#each i in range(0, 4) }}
<svg height="640" width="240">
{{#each range(180) }}
  {{ 120 + 100 * cos((5)   * it * 0.02827) | assignTo: x }}
  {{ 320 + 300 * sin((1+i) * it * 0.02827) | assignTo: y }}
  <circle cx="{{x}}" cy="{{y}}" r="{{it*0.1}}" fill="rgb(0,{{it*1.4}},0)" stroke="black" stroke-width="1">
    <animate attributeName="fill" values="green;yellow;red;green" dur="{{it%10}}s" repeatCount="indefinite" />
    <animate attributeName="opacity" values="1;.5;1" dur="5s" repeatCount="indefinite" />
    <animate attributeName="cx" values="{{x}};{{x*1.02}};{{x*0.98}};{{x}}" dur="3s" repeatCount="indefinite" />
    <animate attributeName="cy" values="{{y}};{{y*1.02}};{{y*0.98}};{{y}}" dur="3s" repeatCount="indefinite" />
  </circle>
{{/each}} 
</svg>
{{/each}}
```
:::

Although hard to capture in a screenshot, we can sit back and watch our living, breathing Spirals :)

[![](/img/pages/app/spirals/animated.png)](http://spirals.web-app.io/animated?from=0)

> Checkout [spirals.web-app.io](http://spirals.web-app.io/animated?from=0) for the animated version.

### Navigating

Lets expand our App beyond these static Spirals by enabling some navigation, this is easily done by adding the snippet below on the top of the home page:

::: v-pre
```hbs
{{ from ?? 1 | toInt | assignTo: from }}
<div style="text-align:right;margin:-54px 0 30px 0">
  {{#if from > 1}} <a href="?from={{ max(from-1,0) }}" title="{{max(from-1,0)}}">previous</a> |{{/if}}
  {{from}} | <a href="?from={{ from+1 }}" title="{{max(from-1,0)}}">next</a>
</div>
```
:::

Whilst the `multi.html` and `animated.html` pages can skip by 4:

::: v-pre
```hbs
{{ from ?? 1 | toInt | assignTo: from }}
<div style="text-align:right;margin:-54px 0 30px 0">
  {{#if from > 1}} <a href="?from={{ max(from-4,0) }}" title="{{max(from-1,0)}}">previous</a> |{{/if}}
  {{from}} | <a href="?from={{ from+4 }}" title="{{max(from-1,0)}}">next</a>
</div>
```
:::

Then changing the `index.html` SVG fragment to use the `from` value on the y-axis:

::: v-pre
```hbs
<svg height="640" width="240">
{{#each range(180) }}
  {{ 120 + 100 * cos((5)    * it * 0.02827) | assignTo: x }}
  {{ 320 + 300 * sin((from) * it * 0.02827) | assignTo: y }}
  <circle cx="{{x}}" cy="{{y}}" r="10" fill="rgb(0,100,0)" stroke="black" stroke-width="1"/>
{{/each}} 
</svg>
```
:::

Whilst the `multi.html` and `animated.html` pages can use it in its `range(from, 4)` function:

::: v-pre
```hbs
{{#each i in range(from, 4) }}
<svg height="640" width="240">
{{#each range(180) }}
  {{ 120 + 100 * cos((5) * it * 0.02827) | assignTo: x }}
  {{ 320 + 300 * sin((1+i)  * it * 0.02827) | assignTo: y }}
  <circle cx="{{x}}" cy="{{y}}" r="{{it*0.1}}" fill="rgb(0,{{it*1.4}},0)" stroke="black" stroke-width="1"/>
{{/each}} 
</svg>
{{/each}}
```
:::

With navigation activated we can quickly scroll through and explore different spirals. To save ourselves the effort of finding them again lets
catalog our favorite picks and add them to a bookmarked list at the bottom of the page. Here are some interesting ones I've found for the home page:

::: v-pre
```hbs
<div>
  Jump to favorites: 
  {{#each [1,5,101,221,222,224,298,441,443,558,663,665,666,783,888] }}
    {{#if index > 0}} | {{/if}} {{#if from == it }} {{it}} {{else}} <a href="?from={{it}}">{{it}</a> {{/if}}
  {{/each}}
</div>
```
:::

and my top picks for the `multi.html` and `animated.html` pages:

::: v-pre
```hbs
<div>
  Jump to favorites: 
  {{#each [1,217,225,229,441,449,661,669,673,885,1338,3326,3338,4330,8662,9330,11998] }}
    {{#if index > 0}} | {{/if}} {{#if from == it }} {{it}} {{else}} <a href="?from={{it}}">{{it}</a> {{/if}}
  {{/each}}
</div>
```
:::

> If you've found more interesting ones, [let me know](https://github.com/mythz/spirals/issues)!

Now it's just a matter of signing off our digital piece by giving it a name in your `app.settings`:

```
name Spirals
```

Which replaces the name in the `menu` and used in any shortcuts that are created, and with those finishing touches our App's journey
into the rich colorful world of SVG is complete:

[![](/img/pages/app/spirals/spiral-nav.png)](http://spirals.web-app.io/animated)

## Publishing your App

To share our digital masterpiece with the world we just need to publish it in a GitHub repo, which I've already done for my Spirals app at: 
[github.com/mythz/spirals](https://github.com/mythz/spirals).

Anyone will then be able to install your App by first downloading the `app` tool themselves ([.NET 6.0 Required](https://www.microsoft.com/net/download/)):

:::sh
dotnet tool install -g app
:::

Then running `install` with the name of the **repo** and your GitHub **User** or **Organization** name in the `--source` argument:

:::sh
app install spirals --source mythz
:::

Which installs instantly thanks to the `7kb` .zip download that can then be opened by double-clicking on the generated **Spirals** Desktop Shortcut:

![](/img/pages/app/app-install-spirals.png)

### Publishing Gist Apps

As Sharp Apps are so lightweight a flexible deployment option is to deploy it to GitHub gists where they can be launched directly from HTML links using the `app://` URL scheme.

To create gists you'll need to generate a [GitHub Access Token](https://github.com/settings/tokens/new) with **gist** scope and add it to your `GITHUB_TOKEN` Environment Variable ([win](https://superuser.com/questions/949560/how-do-i-set-system-environment-variables-in-windows-10), [mac](https://apple.stackexchange.com/q/356441/12255), [linux](https://www.digitalocean.com/community/tutorials/how-to-read-and-set-environmental-and-shell-variables-on-linux)). _(alternative: use `-token` arg in each publish command)_

Before publishing our App, our **app.settings** looks something like:

```
debug true
name Spirals
CefConfig { width:1100, height:900 }
```

To make your App listed in our Global App Directory, include the following metadata about your App:

```
appName     <app alias>    # required: alpha-numeric snake-case characters only, 30 chars max
description <app summary>  # required: 20-150 chars
tags        <app tags>     # optional: space delimited, alpha-numeric snake-case, 3 tags max
```

The `appName` is the globally unique short alias you want your App to be launched as, e.g:

```
app://my-alias
```

:::sh
app open my-alias
:::

If your app.settings contains the app metadata above, publishing the app will publish your App to a Gist & register your App's alias to the Global App Directory.

Then to publish your App to a new Gist, run:

:::sh
app publish
:::

Which will publish your app to a new gist:

```bash
published to: https://gist.github.com/gistlyn/4e06df1f1b9099526a7c97721aa7f69c

Run published App:

    app open spirals
```

To update your Gist run publish again:

:::sh
app publish
:::

When your App is published the first time, the created gist URL will be saved in a local `.publish` text file & used for subsequent App publishes.

After it's published anyone will now be able to run your App locally with the global alias (if specified):

```
app://spirals
```

:::sh
app open spirals
:::

The Gist Id:

```
app://4e06df1f1b9099526a7c97721aa7f69c
```

:::sh
app open 4e06df1f1b9099526a7c97721aa7f69c
:::

Or Gist URL:

:::sh
app open https://gist.github.com/gistlyn/4e06df1f1b9099526a7c97721aa7f69c
:::

Users that are not on Windows can use the `x` dotnet tool instead to launch your App in their preferred browser:

:::sh
x open spirals
:::

If preferred, Windows users can also launch your Gist Desktop App in their preferred browser (i.e. instead of a Chromium Desktop Shell) with the `xapp://` URL Scheme:

```
xapp://spirals
```

### Vue Desktop Template

To simplify the development UX we've created the [vue-desktop](https://github.com/NetCoreTemplates/vue-desktop) .NET Core Desktop Project Template with integrated scripts for building, bundling and publishing Windows Desktop Apps:

> YouTube [youtu.be/kRnQSWdqH6U](https://youtu.be/kRnQSWdqH6U)

<lite-youtube class="w-full mx-4 my-4" width="560" height="315" videoid="kRnQSWdqH6U" style="background-image: url('https://img.youtube.com/vi/kRnQSWdqH6U/maxresdefault.jpg')"></lite-youtube>

The Vue Desktop Template allows for multiple deployment options, including:

  1. Publish to a Gist
  2. Publish to a GitHub Repo
  3. Publish to .zip and run with `app` tool
  4. Publish to self-contained .zip (bundled with app tool)

Our recommendation is to publish Sharp Desktop Apps to Gists (as done with [ServiceStack Studio](/studio)) so they can be launched with the Custom URL Scheme:

```
app://vuedesktop
```

Where it can be launched from a HTML `<a/>` link in a web page, directly in any **browsers URL bar** or **File Explorer**.

Desktop Apps published to GitHub repos can be opened using `<user>/<repo>`, e.g:

```
app://mythz/vuedesktop
```

Where it downloads & extracts the latest Release `.zip` archive (or master if none), before running the app, so can take a little longer to launch for small Apps.

All apps run the latest version by default so it's always up-to-date, but you can speed up App launch times by running the last installed app using the `app:` Custom URL Scheme:

```bash
app:vuedesktop
```

For Gist deployed Apps, it will run the last downloaded app or download & run the latest App gist if it's the first time it's run.

For GitHub repo Apps, you can download and install them locally with:

:::sh
app install mythz/vuedesktop
:::

Where the downloaded version can be **run** using its `<repo>` name, e.g:

```
app:vuedesktop
```

Both Gist and Desktop Apps can be uninstalled using `app uninstall`, e.g:

```
$ app uninstall vuedesktop

To view all installed Sharp Apps, run:

$ app uninstall
```

#### Creating Windows Shortcuts

The `app:` URL Scheme is a convenient way to launch Apps if you already have a **Browser** or Windows **File Explorer** already open where you can quickly launch Apps by typing `CTRL+L` shortcut to go to the Command Bar then type  `app://<name>` to launch your App.

Although many users will prefer the familiar Windows Shortcut which they can create by going to the App's folder and running `app shortcut`

:::sh
cd %USERPROFILE%\.sharp-apps\vuedesktop
:::

:::sh
app shortcut
:::

This will create a Windows Shortcut for the App which can be copied to the Desktop or pinned to the Taskbar for easy access.

### Publishing Gist Apps

Publishing your App to a gist is our preferred option as you can use GitHub to host your App, built-in auto-updates with every each launch and if you publish to the Global App Registry users can download & install your App with a unique UX-friendly name like `app://vuedesktop`.

To create gists you'll need to generate a [GitHub Access Token](https://github.com/settings/tokens/new) with **gist** scope and add it to your `GITHUB_TOKEN` Environment Variable ([win](https://superuser.com/questions/949560/how-do-i-set-system-environment-variables-in-windows-10), [mac](https://apple.stackexchange.com/q/356441/12255), [linux](https://www.digitalocean.com/community/tutorials/how-to-read-and-set-environmental-and-shell-variables-on-linux)). _(alternative: use `-token` arg in each publish command)_

Before publishing your App, its **app.settings** looks something like:

```
debug true
name vuedesktop
CefConfig { width:1100, height:900 }
```

#### Publish to the Global App Registry

To maximize reach and accessibility of your App you can publish it to our [Global App Registry](https://gist.github.com/gistlyn/802daba52b6fe6e2ed1430348dc596cb) by including the following metadata about your App:

```
appName     <app alias>    # required: alpha-numeric snake-case characters only, 30 chars max
description <app summary>  # required: 20-150 chars
tags        <app tags>     # optional: space delimited, alpha-numeric snake-case, 3 tags max
```

The `appName` is the globally unique short alias you want your App to be launched as, e.g:

```
app://my-alias
```

:::sh
app open my-alias
:::

If your app.settings contains the app metadata above, publishing the app will publish your App to a Gist & register your App's alias to the Global App Directory.

Now you can build, bundle and publish your App to a gist with its `publish-app` npm script:

:::sh
npm run publish-app
:::

That returns the gist URL your app was published to:

```
published to: https://gist.github.com/gistlyn/48b2dcf9bccacab62ec9d8a073d5edb8
```

Which can now be opened via an [URL scheme](https://sharpscript.net/sharp-apps/app-index#app-url-schemes): 

<h4><a href="app://48b2dcf9bccacab62ec9d8a073d5edb8">app://48b2dcf9bccacab62ec9d8a073d5edb8</a></h4>

Or via the command line:

:::sh
app open 48b2dcf9bccacab62ec9d8a073d5edb8
:::

When your App is published the first time, the created gist URL will be saved in a local `.publish` text file & used for subsequent App publishes.

#### Local Aliases

If the Gist App isn't published to the Global Registry, users can create their own UX-friendly local alias with:

:::sh
app alias my-alias 48b2dcf9bccacab62ec9d8a073d5edb8
:::

Where they'll be able to use their alias instead of the Gist Id:

```
app://my-alias
```

:::sh
app open my-alias
:::

### Publishing to a GitHub Repo

The same `/dist` folder that's published to Gists can also be published to a GitHub Repo like [github.com/mythz/vuedesktop](https://github.com/mythz/vuedesktop) which can be launched with the `<user>/<repo>` URL Scheme, e.g:

<h3 id="app-mythz-vuedesktop" tabindex="-1"><a href="app://mythz/vuedesktop">app://mythz/vuedesktop</a> <a class="header-anchor" href="#app-mythz-vuedesktop" aria-hidden="true">#</a></h3>

> Need to copy + paste URL in browser as GitHub markdown doesn't allow custom URL links

Or launched from the command-line:

:::sh
app open mythz/vuedesktop
:::

Users can also download and run a local copy launched with a Windows Shortcut with this 1-liner:

:::sh
app download mythz/vuedesktop && cd vuedesktop && app shortcut
:::

This will download this repo and create a **Vue Desktop** Windows Shortcut you can use to launch this App:

![](/img/pages/app/vue-desktop/vuedesktop-dist.png)

### Publish to .zip

The `/dist` folder can also be zipped and distributed that way, by running:

:::sh
npm run publish-zip
:::

In which case it can be extracted and launched by running the `app` command in the App's folder:

```bash
$ cd AppDir
$ app
```

But if you're going to run from a local folder (where `app://` isn't available), you'll likely want to create a Windows Shortcut:

:::sh
app shortcut
:::

That Users can copy to their Desktop or pin to their Taskbar for easy access.

### Publishing self-encapsulated .zip

By having the `app` tool installed, users benefit from ultra small (e.g. **15kb**) downloads whose tiny footprints allows for auto-updating with each App launch so they have access to new features as soon as they're available. Users will also be able to update to the Chromium version used to run all their Sharp Desktop Apps by updating the `app` tool:

:::sh
dotnet tool update -g app
:::

But if preferred, App's can also bundled and distributed with the `app` tool so they can be run without needing the `app` tool installed and distributed Apps are pinned to a specific Chromium version.

You can create self-encapsulated bundles with the `publish-exe` script:

:::sh
npm run publish-exe
:::

This will generate 2 files:

![](/img/pages/app/vue-desktop/vuedesktop-publish-exe.png)

The `*.zip` contains both the `/dist` of your App and the `app` Chromium runtime as well as a convenience [install.ps1](https://github.com/NetCoreTemplates/vue-desktop/blob/master/scripts/install.ps1) script that users can use to effortlessly install the App with the `Win+R` shortcut to bring up Windows **Run** dialog then pasting this powershell cmd-let with the URL of your `install.ps1` script:

```bash
powershell Set-ExecutionPolicy Bypass -Scope Process -Force; iex ((New-Object System.Net.WebClient).DownloadString('https://org.example/install.ps1'))
```

![](/img/pages/app/vue-desktop/vuedesktop-run-install.png)

Here's a copy of `install.ps1` which downloads and extracts the App to the Users LocalApp Data and copies the Shortcut to the Desktop.
Before publishing you'll need to update `$zipUrl` to point to the URL with your `*.zip`:

```bash
$zipUrl  = "https://org.example/MyApp.zip"
$appName = "MyApp"

$TempFile = New-TemporaryFile
Invoke-WebRequest $zipUrl -OutFile $TempFile

$Zip = "$(Join-Path $TempFile.Directory.FullName $TempFile.BaseName).zip"
Move-Item $TempFile $Zip

Remove-Item $(Join-Path $TempFile.Directory.FullName $TempFile.BaseName) -Recurse -ErrorAction Ignore
Expand-Archive -Force $Zip $(Join-Path $TempFile.Directory.FullName $TempFile.BaseName)

$AppDir = $(Get-ChildItem -Path $(Join-Path $TempFile.Directory.FullName $TempFile.BaseName) | Select-Object -First 1)

Remove-Item "$env:LOCALAPPDATA\$appName" -Recurse -ErrorAction Ignore
Move-Item $AppDir.FullName "$env:LOCALAPPDATA\$appName"

# Copy Shortcut to Desktop
Copy-Item $env:LOCALAPPDATA\$appName\dist\*.lnk -Destination $env:USERPROFILE\Desktop 

# Clean up
Remove-Item $Zip -Recurse -ErrorAction Ignore
Remove-Item $(Join-Path $TempFile.Directory.FullName $TempFile.BaseName) -Recurse -ErrorAction Ignore
```

Here's an example of an app we have published to our servers:

```bash
powershell Set-ExecutionPolicy Bypass -Scope Process -Force; iex ((New-Object System.Net.WebClient).DownloadString('https://files.sharpscript.net/VueDesktop/install.ps1'))
```


# Mix features into ASP.NET Core Projects from Gists
Source: https://docs.servicestack.net/mix-tool

To complete the picture of making it easy as possible to compose ASP.NET Core Apps & easily install features we've added `mix` support to the 
[dotnet tools](/dotnet-tool):

:::sh
dotnet tool install --global x
:::

The same functionality is also built into the Windows [app](/netcore-windows-desktop) dotnet tool, both can be updated to the latest version with:

.NET 6.0 (Windows/macOS/Linux):

:::sh
dotnet tool update -g x
:::

.NET 6.0 (Windows x64):

:::sh
dotnet tool update -g app
:::

### mix-enabled dotnet tools

`mix` works exactly the same in all dotnet tools, which just needs the **tool name prefixed** before the `mix` command:

```bash
x mix ...
app mix ...
```

### mix Usage

`x mix` is designed around applying ASP.NET Core features captured in GitHub gists to your local .NET Core projects. 

Type `x mix ?` for a quick Usage Summary:

```
View all published gists:
   x mix

Simple Usage:
   x mix <name> <name> ...

Mix using numbered list index instead:
   x mix 1 3 5 ...

Delete previously mixed gists:
   x mix -delete <name> <name> ...

Use custom project name instead of current folder name (replaces MyApp):
   x mix -name ProjectName <name> <name> ...

Replace additional tokens before mixing:
   x mix -replace term=with <name> <name> ...

Multi replace with escaped string example:
   x mix -replace term=with -replace "This Phrase"="With This" <name> <name> ...

Only display available gists with a specific tag:
  x mix [tag]
  x mix [tag1,tag2]
```

Although most of the time you're only going to run 2 commands, viewing available features with:

:::sh
x mix
:::

Where it displays different features that can be added to your App, where they're added to and the author of the Gist:

```
   1. console-cs                 C# .NET 8 Console App                                                             to: .                            by @ServiceStack    [project,C#]
   2. console-fs                 F# .NET 8 Console App                                                             to: .                            by @ServiceStack    [project,F#]
   3. console-vb                 VB .NET 8 Console App                                                             to: .                            by @ServiceStack    [project,VB]
   4. console-ss                 #Script Console App                                                               to: .                            by @ServiceStack    [project,S#]
   5. console-lisp               #Script Lisp Console App                                                          to: .                            by @ServiceStack    [project,Lisp]
   6. init                       Empty .NET 8 ServiceStack App                                                     to: .                            by @ServiceStack    [project,C#]
   7. init-lts                   Empty .NET 8 LTS ServiceStack App                                                 to: .                            by @ServiceStack    [project,C#]
   8. init-vb                    VB.NET Empty .NET 8 ServiceStack App                                              to: .                            by @ServiceStack    [project,VB]
   9. init-fsharp                F# Empty .NET 8 ServiceStack App                                                  to: .                            by @ServiceStack    [project,F#]
  10. init-corefx                Empty ASP.NET Core 2.1 LTS on .NET Framework                                      to: .                            by @ServiceStack    [project,C#]
  11. init-sharp-app             Empty ServiceStack Sharp App                                                      to: .                            by @ServiceStack    [project,S#]
  12. init-test                  .NET 8 Integration Test                                                           to: .                            by @ServiceStack    [project,C#]
  13. init-test2                 .NET 8 and .NET v4.72 Integration Test                                            to: .                            by @ServiceStack    [project,C#]
  14. redis                      Use ServiceStack.Redis                                                            to: $HOST                        by @ServiceStack    [db]
  15. sqlserver                  Use OrmLite with SQL Server                                                       to: $HOST                        by @ServiceStack    [db]
  16. sqlite                     Use OrmLite with SQLite                                                           to: $HOST                        by @ServiceStack    [db]
  17. postgres                   Use OrmLite with PostgreSQL                                                       to: $HOST                        by @ServiceStack    [db]
  18. mysql                      Use OrmLite with MySql                                                            to: $HOST                        by @ServiceStack    [db]
  19. oracle                     Use OrmLite with Oracle                                                           to: $HOST                        by @ServiceStack    [db]
  20. firebird                   Use OrmLite with Firebird                                                         to: $HOST                        by @ServiceStack    [db]
  21. dynamodb                   Use AWS DynamoDB and PocoDynamo                                                   to: $HOST                        by @ServiceStack    [db]
  22. mongodb                    Use MongoDB                                                                       to: $HOST                        by @ServiceStack    [db]
  23. ravendb                    Use RavenDB                                                                       to: $HOST                        by @ServiceStack    [db]
  24. marten                     Use Marten                                                                        to: $HOST                        by @ServiceStack    [db]
  25. auth                       Configure AuthFeature                                                             to: $HOST                        by @ServiceStack    [auth]
  26. auth-ext                   Configure AuthFeature inc. extended .NET Providers                                to: $HOST                        by @ServiceStack    [auth]
  27. auth-db                    Use OrmLite Auth Repository (requires auth)                                       to: $HOST                        by @ServiceStack    [auth]
  28. auth-redis                 Use Redis Auth Repository (requires auth)                                         to: $HOST                        by @ServiceStack    [auth]
  29. auth-memory                Use Memory Auth Repository (requires auth)                                        to: $HOST                        by @ServiceStack    [auth]
  30. auth-dynamodb              Use DynamoDB Auth Repository (requires auth)                                      to: $HOST                        by @ServiceStack    [auth]
  31. auth-mongodb               Use MongoDB Auth Repository (requires auth)                                       to: $HOST                        by @ServiceStack    [auth]
  32. auth-ravendb               Use RavenDB Auth Repository (requires auth)                                       to: $HOST                        by @ServiceStack    [auth]
  33. auth-marten                Use Marten Auth Repository (requires auth)                                        to: $HOST                        by @ServiceStack    [auth]
  34. backgroundmq               Use Memory Background MQ                                                          to: $HOST                        by @ServiceStack    [mq]
  35. rabbitmq                   Use RabbitMQ                                                                      to: $HOST                        by @ServiceStack    [mq]
  36. sqs                        Use AWS SQS MQ                                                                    to: $HOST                        by @ServiceStack    [mq]
  37. servicebus                 Use Azure Service Bus MQ                                                          to: $HOST                        by @ServiceStack    [mq]
  38. redismq                    Use Redis MQ                                                                      to: $HOST                        by @ServiceStack    [mq]
  39. autoquery                  Configure AutoQuery Services                                                      to: $HOST                        by @ServiceStack    [autoquery]
  40. autocrudgen                AutoGen AutoQuery Services for Existing DBs                                       to: $HOST                        by @ServiceStack    [autoquery,autogen,db]
  41. autodto                    Generate DB DTOs in C#, TypeScript, Dart, Java, Kotlin, Swift, VB.NET, F#         to: .                            by @ServiceStack    [autoquery,codegen]
  42. migrations                 Add OrmLite DB Migrations to an existing project                                  to: $HOST                        by @ServiceStack    [db]
  43. validation-source          Configure dynamic RDBMS validations source                                        to: $HOST                        by @ServiceStack    [validation]
  44. profiling                  Configure Request Logging & Profiling                                             to: $HOST                        by @ServiceStack    [feature]
  45. serverevents               Configure Server Events (SSE)                                                     to: $HOST                        by @ServiceStack    [feature,sse]
  46. cors                       Configure support for CORS                                                        to: $HOST                        by @ServiceStack    [feature,cors]
  47. openapi                    Configure support for Open API and Swagger UI                                     to: $HOST                        by @ServiceStack    [feature,postman]
  48. feature-mq                 Simple MQ Feature to test sending Messages                                        to: $HOST                        by @ServiceStack    [feature,mq,sharp]
  49. feature-authrepo           List and Search Users registered in Auth Repository                               to: $HOST                        by @ServiceStack    [feature,auth,sharp]
  50. hangfire-postgres          Adds hangfire cron scheduler and dashboard for PostgreSQL                         to: $HOST                        by @GuerrillaCoder  [hangfire,postgres]
  51. sharpdata                  Instant JSON,CSV,XML,JSV data APIs around configured RDBMS tables                 to: .                            by @ServiceStack    [S#]
  52. flutter                    Add flutter project                                                               to: .                            by @ServiceStack    [flutter,mobile]
  53. flutter-grpc               Add flutter project with GRPC                                                     to: .                            by @ServiceStack    [flutter,mobile]
  54. build                      Adds GitHub Action to build and test                                              to: .                            by @ServiceStack    [github]
  55. release-ecr-aws            Adds GitHub Action to deploy to AWS ECS                                           to: .                            by @ServiceStack    [github]
  56. release-ghr-vanilla        Adds GitHub Action to deploy to a Linux server using SSH, via GHCR                to: .                            by @ServiceStack    [github]
  57. release-ecr-vanilla        Adds GitHub Action to deploy to a Linux server using SSH, via AWS ECR             to: .                            by @ServiceStack    [github]
  58. release-hub-vanilla        Adds GitHub Action to deploy to a Linux server using SSH, via DockerHub           to: .                            by @ServiceStack    [github]
  59. blazor-litestream-aws      Use SQLite and Litestream replicating to AWS S3 for Blazor templates              to: .                            by @ServiceStack    [github]
  60. blazor-litestream-azure    Use SQLite and Litestream replicating to Azure Blob Storage for Blazor templates  to: .                            by @ServiceStack    [github]
  61. blazor-litestream-sftp     Use SQLite and Litestream replicating to SFTP server for Blazor templates         to: .                            by @ServiceStack    [github]
  62. jamstack-litestream-aws    Use SQLite and Litestream replicating to AWS S3 for JamStack templates            to: .                            by @ServiceStack    [github]
  63. jamstack-litestream-azure  Use SQLite and Litestream replicating to Azure Blob for JamStack templates        to: .                            by @ServiceStack    [github]
  64. jamstack-litestream-sftp   Use SQLite and Litestream replicating to SFTP server for JamStack templates       to: .                            by @ServiceStack    [github]
  65. litestream-aws             Use SQLite and Litestream replicating to AWS S3                                   to: .                            by @ServiceStack    [github]
  66. litestream-azure           Use SQLite and Litestream replicating to Azure Blob Storage                       to: .                            by @ServiceStack    [github]
  67. litestream-sftp            Use SQLite and Litestream replicating to an SFTP server                           to: .                            by @ServiceStack    [github]
  68. blazor-upgrade-clean       Remove old files                                                                  to: .                            by @ServiceStack    [upgrade]
  69. blazor-upgrade             Update to latest Files                                                            to: .                            by @ServiceStack    [upgrade]
  70. migration-upgrade-blazor   Update to latest GitHub Action release for Blazor templates                       to: .                            by @ServiceStack    [upgrade]
  71. migration-upgrade-js       Update to latest GitHub Action release for JS Jamstack templates                  to: .                            by @ServiceStack    [upgrade]
  72. nuglify                    Use Nuglify's Advanced JS/CSS/HTML Minifiers                                      to: $HOST                        by @ServiceStack    [assets]
  73. northwind.sqlite           northwind.sqlite                                                                  to: .                            by @ServiceStack    [sqlite]
  74. chinook.sqlite             chinook.sqlite                                                                    to: .                            by @ServiceStack    [sqlite]
  75. northwind.sharpdata        northwind.sharpdata                                                               to: .                            by @ServiceStack    [sharpdata]
  76. chinook.sharpdata          chinook.sharpdata                                                                 to: .                            by @ServiceStack    [sharpdata]
  77. grpc                       Configure gRPC                                                                    to: $HOST                        by @ServiceStack    [feature,grpc]
  78. grpc-android               Android gRPC SSL Channel Builder                                                  to: .                            by @ServiceStack    [java,grpc]
  79. bcl.proto                  protobuf-net\bcl.proto                                                            to: .                            by @ServiceStack    [grpc]
  80. example-validation         Contacts Validation Example                                                       to: $HOST                        by @ServiceStack    [example,sharp]
  81. feedz                      ServiceStack pre-release Feedz packages                                           to: .                            by @ServiceStack    [config]
  82. gh-nuget                   ServiceStack pre-release GitHub packages                                          to: .                            by @ServiceStack    [config]
  83. myget                      ServiceStack pre-release MyGet packages                                           to: .                            by @ServiceStack    [config]
  84. nginx                      Nginx reverse proxy config for .NET Core Apps                                     to: /etc/nginx/sites-available/  by @ServiceStack    [config]
  85. nginx-yum                  Nginx reverse proxy (yum) config for .NET Core Apps                               to: /etc/nginx/conf.d/           by @ServiceStack    [config]
  86. supervisor                 Supervisor config for managed execution of .NET Core Apps                         to: /etc/supervisor/conf.d/      by @ServiceStack    [config]
  87. supervisord.service        Systemd supervisord.service script                                                to: /usr/lib/systemd/system/     by @ServiceStack    [config]
  88. supervisor-sharp           Supervisor config for managed execution of Sharp Apps                             to: /etc/supervisor/conf.d/      by @ServiceStack    [config]
  89. docker                     Dockerfile example for .NET Core Sharp Apps                                       to: .                            by @ServiceStack    [config]
  90. nlog                       Adds prod/dev default config files. Saves to APP_LOG_PATH                         to: $HOST                        by @GuerrillaCoder  [config]
  91. gen-dev-crt.sh             Generate *.servicestack.com self-signed localhost certificate                     to: $HOST                        by @ServiceStack    [config]
  92. typechat.mjs               Node typechat.mjs script                                                          to: $HOST                        by @ServiceStack    [config]
  93. gen.https.sh               gen.https.sh                                                                      to: .                            by @ServiceStack    [files,ssl]
  94. docker-dotnet              Docker file to build basic ServiceStack application                               to: .                            by @ServiceStack    [docker]
  95. docker-dotnet-spa          Docker file to build ServiceStack application that also needs node                to: .                            by @ServiceStack    [docker]
  96. docker-jupyter             Jupyter Dockerfile for running C# and F# Notebooks on mybinder.org                to: .                            by @ServiceStack    [docker]
  97. docker-jupyter-reports     Jupyter Dockerfile for running C#,F# and LaTeX support for nbconvert              to: .                            by @ServiceStack    [docker]
 
   Usage:  x mix <name> <name> ...

  Search:  x mix [tag] Available tags: auth, config, db, feature, lib, mq, project, react, sharp, svg, ui, vue

Advanced:  x mix ?
```

Then choosing which features you want to add to your project with `x mix <name>`, e.g:

:::sh
x mix redis
:::

The entire list of available features is maintained in the self-documenting human and machine readable
[mix.md](https://gist.github.com/gistlyn/9b32b03f207a191099137429051ebde8) feature index.

> To publish your feature here and make it available to all `mix` users, please [link to it in the comments](https://gist.github.com/gistlyn/9b32b03f207a191099137429051ebde8#comments).

### Mix in Features into ASP.NET Core Apps

It should be noted that `ModularStartup` and `mix` dotnet tool aren't limited to ServiceStack Apps, they're a generic solution
that can easily add features to any .NET Core App. E.g. some of ServiceStack features relies on external dependencies which utilizes
the same dependency registration used in all ASP.NET Core Apps, e.g running:

:::sh
x mix mongodb
:::

Applies the `mongodb` feature to your HOST project as instructed by the `to: $HOST` modifier above that it finds by
using the first folder containing either `appsettings.json`, `Program.cs` or `Startup.cs`
and writing the following [mongodb Gist file](https://gist.github.com/gistlyn/f777396583262127a66e2369ae475d3f):

```csharp
namespace MyApp
{
    public class ConfigureMongoDb : IConfigureServices
    {
        IConfiguration Configuration { get; }
        public ConfigureMongoDb(IConfiguration configuration) => Configuration = configuration;

        public void Configure(IServiceCollection services)
        {
            var mongoClient = new MongoClient();
            IMongoDatabase mongoDatabase = mongoClient.GetDatabase("MyApp");
            container.AddSingleton(mongoDatabase);
        }
    }    
}
```

With all `MyApp` tokens replaced with the **Project Name** using the same replacement rules as new projects, i.e:

 - `MyApp` will be replaced with `ProjectName`
 - `my-app` will be replaced with `project-name`
 - `My App` will be replaced with `Project Name`

By default it assumes the folder name is the project name, that's overridable using the `-name` flag:

:::sh
x mix -name ProjectName mongodb
:::

This feature also installs the **MongoDB.Driver** NuGet package as instructed by the `_init` command in the 
[mongodb feature](https://gist.github.com/gistlyn/f777396583262127a66e2369ae475d3f).

So after just a single `mix` command and App restart, it's now configured and running with MongoDB!

#### Registering MongoDB Auth Repository

As a design goal `mix` features are designed to be layerable where you can existing features that builds upon existing registrations, 
for example you can later configure your App to **enable auth** and configure it to use a `MongoDbAuthRepository` with:

:::sh
x mix auth auth-mongodb
:::

### Mix in DB Support

All DB servers are just as easily configurable, which we can quickly find using a `[db]` tag search:

:::sh
x mix [db]
:::

::: info Tip
search term needs to be quoted in unix shells, e.g: '[db]'
:::

Which will list all available `[db]` providers:

```
Results matching tag [db]:

   1. redis      Use ServiceStack.Redis            to: $HOST  by @ServiceStack  [db]
   2. sqlserver  Use OrmLite with SQL Server       to: $HOST  by @ServiceStack  [db]
   3. sqlite     Use OrmLite with SQLite           to: $HOST  by @ServiceStack  [db]
   4. postgres   Use OrmLite with PostgreSQL       to: $HOST  by @ServiceStack  [db]
   5. mysql      Use OrmLite with MySql            to: $HOST  by @ServiceStack  [db]
   6. oracle     Use OrmLite with Oracle           to: $HOST  by @ServiceStack  [db]
   7. firebird   Use OrmLite with Firebird         to: $HOST  by @ServiceStack  [db]
   8. dynamodb   Use AWS DynamoDB and PocoDynamo   to: $HOST  by @ServiceStack  [db]
   9. mongodb    Use MongoDB                       to: $HOST  by @ServiceStack  [db]
  10. ravendb    Use RavenDB                       to: $HOST  by @ServiceStack  [db]
  11. marten     Use Marten NoSQL with PostgreSQL  to: $HOST  by @ServiceStack  [db]

   Usage:  x mix <name> <name> ...

  Search:  x mix [tag] Available tags: auth, config, db, feature, lib, mq, project, react, sharp, svg, ui, vue

Advanced:  x mix ?
```

So we can install Redis with:

:::sh
x mix redis
:::

Where it will apply the [Redis Gist](https://gist.github.com/gistlyn/512309b3cb7d734bb0f7323907499b08) below:

```csharp
namespace MyApp
{
    public class ConfigureRedis : IConfigureServices, IConfigureAppHost
    {
        IConfiguration Configuration { get; }
        public ConfigureRedis(IConfiguration configuration) => Configuration = configuration;

        public void Configure(IServiceCollection services)
        {
            services.AddSingleton<IRedisClientsManager>(
                new RedisManagerPool(Configuration.GetConnectionString("Redis") ?? "localhost:6379"));
        }

        public void Configure(IAppHost appHost)
        {
            appHost.GetPlugin<SharpPagesFeature>()?.ScriptMethods.Add(new RedisScripts());
        }
    }
}
```

The configuration is declarative where it only runs `Configure(IAppHost appHost)` in ServiceStack Apps and only adds the `RedisScripts`
if it's configured with [#Script Pages](https://sharpscript.net/docs/script-pages), otherwise any additional configuration is inert and isn't run.

Typically DB's will require you to specify your App DB's connection string to your external DB (with a default fallback) - where typically the
most effort required to enable a feature is adding a Connection String in your `appsettings.json`.

### Composable Features

A nice characteristic about "no-touch" layerable features are that they're composable, where `mix` will let you hand-pick all features you
want in a single command. For example you can enable Authentication, register an RDBMS Auth Repository using SQL Server with:

:::sh
x mix auth auth-db sqlserver
:::

Which will apply the [Configure.Auth.cs](https://gist.github.com/gistlyn/1ec54e10d44f87e0f20daaf7e2248fea), 
[Configure.AuthRepository.cs](https://gist.github.com/gistlyn/16fddde0763b3eee516d670ab9fab194) and [Configure.Db.cs](https://gist.github.com/gistlyn/7075e53e1fe69d3da12996677b5f3a5a) gists.

If you later wanted to switch to PostgreSQL, you can `mix` it in with:

:::sh
x mix postgres
:::

Where it will override [Configure.Db.cs](https://gist.github.com/gistlyn/faf62da8b8ef30849506631025a5d06c) to use the postgres version, 
leaving any custom logic in `Configure.Auth.cs` or `Configure.AuthRepository.cs` untouched.

Or if you later want to change the Auth Repository to use Redis instead, you can run:

:::sh
x mix auth-redis
:::

Where it will override the existing `Configure.AuthRepository.cs` added by **auth-db**.

### Undo mix

In addition to being easy to add, `mix` makes it easy to undo where you can specify the `-delete` flag to remove all the Gist files added
by all features, e.g:

:::sh
x mix -delete auth auth-db sqlserver
:::

Which will let you review all the files in each Gist that will deleted, then hit `Enter` to confirm:

```
Delete 1 file from 'auth' https://gist.github.com/gistlyn/1ec54e10d44f87e0f20daaf7e2248fea:

C:\Projects\app\Configure.Auth.cs

Delete 1 file from 'auth-db' https://gist.github.com/gistlyn/16fddde0763b3eee516d670ab9fab194:

C:\Projects\app\Configure.AuthRepository.cs

Delete 1 file from 'sqlserver' https://gist.github.com/gistlyn/7075e53e1fe69d3da12996677b5f3a5a:

C:\Projects\app\Configure.Db.cs

Proceed? (n/Y):
```

### Encapsulated Features

A nice benefit of decoupling features into modular classes is that you're able to a richer and more customizable out-of-the-box experience. 

Instead of overloading users with daunting amounts of configuration required in common medium-sized Apps,
most templates will start with an empty slate and leave it for users to read about each feature then decide how to hand-pick 
different configuration to slot it into their own App's configuration. 

On the flip-side if you provide too much configuration Developers wont be confident to know what configuration belongs to which feature
and which feature are interconnected or can be safely removed without breaking their App.

With modular features we can encapsulate configuration in a single `.cs` file that's primed with the popular well-known configuration
for the feature. E.g. The Auth Repositories include an example of maintaining a custom `UserAuth` model, registering the 
[Auth Event](/auth/sessions#session-events) to populate their additional fields on Authentication and sample code necessary for ensuring
a specific Admin User is created on `Startup`:

```csharp
namespace MyApp
{
    // Custom User Table with extended Metadata properties
    public class AppUser : UserAuth
    {
        public string ProfileUrl { get; set; }
        public string LastLoginIp { get; set; }
        public DateTime? LastLoginDate { get; set; }
    }

    public class AppUserAuthEvents : AuthEvents
    {
        public override void OnAuthenticated(IRequest req, IAuthSession session, IServiceBase authService, 
            IAuthTokens tokens, Dictionary<string, string> authInfo)
        {
            var authRepo = HostContext.AppHost.GetAuthRepository(req);
            using (authRepo as IDisposable)
            {
                var userAuth = (AppUser)authRepo.GetUserAuth(session.UserAuthId);
                userAuth.ProfileUrl = session.GetProfileUrl();
                userAuth.LastLoginIp = req.UserHostAddress;
                userAuth.LastLoginDate = DateTime.UtcNow;
                authRepo.SaveUserAuth(userAuth);
            }
        }
    }

    public class ConfigureAuthRepository : IConfigureAppHost, IConfigureServices, IPreInitPlugin
    {
        public void Configure(IServiceCollection services)
        {
            services.AddSingleton<IAuthRepository>(c =>
                new OrmLiteAuthRepository<AppUser, UserAuthDetails>(c.Resolve<IDbConnectionFactory>()) {
                    UseDistinctRoleTables = true
                });            
        }

        public void Configure(IAppHost appHost)
        {
            var authRepo = appHost.Resolve<IAuthRepository>();
            authRepo.InitSchema();

            CreateUser(authRepo, "admin@email.com", "Admin User", "p@55wOrd", roles:new[]{ RoleNames.Admin });
        }

        public void BeforePluginsLoaded(IAppHost appHost)
        {
            appHost.AssertPlugin<AuthFeature>().AuthEvents.Add(new AppUserAuthEvents());
        }

        // Add initial Users to the configured Auth Repository
        public void CreateUser(IAuthRepository authRepo, 
            string email, string name, string password, string[] roles)
        {
            if (authRepo.GetUserAuthByUserName(email) == null)
            {
                var newAdmin = new AppUser { Email = email, DisplayName = name };
                var user = authRepo.CreateUserAuth(newAdmin, password);
                authRepo.AssignRoles(user, roles);
            }
        }
    }
}
```

All captured within a working configuration. You can start appreciating the instant utility of `mix` once you imagine what it was like before 
with how much time an effort it would've taken to scan through docs, learn about each feature independently to be able to piece together 
equivalent functionality.

### Mix in Auth Repository

As it can take a while to piece together how to configure your preferred Auth Repository, use a Custom User Model 
and utilize [Auth Events](/auth/sessions#session-events) to populate it, we now recommend using `mix` to configure
your preferred Auth Repository, which you can query with:

:::sh
x mix [auth]
:::

To display the current list of available Auth Repositories:

```
Results matching tag [auth]:

   1. auth              Configure AuthFeature                        to: $HOST  by @ServiceStack [auth]
   2. auth-db           Use OrmLite Auth Repository (requires auth)  to: $HOST  by @ServiceStack [auth]
   3. auth-redis        Use Redis Auth Repository (requires auth)    to: $HOST  by @ServiceStack [auth]
   4. auth-memory       Use Memory Auth Repository (requires auth)   to: $HOST  by @ServiceStack [auth]
   5. auth-dynamodb     Use DynamoDB Auth Repository (requires auth) to: $HOST  by @ServiceStack [auth]
   6. auth-mongodb      Use MongoDB Auth Repository (requires auth)  to: $HOST  by @ServiceStack [auth]
   7. auth-ravendb      Use RavenDB Auth Repository (requires auth)  to: $HOST  by @ServiceStack [auth]
   8. auth-marten       Use Marten Auth Repository (requires auth)   to: $HOST  by @ServiceStack [auth]
   9. feature-authrepo  List and Search Users in an Auth Repo        to: $HOST  by @ServiceStack [feature,auth]
```

### Mix in MQ Server

Likewise we now recommend using `mix` to configure your preferred MQ Service, other than being quicker to add,
it proposes adopting a naming convention in app settings and file names that other `mix` features can also make use of:

:::sh
x mix [mq]
:::

Currently available list of MQ Services:

```
Results matching tag [mq]:

   1. backgroundmq  Use Memory Background MQ                    to: $HOST  by @ServiceStack  [mq]
   2. rabbitmq      Use RabbitMQ                                to: $HOST  by @ServiceStack  [mq]
   3. sqs           Use AWS SQS MQ                              to: $HOST  by @ServiceStack  [mq]
   4. servicebus    Use Azure Service Bus MQ                    to: $HOST  by @ServiceStack  [mq]
   5. redismq       Use Redis MQ                                to: $HOST  by @ServiceStack  [mq]
   6. feature-mq    Simple MQ Feature to test sending Messages  to: $HOST  by @ServiceStack  [feature,mq,sharp]
```

## Mix in NUglify

You can configure your ServiceStack App to use Nuglify's Advanced HTML, CSS, JS Minifiers using [mix](/mix-tool) with:

:::sh
x mix nuglify 
:::

Which will write [Configure.Nuglify.cs](https://gist.github.com/gistlyn/4bdb79d21f199c22b8a86f032c186e2d) to your **HOST** project.

### Mix in Prebuilt Recipes and Working Examples

`ModularStartup` and `mix` can scale up to complete working examples which can provide instant utility and integration of a feature into
your existing App. By contrast most working examples are typically made available off to the side in stale projects which need to 
be downloaded and run in isolation. If it still works you'd then have to compare the project files with your project and carefully copy over the 
differences you'd think your App needs to replicate its functionality. This can be very time consuming to the point where a lot of users will 
skip trying to download & run the example and instead try to manually configure it in their App.

All `mix` features add their files to your App's [Physical Project Structure](/physical-project-structure) where configuration is added to 
your `Host` Project, Service Contracts are added to your `ServiceModel/` folder and Service Implementations added to your `ServiceInterface/` folder
and any Web assets added to your App's `wwwroot/`. 

They can also be added to both multi and single project solutions in which case they'll be added to `ServiceInterface` and `ServiceModel` folders 
in your App's project folder using the same namespace as used in multi-project solutions, making it easy to upgrade to a multi-project solution later.

### example-validation

The `example-validation` **mix** is a complete working validation example that's typical of a real-world validation example complete with 
Authentication integration allowing each authenticated user to manage their own private Contacts list. 

[![](/img/pages/mix/example-validation-900.gif)](https://youtu.be/udrLtICylj8)

> YouTube: [youtu.be/udrLtICylj8](https://youtu.be/udrLtICylj8)

To follow video's example, start with a new **Acme** project from `sharp` .NET Core Template:

:::sh
x new script Acme
:::

Add the `example-validation` mix:

:::sh
cd Acme
:::

:::sh
x mix example-validation
:::

Which will prompt you with a link to the gist and the files that will be added to your project:

```
Write files from 'example-validation' https://gist.github.com/gistlyn/33873ed2857b2c5a9623629c6210d665 to:

  C:\projects\Acme\Acme\Configure.Contacts.cs
  C:\projects\Acme\Acme.ServiceInterface\ContactServices.cs
  C:\projects\Acme\Acme.ServiceModel\Contacts.cs
  C:\projects\Acme\Acme\wwwroot\contacts\_id\edit.html
  C:\projects\Acme\Acme\wwwroot\contacts\_requires-auth-partial.html
  C:\projects\Acme\Acme\wwwroot\contacts\index.html

Proceed? (n/Y):
```

Now after restarting your App you'll be able to add contacts by clicking on the new **Contacts** link in your App's main menu: 

:::sh
cd Acme
:::
:::sh
dotnet run
:::

After you're done reviewing the example you can either refactor it to handle your App's requirements or completely remove it from your App with:

:::sh
x mix -delete example-validation
:::

### feature-mq

The `feature-mq` adds MQ support to your App, complete with UI and includes 2 different ways of calling MQ Services in ServiceStack, just like 
`example-validation` above, `feature-mq` is another complete working example with both UI and Service implementation in the following files:

  - [Configure.Mq.cs?](https://gist.github.com/gistlyn/355338cd60a32ee9c9fc4761269f7782#file-configure-mq-cs)
  - [Feature.Mq.cs](https://gist.github.com/gistlyn/355338cd60a32ee9c9fc4761269f7782#file-feature-mq-cs)
  - [ServiceInterface\MqServices.cs ](https://gist.github.com/gistlyn/355338cd60a32ee9c9fc4761269f7782#file-serviceinterface-mqservices-cs)
  - [ServiceModel\Mq.cs](https://gist.github.com/gistlyn/355338cd60a32ee9c9fc4761269f7782#file-servicemodel-mq-cs)
  - [wwwroot\messaging.html](https://gist.github.com/gistlyn/355338cd60a32ee9c9fc4761269f7782#file-wwwroot-messaging-html)
  
As `Configure.Mq.cs?` is optional it will only add it if doesn't already exist, so it will either use your existing MQ configuration
or configure your App to use the In Memory `BackgroundMqService` implementation.

Add `feature-mq` to your project with:

:::sh
x mix feature-mq
:::

![](/img/pages/nav/feature-mq.png)

This will add the `TestMq` Service and make it available to your MQ endpoint. `TestMq` is a regular service that updates values in the 
App's registered `ICacheClient` and returns the Cache's current values as well as the internal Stats of the MQ:

```csharp
public class MqServices : Service
{
    public IMessageService MqService { get; set; }

    public void Any(PublishMq request)
    {
        PublishMessage(request.ConvertTo<TestMq>());
    }

    public object Any(TestMq request)
    {
        if (!string.IsNullOrEmpty(request.Name))
            Cache.Set("mq.name", request.Name);
        
        if (request.Add > 0)
            Cache.Increment("mq.counter", (uint)request.Add);
        else if (request.Add < 0)
            Cache.Decrement("mq.counter", (uint)(request.Add * -1));

        return new TestMqResponse {
            Name = Cache.Get<string>("mq.name"),
            Counter = Cache.Get<long>("mq.counter"),
            StatsDescription = MqService.GetStatsDescription(),
        };
    }
}
```

The 2 ways to call a MQ Service is directly using the `publish` or `sendOneWay` APIs (available in all ServiceStack Service Clients) where 
it send the request to the Service's `/oneway` endpoint which will automatically publish it to the registered MQ. 

Alternatively you can publish the Request DTO yourself from a different Service Implementation as done in `PublishMq`, as-is typical for
Services that queues sending emails without blocking Service Execution.

The feature's UI allows you to publish `TestMq` messages using either approach:

```js
client = new JsonServiceClient('/');

var oneway = document.querySelector('input[name=mq-publish]:checked').value === "OneWay";
if (oneway) {
    client.publish(new TestMq({ name: $txtName.value, add: parseInt(add) }))
} else {
    client.post(new PublishMq({ name: $txtName.value, add: parseInt(add) }))
}
```

Both approaches end with the same result with the `TestMq` Request DTO published and executed by the registered MQ Service as shown in the
UI which is periodically updated with the current state in the Cache and the internal stats of the MQ Service showing how many messages it processed.

### feature-authrepo

Another UI feature `mix` available is a UI to browse and search for registered users in an Auth Repository.

This wasn't generically possible before as `IAuthRepository` didn't previously provide any API's to be able to query all Users, 
which is now available in the new `IQueryUserAuth` API:

```csharp
public interface IQueryUserAuth
{
    List<IUserAuth> GetUserAuths(string orderBy = null, int? skip = null, int? take = null);
    List<IUserAuth> SearchUserAuths(string query, string orderBy = null, int? skip = null, int? take = null);
}
```

This is now implemented in all ServiceStack Auth Repositories although there are limitations depending on the queryability of the underlying data provider.

Searching in these Auth Repositories are efficient and searches in **UserName**, **Email**, **DisplayName** and **Company** fields:

 - `OrmLiteAuthRepository`
 - `InMemoryAuthRepository` 
 - `MongoDbAuthRepository` 

For RavenDB it reuses the existing Username/Email indexes so only searches **UserName**, **Email** fields and only performs a StartsWith/EndsWith 
search as allowed by RavenDB:

 - `RavenDbUserAuthRepository` 

Searches and Order By's are very inefficient in Redis as it needs to deserialize all users to perform the querying/sorting on the client.
Just paging through users with skip/take is efficient as it only needs to deserialize the partial resultset.

 - `RedisAuthRepository`

All queries performs a table scan in DynamoDB but searches all fields:

 - `DynamoDbAuthRepository`

#### API Usage

These API's are accessible from an `IAuthRepository` dependency, if you're using a custom Auth Repository it will need to implement 
`IQueryUserAuth` otherwise calling these APIs (and feature) will throw a `NotSupportedException`:

```csharp
AuthRepository.GetUserAuths(orderBy:fieldName, skip:skip, take:take)
AuthRepository.SearchUserAuths(query:q, orderBy:fieldName, skip:skip, take:take)
```

The `orderBy` is the field name you want to order the results by, e.g. `UserName` and can suffixed with the `DESC` modifier to order 
results in descending order, e.g. `UserName DESC`.

In `#Script` these API's are available in `camelCase` off `authRepo` using a JS Object literal as seen in `users.html` page usage of this feature:

::: v-pre
```hbs
{{ authRepo.searchUserAuths({ query:qs.q, take: pageSize, skip: pageSize*page }) | to => users }}
```
:::

#### Users UI

Clicking the **Users** menu item will show you a list of searchable and pageable registered Users in a summary view:

![](/img/pages/mix/feature-authrepo.png)

Clicking on a user will show you a complete list of fields stored for that user, including any custom fields, if you're using a Custom
`UserAuth` table:

![](/img/pages/mix/feature-authrepo-admin.png)


# Post Command - HTTP API Command Line Utils
Source: https://docs.servicestack.net/post-command

Post Command is a collection of command line utils that lets you easily discover, inspect and invoke ServiceStack endpoints from a single command.

<lite-youtube class="w-full mx-4 my-4" width="560" height="315" videoid="FcXG4RnlVQk" style="background-image: url('https://img.youtube.com/vi/FcXG4RnlVQk/maxresdefault.jpg')"></lite-youtube>

All command line utils are available in the latest [dotnet tool](/dotnet-tool) which can be installed from:

:::sh
dotnet tool install --global x 
:::

Or if you had a previous version installed, update with:

:::sh
dotnet tool update -g x
:::

## inspect command

The `inspect` command lets you inspect features and APIs available on a remote ServiceStack endpoint including the version of ServiceStack 
running, the App's registered Content Types, Plugins and Auth Providers as well as its public APIs, their routes and Response Types.

Use `x inspect` to display usage examples and available options:

```
Usage: x inspect <base-url>
       x inspect <base-url> <request>
       x inspect <base-url> <request> -lang <csharp|python|typescript|dart|java|kotlin|swift|fsharp|vbnet>
       x inspect <base-url> <request> -lang <cs|py|ts|da|ja|kt|sw|fs|vb>
```

### inspect ServiceStack App

This this command to display high-level information about the endpoint in a human-friendly format, e.g:

:::sh
x inspect https://techstacks.io
:::

Output:

```
Base URL:           https://techstacks.io
Name:               TechStacks!
Version:            5.111

Content Types:      application/json, application/xml, application/jsv, text/html, text/jsonreport, text/csv
Plugins:            html, csv, autoroutes, metadata, ssref, httpcache, svg, sharp, auth, sitemap, cors, validation, autoquerymeta, autoquery, openapi, session
Auth Providers:     twitter (oauth), github (oauth), jwt (Bearer), servicestack (credentials)

| #   | Api                             | Routes                                         | Response                                |
|-----|---------------------------------|------------------------------------------------|-----------------------------------------|
| 1   | Ping                            | /ping                                          |                                         |
| 2   | GetOrganization                 | GET:/orgs/{Id}                                 | GetOrganizationResponse                 |
| 3   | GetOrganizationBySlug           | GET:/organizations/{Slug}                      | GetOrganizationResponse                 |
| 4   | GetOrganizationMembers          | GET:/orgs/{Id}/members                         | GetOrganizationMembersResponse          |
| 5   | GetOrganizationAdmin            | GET:/orgs/{Id}/admin                           | GetOrganizationAdminResponse            |
| 6   | CreateOrganizationForTechnology | POST:/orgs/posts/new                           | CreateOrganizationForTechnologyResponse |
| 7   | CreateOrganization              | POST:/orgs                                     | CreateOrganizationResponse              |
| 8   | UpdateOrganization              | PUT:/orgs/{Id}                                 | UpdateOrganizationResponse              |
| 9   | DeleteOrganization              | DELETE:/orgs/{Id}                              |                                         |
| 10  | LockOrganization                | PUT:/orgs/{Id}/lock                            |                                         |
| 11  | AddOrganizationLabel            | POST:/orgs/{OrganizationId}/labels             | OrganizationLabelResponse               |
| 12  | UpdateOrganizationLabel         | PUT:/orgs/{OrganizationId}/members/{Slug}      | OrganizationLabelResponse               |
| 13  | RemoveOrganizationLabel         | DELETE:/orgs/{OrganizationId}/labels/{Slug}    |                                         |
| 14  | AddOrganizationCategory         | POST:/orgs/{OrganizationId}/categories         | AddOrganizationCategoryResponse         |
| 15  | UpdateOrganizationCategory      | PUT:/orgs/{OrganizationId}/categories/{Id}     | UpdateOrganizationCategoryResponse      |
| 16  | DeleteOrganizationCategory      | DELETE:/orgs/{OrganizationId}/categories/{Id}  |                                         |
| 17  | AddOrganizationMember           | POST:/orgs/{OrganizationId}/members            | AddOrganizationMemberResponse           |
| 18  | UpdateOrganizationMember        | PUT:/orgs/{OrganizationId}/members/{Id}        | UpdateOrganizationMemberResponse        |
| 19  | RemoveOrganizationMember        | DELETE:/orgs/{OrganizationId}/members/{UserId} |                                         |
| 20  | SetOrganizationMembers          | POST:/orgs/{OrganizationId}/members/set        | SetOrganizationMembersResponse          |
| 21  | GetOrganizationMemberInvites    | GET:/orgs/{OrganizationId}/invites             | GetOrganizationMemberInvitesResponse    |
| 22  | RequestOrganizationMemberInvite | POST:/orgs/{OrganizationId}/invites            | RequestOrganizationMemberInviteResponse |
| 23  | UpdateOrganizationMemberInvite  | PUT:/orgs/{OrganizationId}/invites/{UserId}    | UpdateOrganizationMemberInviteResponse  |
| 24  | QueryPosts                      | GET:/posts                                     | QueryResponse<Post>                     |
| 25  | GetPost                         | GET:/posts/{Id}                                | GetPostResponse                         |
| 26  | CreatePost                      | POST:/posts                                    | CreatePostResponse                      |
| 27  | UpdatePost                      | PUT:/posts/{Id}                                | UpdatePostResponse                      |
| 28  | DeletePost                      | DELETE:/posts/{Id}                             | DeletePostResponse                      |
| 29  | LockPost                        | PUT:/posts/{Id}/lock                           |                                         |
| 30  | HidePost                        | PUT:/posts/{Id}/hide                           |                                         |

...
```

Routes with an associated HTTP Verb, e.g. `GET:/technology` only allows access with that specific verb, if unspecified any verb can be used.

### inspect API

Adding an API Name to the command will let you describe a specific API Endpoint to learn more about its features, restrictions & capabilities, e.g:

:::sh
x inspect https://techstacks.io LockTechStack
:::

Which will output the APIs description, any tags it was annotated with, its defined routes as well as any Auth Requirements along with all the 
available Auth Providers registered, e.g:

```csharp
# LockTechStack
Limit updates to TechStack to Owner or Admin users

Tags:               [TechStacks]
Routes:             /admin/techstacks/{TechnologyStackId}/lock

# Requires Auth
Auth Providers:     twitter (oauth), github (oauth), jwt (Bearer), servicestack (credentials)
Roles:              Admin


# C# DTOs:


using System;
using System.Collections;
using System.Collections.Generic;
using System.Runtime.Serialization;
using ServiceStack;
using ServiceStack.DataAnnotations;


public partial class LockStackResponse
{
}

///<summary>
///Limit updates to TechStack to Owner or Admin users
///</summary>
[Route("/admin/techstacks/{TechnologyStackId}/lock")]
public partial class LockTechStack
    : IReturn<LockStackResponse>, IPut
{
    [Validate("GreaterThan(0)")]
    public virtual long TechnologyStackId { get; set; }

    public virtual bool IsLocked { get; set; }
}
```

Whilst the C# code defines the API Service Contract including any user-defined routes, its Response Type, what HTTP Verb it should be called with as well as any declarative validation rules when defined. The properties on the Request DTO define the Typed Inputs that the API Accepts whilst the Response DTO describes what a successful Response will return.

### View all Referenced DTOs

Only the Request and Response DTOs representing the APIs Inputs and Outputs are displayed by default, to include all referenced types you can use the [IncludeTypes syntax](/csharp-add-servicestack-reference#include-request-dto-and-its-dependent-types), e.g:

:::sh
x inspect https://techstacks.io GetTechnology.*
:::

Which will include all referenced types used in this API:

```csharp
# GetTechnology
Tags:               [Tech]
Routes:             /technology/{Slug}

# C# DTOs:


using System;
using System.Collections;
using System.Collections.Generic;
using System.Runtime.Serialization;
using ServiceStack;
using ServiceStack.DataAnnotations;


[Route("/technology/{Slug}")]
public partial class GetTechnology
    : IReturn<GetTechnologyResponse>, IRegisterStats, IGet
{
    public virtual string Slug { get; set; }
}

public partial class GetTechnologyResponse
{
    public GetTechnologyResponse()
    {
        TechnologyStacks = new List<TechnologyStack>{};
    }

    public virtual DateTime Created { get; set; }
    public virtual Technology Technology { get; set; }
    public virtual List<TechnologyStack> TechnologyStacks { get; set; }
    public virtual ResponseStatus ResponseStatus { get; set; }
}

public partial interface IRegisterStats
{
}

public partial class Technology
    : TechnologyBase
{
}

public partial class TechnologyBase
{
    public virtual long Id { get; set; }
    public virtual string Name { get; set; }
    public virtual string VendorName { get; set; }
    public virtual string VendorUrl { get; set; }
    public virtual string ProductUrl { get; set; }
    public virtual string LogoUrl { get; set; }
    public virtual string Description { get; set; }
    public virtual DateTime Created { get; set; }
    public virtual string CreatedBy { get; set; }
    public virtual DateTime LastModified { get; set; }
    public virtual string LastModifiedBy { get; set; }
    public virtual string OwnerId { get; set; }
    public virtual string Slug { get; set; }
    public virtual bool LogoApproved { get; set; }
    public virtual bool IsLocked { get; set; }
    public virtual TechnologyTier Tier { get; set; }
    public virtual DateTime? LastStatusUpdate { get; set; }
    public virtual int? OrganizationId { get; set; }
    public virtual long? CommentsPostId { get; set; }
    public virtual int ViewCount { get; set; }
    public virtual int FavCount { get; set; }
}

public partial class TechnologyStack
    : TechnologyStackBase
{
}

public partial class TechnologyStackBase
{
    public virtual long Id { get; set; }
    public virtual string Name { get; set; }
    public virtual string VendorName { get; set; }
    public virtual string Description { get; set; }
    public virtual string AppUrl { get; set; }
    public virtual string ScreenshotUrl { get; set; }
    public virtual DateTime Created { get; set; }
    public virtual string CreatedBy { get; set; }
    public virtual DateTime LastModified { get; set; }
    public virtual string LastModifiedBy { get; set; }
    public virtual bool IsLocked { get; set; }
    public virtual string OwnerId { get; set; }
    public virtual string Slug { get; set; }
    [StringLength(int.MaxValue)]
    public virtual string Details { get; set; }

    [StringLength(int.MaxValue)]
    public virtual string DetailsHtml { get; set; }

    public virtual DateTime? LastStatusUpdate { get; set; }
    public virtual int? OrganizationId { get; set; }
    public virtual long? CommentsPostId { get; set; }
    public virtual int ViewCount { get; set; }
    public virtual int FavCount { get; set; }
}

public enum TechnologyTier
{
    ProgrammingLanguage,
    Client,
    Http,
    Server,
    Data,
    SoftwareInfrastructure,
    OperatingSystem,
    HardwareInfrastructure,
    ThirdPartyServices,
}
```

Thanks to ServiceStack's [unique message-based design](https://youtu.be/Vae0ALalIP0) the code contract used to define the Service is also all that's needed to invoke the API along with the generic ServiceStack Client library which for .NET is available in the **ServiceStack.Client** NuGet package:

:::sh
dotnet add package ServiceStack.Client
:::

Which together with the above C# DTOs enables its optimal end-to-end typed API:

```csharp
var client = new JsonApiClient("https://techstacks.io");

client.Send(new LockTechStack { TechnologyStackId = id, IsLocked = true });
```

Request DTOs annotated with an `IVerb` interface marker (e.g. `IPut`) can instead use `Send()` to invoke the API with that HTTP Verb.

This same simplified usage scenario is also available in each of [Add ServiceStack Reference](/add-servicestack-reference) supported Languages:

 - [C#](/csharp-add-servicestack-reference)
 - [Python](/python-add-servicestack-reference)
 - [TypeScript](/typescript-add-servicestack-reference)
 - [Dart](/dart-add-servicestack-reference)
 - [Java](/java-add-servicestack-reference)
 - [Kotlin](/kotlin-add-servicestack-reference)
 - [Swift](/swift-add-servicestack-reference)
 - [F#](/fsharp-add-servicestack-reference)
 - [VB.NET](/vbnet-add-servicestack-reference)

Where the `-lang` option can be used to change what language to return the DTO Types in:

```
Usage: x inspect <base-url> <request> -lang <csharp|python|typescript|dart|java|kotlin|swift|fsharp|vbnet>
       x inspect <base-url> <request> -lang <cs|py|ts|da|ja|kt|sw|fs|vb>
```

For example to view the DTOs in Swift run:

:::sh
x inspect https://techstacks.io LockTechStack -lang swift
:::

Output:

```swift
# LockTechStack
Limit updates to TechStack to Owner or Admin users

Tags:               [TechStacks]
Routes:             /admin/techstacks/{TechnologyStackId}/lock

# Requires Auth
Auth Providers:     twitter (oauth), github (oauth), jwt (Bearer), servicestack (credentials)
Roles:              Admin


# Swift DTOs:


import Foundation
import ServiceStack

/**
* Limit updates to TechStack to Owner or Admin users
*/
// @Route("/admin/techstacks/{TechnologyStackId}/lock")
public class LockTechStack : IReturn, IPut, Codable
{
    public typealias Return = LockStackResponse

    // @Validate(Validator="GreaterThan(0)")
    public var technologyStackId:Int?

    public var isLocked:Bool?

    required public init(){}
}

public class LockStackResponse : Codable
{
    required public init(){}
}
```

## send - Invoking APIs

In addition to being able to invoke ServiceStack APIs natively in each supported language, they can also be invoked with just a single command-line.

Running `x send` will display different example usage of this versatile tool which supports most of 
[ServiceStack's Authentication options](/auth/authentication-and-authorization):

```
Usage: x <send|GET|POST|PUT|DELETE|PATCH> <base-url> <request>
       x <send|GET|POST|PUT|DELETE|PATCH> <base-url> <request> {js-object}
       x <send|GET|POST|PUT|DELETE|PATCH> <base-url> <request> < body.json

Options:
 -raw                   Show raw HTTP Headers and Body
 -json                  Show Body as JSON
 -token <token>         Use JWT or API Key Bearer Token
 -basic <user:pass>     Use HTTP Basic Auth
 -authsecret <secret>   Use Admin Auth Secret
 -ss-id <session-id>    Use ss-id Session Id Cookie
 -cookies <file>        Store and Load Cookies from file
```

HTTP APIs can be invoked with a specific HTTP Verb or **send** which will use the APIs preferred HTTP Method when it can be inferred e.g. Request DTO is annotated with `IVerb` interface marker or its implementation uses a HTTP Verb method name instead of `Any()`.

### UI for generating post commands

Whilst the syntax for invoking APIs from the command line should be fairly intuitive, you may benefit from using the UI in [apps.servicestack.net](https://apps.servicestack.net) to craft the initial API call that can be copied by clicking the copy icon from **Invoke API from command line** command:

[![](./img/pages/apps/post-command-ui.png)](https://apps.servicestack.net/#techstacks.io/csharp/AutoQuery/FindTechnologies(Ids:[1,2,3],VendorName:Google,Take:5,Fields:%22Id,%20Name,%20VendorName,%20Slug,%20Tier,%20FavCount,%20ViewCount%22))

This is quick way for using a UI to bootstrap the initial post command that you can continue iterating on and invoking locally.

::: info
[apps.servicestack.net](https://apps.servicestack.net) requires your remote ServiceStack App is accessible from the Internet
:::

### Invoking APIs without arguments

APIs that don't require arguments can be invoked with just their names, e.g. we can invoke the [GetLocations](https://covid-vac-watch.netcore.io/json/metadata?op=GetLocations)
Covid 19 Vaccine Watch API with either:

```bash
x send https://covid-vac-watch.netcore.io GetLocations
x GET https://covid-vac-watch.netcore.io GetLocations
```

Output:

```
locations:
  Alabama
  Alaska
  American Samoa
  Arizona
  Arkansas
  Bureau of Prisons
  California
  Colorado
  Connecticut
  Delaware
  Dept of Defense
  District of Columbia
  Federated States of Micronesia
  Florida
  Georgia
  ...
```

By default APIs return a human friendly text output optimal for reading at a glance. 

### json Response output

Alternatively use `-json` if you're only interested in viewing the JSON response, e.g:

:::sh
x send https://covid-vac-watch.netcore.io GetLocations -json
:::

Output:

```json
{"locations":["Alabama","Alaska","American Samoa","Arizona","Arkansas","Bureau of Prisons","California","Colorado","Connecticut","Delaware","Dept of Defense","District of Columbia","Federated States of Micronesia","Florida","Georgia","Guam","Hawaii","Idaho","Illinois","Indian Health Svc","Indiana","Iowa","Kansas","Kentucky","Long Term Care","Louisiana","Maine","Marshall Islands","Maryland","Massachusetts","Michigan","Minnesota","Mississippi","Missouri","Montana","Nebraska","Nevada","New Hampshire","New Jersey","New Mexico","New York State","North Carolina","North Dakota","Northern Mariana Islands","Ohio","Oklahoma","Oregon","Pennsylvania","Puerto Rico","Republic of Palau","Rhode Island","South Carolina","South Dakota","Tennessee","Texas","United States","Utah","Vermont","Veterans Health","Virgin Islands","Virginia","Washington","West Virginia","Wisconsin","Wyoming"]}
```

This is useful if you want to capture the results in a `.json` text file for inspection with other JSON aware tools:

:::sh
x send https://covid-vac-watch.netcore.io GetLocations -json > results.json
:::

[jq](https://stedolan.github.io/jq/) is a popular command-line tool for querying JSON outputs that's useful for inspecting the JSON response of one command to chain using it in others. A useful usecase is for parse an `AuthenticateResponse` to capture the JWT `bearerToken` property with `jq -r .bearerToken`:

```bash
TOKEN=$(x send https://test.servicestack.net Authenticate "{provider:'credentials',username:'admin',password:'test'}" -json | jq -r .bearerToken)
```

Then using it to make stateless Authenticated requests, e.g:

:::sh
x send -token $TOKEN https://test.servicestack.net HelloSecure "{name:'World'}"
:::

Output:

```
result:  Hello, World!
```

### raw HTTP output

If preferred you can instead view the full HTTP Response including HTTP Headers by adding the `-raw` flag, e.g:

:::sh
x send https://covid-vac-watch.netcore.io GetLocations -raw
:::

Output:

```
GET /json/reply/GetLocations HTTP/1.1
Host: covid-vac-watch.netcore.io
Accept: application/json

HTTP/1.1 200 OK
Server: nginx/1.19.3
Date: Wed, 28 Jul 2021 07:39:34 GMT
Transfer-Encoding: chunked
Connection: keep-alive
Vary: Accept
X-Powered-By: ServiceStack/5.111 NetCore/Linux
Strict-Transport-Security: max-age=31536000
Content-Type: application/json; charset=utf-8

{"locations":["Alabama","Alaska","American Samoa","Arizona","Arkansas","Bureau of Prisons","California","Colorado","Connecticut","Delaware","Dept of Defense","District of Columbia","Federated States of Micronesia","Florida","Georgia","Guam","Hawaii","Idaho","Illinois","Indian Health Svc","Indiana","Iowa","Kansas","Kentucky","Long Term Care","Louisiana","Maine","Marshall Islands","Maryland","Massachusetts","Michigan","Minnesota","Mississippi","Missouri","Montana","Nebraska","Nevada","New Hampshire","New Jersey","New Mexico","New York State","North Carolina","North Dakota","Northern Mariana Islands","Ohio","Oklahoma","Oregon","Pennsylvania","Puerto Rico","Republic of Palau","Rhode Island","South Carolina","South Dakota","Tennessee","Texas","United States","Utah","Vermont","Veterans Health","Virgin Islands","Virginia","Washington","West Virginia","Wisconsin","Wyoming"]}
```

### Using Rider HTTP Scratch Tools

A productive way to further re-iterate on the HTTP Request is to copy+paste the HTTP Request Header into JetBrains Rider’s HTTP Rest tool where you can run it and customize it using their text editor UI by going to **New Scratch File** and selecting **HTTP Request** or via `Tools > HTTP Client > Create Request in HTTP Client`:

![](./img/pages/apps/post-command-httpscratch-GetLocations.png)

### Invoking APIs with Arguments

To invoke an API with arguments we can use a JavaScript Object Literal which allows a wrist-friendly syntax for invoking any API including rich [AutoQuery APIs](https://servicestack.net/autoquery) which thanks to its human friendly output allows quickly inferring Query result-sets from a glance, e.g:

#### Quote Arguments in Unix Shells

Since JavaScript operators have special meaning in Unix shells you'd need to wrap the object literal in double quotes to have the shell pass it verbatim to the command tool without evaluating it, e.g:

Windows / Linux / macOS:

:::sh
x send https://techstacks.io FindTechnologies "{Ids:[1,2,6],VendorName:'Google',Take:1}"
:::

Windows Only:

:::sh
x send https://techstacks.io FindTechnologies {Ids:[1,2,6],VendorName:'Google',Take:1}
:::

So requests that doesn't use any special batch characters can be sent with or without quotes. An alternative way to by pass the shell is to redirect a JSON Request body instead, e.g:

:::sh
x send https://techstacks.io FindTechnologies < FindTechnologies.json
:::

#### Last 5 Recorded Dates of Vaccinated people in Alaska

```bash
x send https://covid-vac-watch.netcore.io QueryVaccinationRates "{Location:'Alaska',orderBy:'-date',take:5,Fields:'id,date,peopleVaccinated',include:'total'}"
```

Output:

```
offset:   0
total:    195

results:
| # | id    | date                        | peopleVaccinated |
|---|-------|-----------------------------|------------------|
| 1 | 12308 | 2021-07-25T00:00:00.0000000 |           372940 |
| 2 | 12307 | 2021-07-24T00:00:00.0000000 |           372902 |
| 3 | 12306 | 2021-07-23T00:00:00.0000000 |           372132 |
| 4 | 12305 | 2021-07-22T00:00:00.0000000 |           371514 |
| 5 | 12304 | 2021-07-21T00:00:00.0000000 |           371062 |
```

#### Multi conditional TechStacks query

```bash
x send https://techstacks.io FindTechnologies "{Ids:[1,2,6],VendorName:'Google',Take:10,Fields:'Id,Name,VendorName,Tier,FavCount,ViewCount'}"
```

Output:

```
offset:   0
total:    18

results:
| #  | id | name                   | vendorName   | tier                   | viewCount | favCount |
|----|----|------------------------|--------------|------------------------|-----------|----------|
| 1  |  1 | ServiceStack           | ServiceStack | Server                 |      4204 |        5 |
| 2  |  2 | PostgreSQL             | PostgreSQL   | Data                   |      2291 |        4 |
| 3  |  6 | AWS RDS                | Amazon       | Data                   |       625 |        1 |
| 4  |  7 | AngularJS              | Google       | Client                 |      5012 |        1 |
| 5  | 13 | Google Closure Library | Google       | Client                 |       390 |        1 |
| 6  | 15 | Dart                   | Google       | ProgrammingLanguage    |       320 |        2 |
| 7  | 18 | Go                     | Google       | ProgrammingLanguage    |      3865 |        2 |
| 8  | 57 | LevelDB                | Google       | Data                   |       325 |        1 |
| 9  | 61 | Firebase               | Google       | Data                   |       722 |        1 |
| 10 | 72 | Google Cloud Platform  | Google       | HardwareInfrastructure |       269 |        1 |
```

### Invoking Complex APIs

As ServiceStack APIs supports [nested complex types in query strings](/routing#populating-complex-type-properties-on-querystring) the JS Object Request body will be able to scale to execute even deeply complicated API requests in both HTTP Methods without Request Bodies, e.g:

#### Example GET Request

```bash
x GET https://test.servicestack.net StoreLogs "{Loggers:[{Id:786,Devices:[{Id:5955,Type:'Panel',TimeStamp:1,Channels:[{Name:'Temperature',Value:'58'},{Name:'Status',Value:'On'}]}]}]}" -raw
```

Where they're sent on the query string:

```
GET /json/reply/StoreLogs?Loggers=%5b%7bId%3a786,Devices%3a%5b%7bId%3a5955,Type%3aPanel,TimeStamp%3a1,Channels%3a%5b%7bName%3aTemperature,Value%3a58%7d,%7bName%3aStatus,Value%3aOn%7d%5d%7d%5d%7d%5d HTTP/1.1
Host: test.servicestack.net
Accept: application/json

HTTP/1.1 200 OK
Server: nginx/1.18.0, (Ubuntu)
Date: Wed, 28 Jul 2021 07:40:26 GMT
Transfer-Encoding: chunked
Connection: keep-alive
Set-Cookie: ss-id=nt6W8DDHatjwf0kToEUa; path=/; samesite=strict; httponly, ss-pid=GsP8tmccacQn0fH8vOAD; expires=Sun, 28 Jul 2041 07:40:26 GMT; path=/; samesite=strict; httponly
Vary: Accept
Access-Control-Allow-Credentials: true
Access-Control-Allow-Headers: Content-Type, Allow, Authorization, X-Args
Access-Control-Allow-Methods: GET, POST, PUT, DELETE, PATCH, OPTIONS, HEAD
X-Powered-By: ServiceStack/5.111 NetCore/Linux
Content-Type: application/json; charset=utf-8

{"existingLogs":[{"id":786,"devices":[{"id":5955,"type":"Panel","timeStamp":1,"channels":[{"name":"Temperature","value":"58"},{"name":"Status","value":"On"}]}]}]}
```

#### Example POST Request

As well as HTTP Requests with Request bodies where only the method used needs to change whilst the Request JS Object literal stays exactly the same, e.g:

```bash
x POST https://test.servicestack.net StoreLogs "{Loggers:[{Id:786,Devices:[{Id:5955,Type:'Panel',TimeStamp:1,Channels:[{Name:'Temperature',Value:'58'},{Name:'Status',Value:'On'}]}]}]}" -raw
```

Where instead of being sent on the query string it's posted inside a JSON Request body, irrespective of how its sent a ServiceStack API supporting any HTTP Method by being implemented with the `Any()` method name will result in an identical response:

```
POST /json/reply/StoreLogs HTTP/1.1
Host: test.servicestack.net
Accept: application/json
Content-Type: application/json
Content-Length: 157

{"Loggers":[{"Id":786,"Devices":[{"Id":5955,"Type":"Panel","TimeStamp":1,"Channels":[{"Name":"Temperature","Value":"58"},{"Name":"Status","Value":"On"}]}]}]}

HTTP/1.1 200 OK
Server: nginx/1.18.0, (Ubuntu)
Date: Wed, 28 Jul 2021 07:40:54 GMT
Transfer-Encoding: chunked
Connection: keep-alive
Set-Cookie: ss-id=X1BmXXrr9vr5DIpAoxFM; path=/; samesite=strict; httponly, ss-pid=J8kDBiJ37WEOnywRdGMS; expires=Sun, 28 Jul 2041 07:40:54 GMT; path=/; samesite=strict; httponly
Vary: Accept
Access-Control-Allow-Credentials: true
Access-Control-Allow-Headers: Content-Type, Allow, Authorization, X-Args
Access-Control-Allow-Methods: GET, POST, PUT, DELETE, PATCH, OPTIONS, HEAD
X-Powered-By: ServiceStack/5.111 NetCore/Linux
Content-Type: application/json; charset=utf-8

{"existingLogs":[{"id":786,"devices":[{"id":5955,"type":"Panel","timeStamp":1,"channels":[{"name":"Temperature","value":"58"},{"name":"Status","value":"On"}]}]}]}
```

#### Redirected Input Example 

For requests that get significantly large it may be more convenient to maintain the request body in a separate file that you can pipe into the command instead, e.g:

:::sh
x send https://test.servicestack.net StoreLogs -raw < StoreLogs.json
:::

Output:
```
POST /json/reply/StoreLogs HTTP/1.1
Host: test.servicestack.net
Accept: application/json
Content-Type: application/json
Content-Length: 157

{"Loggers":[{"Id":786,"Devices":[{"Id":5955,"Type":"Panel","TimeStamp":1,"Channels":[{"Name":"Temperature","Value":"58"},{"Name":"Status","Value":"On"}]}]}]}

HTTP/1.1 200 OK
Server: nginx/1.18.0, (Ubuntu)
Date: Wed, 28 Jul 2021 07:41:38 GMT
Transfer-Encoding: chunked
Connection: keep-alive
Set-Cookie: ss-id=kScY3mYF06e3iuPaCnaD; path=/; samesite=strict; httponly, ss-pid=hpbimtl9dIWA1IbJPMXN; expires=Sun, 28 Jul 2041 07:41:38 GMT; path=/; samesite=strict; httponly
Vary: Accept
Access-Control-Allow-Credentials: true
Access-Control-Allow-Headers: Content-Type, Allow, Authorization, X-Args
Access-Control-Allow-Methods: GET, POST, PUT, DELETE, PATCH, OPTIONS, HEAD
X-Powered-By: ServiceStack/5.111 NetCore/Linux
Content-Type: application/json; charset=utf-8

{"existingLogs":[{"id":786,"devices":[{"id":5955,"type":"Panel","timeStamp":1,"channels":[{"name":"Temperature","value":"58"},{"name":"Status","value":"On"}]}]}]}
```

Remove the `-raw` option to display the response in a more human-friendly readable format:

:::sh
x send https://test.servicestack.net StoreLogs < StoreLogs.json
:::

Output:
```
[existingLogs]
id:       786

[devices]
id:         5955
type:       Panel
timeStamp:  1

channels:
| # | name        | value |
|---|-------------|-------|
| 1 | Temperature | 58    |
| 2 | Status      | On    |
```

## Authentication

To support making Authenticated Requests most of ServiceStack's built-in Authentication Options are supported from the options below:

```
Options:
 -token <token>         Use JWT or API Key Bearer Token
 -basic <user:pass>     Use HTTP Basic Auth
 -authsecret <secret>   Use Admin Auth Secret
 -ss-id <session-id>    Use ss-id Session Id Cookie
 -cookies <file>        Store and Load Cookies from file
```

Since Username/Password Credentials Auth is a normal ServiceStack API we can invoke it like normal, e.g:

:::sh
x send https://test.servicestack.net Authenticate "{provider:'credentials',username:'admin',password:'test'}"
:::

However to hide your credentials from command history logs you'll likely want to maintain your credentials in a separate file, e.g:

:::sh
x send https://test.servicestack.net Authenticate < auth.json
:::

Which if successful will return a populated human-friendly `AuthenticateResponse`:

```
userId:          2
sessionId:       QfJLhmd8XQxeuAIqvoCY
userName:        admin
displayName:     admin DisplayName
bearerToken:     eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiIsImtpZCI6IjNuLyJ9.eyJzdWIiOjIsImlhdCI6MTYyNzM4MjY5NiwiZXhwIjoxNjI4NTkyMjk2LCJlbWFpbCI6ImFkbWluQGdtYWlsLmNvbSIsImdpdmVuX25hbWUiOiJGaXJzdCBhZG1pbiIsImZhbWlseV9uYW1lIjoiTGFzdCBhZG1pbiIsIm5hbWUiOiJhZG1pbiBEaXNwbGF5TmFtZSIsInByZWZlcnJlZF91c2VybmFtZSI6ImFkbWluIiwicm9sZXMiOlsiQWRtaW4iXSwianRpIjozfQ.j80f1KYsNRDhygO817NSaqYg7DIR1ptLZQUB1mZd_R8
refreshToken:    eyJ0eXAiOiJKV1RSIiwiYWxnIjoiSFMyNTYiLCJraWQiOiIzbi8ifQ.eyJzdWIiOjIsImlhdCI6MTYyNzM4MjY5NiwiZXhwIjoxNjU4OTE4Njk2LCJqdGkiOi0zfQ.nkwDYvmB5_QHm6hmVv8Thfl2Iz8W_LUDf6bspb-Nu2c
profileUrl:      data:image/svg+xml,%3Csvg width='100' height='100' viewBox='0 0 100 100' xmlns='http://www.w3.org/2000/svg'%3E %3Cstyle%3E .path%7B%7D %3C/style%3E %3Cg id='male-svg'%3E%3Cpath fill='%23556080' d='M1 92.84V84.14C1 84.14 2.38 78.81 8.81 77.16C8.81 77.16 19.16 73.37 27.26 69.85C31.46 68.02 32.36 66.93 36.59 65.06C36.59 65.06 37.03 62.9 36.87 61.6H40.18C40.18 61.6 40.93 62.05 40.18 56.94C40.18 56.94 35.63 55.78 35.45 47.66C35.45 47.66 32.41 48.68 32.22 43.76C32.1 40.42 29.52 37.52 33.23 35.12L31.35 30.02C31.35 30.02 28.08 9.51 38.95 12.54C34.36 7.06 64.93 1.59 66.91 18.96C66.91 18.96 68.33 28.35 66.91 34.77C66.91 34.77 71.38 34.25 68.39 42.84C68.39 42.84 66.75 49.01 64.23 47.62C64.23 47.62 64.65 55.43 60.68 56.76C60.68 56.76 60.96 60.92 60.96 61.2L64.74 61.76C64.74 61.76 64.17 65.16 64.84 65.54C64.84 65.54 69.32 68.61 74.66 69.98C84.96 72.62 97.96 77.16 97.96 81.13C97.96 81.13 99 86.42 99 92.85L1 92.84Z'/%3E%3C/g%3E%3C/svg%3E

[roles]
Admin
```

### Authentication -cookies

Likely the easiest and most versatile authentication option would be to use a separate cookies file where it will load and save cookies after each request allowing each request to be made within the context of the same authenticated session as done in browsers, e.g:

:::sh
x send -cookies cookies.xml https://test.servicestack.net Authenticate < auth.json
:::

We can test that it's working by first trying to call an Authentication protected Service without any Authentication options, e.g:

:::sh
x send https://test.servicestack.net HelloSecure "{name:'World'}"
:::

Output:

```
The remote server returned an error: (401) Not Authenticated.
```

Then re-trying the request, providing the **cookies.xml** that was populated after the success Authentication:

:::sh
x send -cookies cookies.xml https://test.servicestack.net HelloSecure "{name:'World'}"
:::

Output:

```
result:  Hello, World!
```

The `-cookies` Authentication option is the most versatile as it supports standard [Server Sessions](/auth/sessions) as well as stateless Authentication options like [JWT Auth configured with Token Cookies](/auth/jwt-authprovider#enable-server-cookies) where the JWT Bearer Token is maintained in a cookie.

### Authentication -token

The `-token` Authentication option should be used when authenticating with Bearer Tokens like [JWT](/auth/jwt-authprovider) or [API Key](/auth/api-key-authprovider) Auth Providers. 
When the `JwtAuthProvider` is configured a successful Authentication Response will return a populated **bearerToken** which we can use to authenticate with instead. As Bearer Tokens can become quite verbose you may want to choose to save in a shell environment variable instead, e.g:

**Windows:**

```bash
set TOKEN=...
x send -token %TOKEN% https://test.servicestack.net HelloSecure {name:'World'}
```

**Linux / macOS:**

```bash
TOKEN=...
x send -token $TOKEN https://test.servicestack.net HelloSecure "{name:'World'}"
```

Output:

```
result:  Hello, World!
```

### Capturing bearerToken with `#Script` expression

A dependency-free solution for capturing the `bearerToken` is to utilize the [#Script](https://sharpscript.net) eval expression support in `x` to make an API Request and parsing the JSON response and parsing it with #Script methods, e.g:

```bash
TOKEN=$(x -e "'https://test.servicestack.net/auth' |> urlTextContents({method:'POST',accept:'application/json',data:'provider=credentials&username=admin&password=test'}) |> parseJson |> get('bearerToken')")
```

Then using it to make stateless Authenticated requests, e.g:

:::sh
x send -token $TOKEN https://test.servicestack.net HelloSecure "{name:'World'}"
:::

### Capturing bearerToken with jq

[jq](https://stedolan.github.io/jq/) is a versatile command for extracting info from JSON outputs which can extract the raw string "bearerToken" property value of an `AuthenticateResponse` with `jq -r .bearerToken`, e.g:

```bash
TOKEN=$(x send https://test.servicestack.net Authenticate "{provider:'credentials',username:'admin',password:'test'}" -json | jq -r .bearerToken)
```

### Inspect JWTs

When working with JWTs it can be useful to quickly inspect its contents which we can do with `inspect-jwt`:

```
Usage: x inspect-jwt <jwt>
       x inspect-jwt < file.txt
```

Which we can use with the populated **bearerToken** above to inspect the contents of the JWT in a human-friendly format, e.g:

    $ x inspect-jwt eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiIsImtpZCI6IjNuLyJ9.eyJzdWIiOjIsImlhdCI6MTYyNjg0OTEzMCwiZXhwIjoxNjI4MDU4NzMwLCJlbWFpbCI6ImFkbWluQGdtYWlsLmNvbSIsImdpdmVuX25hbWUiOiJGaXJzdCBhZG1pbiIsImZhbWlseV9uYW1lIjoiTGFzdCBhZG1pbiIsIm5hbWUiOiJhZG1pbiBEaXNwbGF5TmFtZSIsInByZWZlcnJlZF91c2VybmFtZSI6ImFkbWluIiwicm9sZXMiOlsiQWRtaW4iXSwianRpIjo5fQ.uLp_QkmBo6J6TlXiUPl0Iq6TkTbF0xzncbUI1HmDro4

Output:

```
[JWT Header]
typ:  JWT
alg:  HS256
kid:  3n/


[JWT Payload]
sub:                 2
iat:                 1626849130 (Wed, 21 Jul 2021 06:32:10 GMT)
exp:                 1628058730 (Wed, 04 Aug 2021 06:32:10 GMT)
email:               admin@gmail.com
given_name:          First admin
family_name:         Last admin
name:                admin DisplayName
preferred_username:  admin

[roles]
Admin

jti:                 9
```

### Authentication -basic

When the `BasicAuthProvider` is configured we can authenticate with HTTP Basic Auth using the `-basic` command line option which supports both clear text:

:::sh
x send -basic admin:test https://test.servicestack.net HelloSecure "{name:'World'}"
:::

Output:

:::sh
x send -basic admin:test https://test.servicestack.net HelloSecure "{name:'World'}"
:::

As well as Base64 encoded credentials which we can convert using the `x base64` tool, e.g:

:::sh
x base64 admin:test
:::

Output:

```
YWRtaW46dGVzdA==
```

:::sh
x send -basic YWRtaW46dGVzdA== https://test.servicestack.net HelloSecure "{name:'World'}"
:::

Output:

```
result:  Hello, World!
```

Although a Base64 encoded password does not offer much protection for your password (e.g. it can be decoded with `x unbase64 YWRtaW46dGVzdA==`), to avoid your password from being captured in shell command history we can instead read it from a plain text file, e.g:

```bash
set /P basic=<credentials.txt
x send -basic %basic% https://test.servicestack.net HelloSecure "{name:'World'}"
```

Output:

```
result:  Hello, World!
```

### Authentication -authsecret

If the remote ServiceStack App is [configured with an Admin Auth Secret](/debugging#authsecret), i.e:

```csharp
SetConfig(new HostConfig { AdminAuthSecret = "secretz" });
```

It can be used to authenticated with using the `-authsecret` option:

:::sh
x send -authsecret secretz https://test.servicestack.net HelloSecure "{name:'World'}"
:::

Output:

```
result:  Hello, World!
```

### Authentication -ss-id

When the remote ServiceStack App is configured to use Server Sessions you can impersonate a pre-authenticated Users Session using the `-ss-id` Authentication option which is useful for impersonating an existing Users Session by copying their `ss-id` or `ss-pid` Cookie which you can find in Web Inspector's **Application** page:

![](./img/pages/auth/webinspector-cookies.png)

If Users were authenticated with **Remember Me** checked their Session will be stored against the `ss-pid` Cookie otherwise it will use the `ss-id` Session Cookie.

Making a `GET` request to the `Authenticate` API is another way you can test which user you're authenticated as, e.g:

:::sh
x GET -ss-id FoCHJK9Apl9mrcaq3ceE https://blazor-vue.web-templates.io Authenticate
:::

Output:

```
userId:          1
sessionId:       FoCHJK9Apl9mrcaq3ceE
userName:        admin@email.com
displayName:     Admin User
profileUrl:      data:image/svg+xml,%3Csvg width='100' height='100' viewBox='0 0 100 100' xmlns='http://www.w3.org/2000/svg'%3E %3Cstyle%3E .path%7B%7D %3C/style%3E %3Cg id='male-svg'%3E%3Cpath fill='%23556080' d='M1 92.84V84.14C1 84.14 2.38 78.81 8.81 77.16C8.81 77.16 19.16 73.37 27.26 69.85C31.46 68.02 32.36 66.93 36.59 65.06C36.59 65.06 37.03 62.9 36.87 61.6H40.18C40.18 61.6 40.93 62.05 40.18 56.94C40.18 56.94 35.63 55.78 35.45 47.66C35.45 47.66 32.41 48.68 32.22 43.76C32.1 40.42 29.52 37.52 33.23 35.12L31.35 30.02C31.35 30.02 28.08 9.51 38.95 12.54C34.36 7.06 64.93 1.59 66.91 18.96C66.91 18.96 68.33 28.35 66.91 34.77C66.91 34.77 71.38 34.25 68.39 42.84C68.39 42.84 66.75 49.01 64.23 47.62C64.23 47.62 64.65 55.43 60.68 56.76C60.68 56.76 60.96 60.92 60.96 61.2L64.74 61.76C64.74 61.76 64.17 65.16 64.84 65.54C64.84 65.54 69.32 68.61 74.66 69.98C84.96 72.62 97.96 77.16 97.96 81.13C97.96 81.13 99 86.42 99 92.85L1 92.84Z'/%3E%3C/g%3E%3C/svg%3E

[roles]
Admin
```


# What is a Message-based WebService
Source: https://docs.servicestack.net/what-is-a-message-based-web-service

Answer from [ServiceStack's interview on InfoQ](http://www.infoq.com/articles/interview-servicestack-2):

In essence, a message-based service is one that passes messages to facilitate its communication. A good metaphor for illustrating the differences between a RPC method and a message-based API can be seen in Smalltalk or [Objective-C's message dispatch mechanism](http://stackoverflow.com/a/982356/85785) vs a normal static C method call. Method invocations are coupled to instance they are invoked on, in a message-based system the request is captured in the message and sent to a receiver. The receiver doesn't have to handle the message as it can optionally delegate the request to an alternative receiver to process instead. 

### Message-based design in ServiceStack

Message-based design is enabled in ServiceStack by capturing the Services Request Query into a Request DTO that's completely de-coupled from any one implementation. You can think of making a ServiceStack request as a Smalltalk runtime method dispatch at a Macro scale, where the ServiceStack host is the Receiver, the HTTP Verb is the selector and Request DTO is the message. 

It doesn't matter on which of the endpoints the Request is sent to as the request can be populated with any combination of PathInfo, QueryString and Request Body. After the Request binding, the request travels through all user-defined filters and pre-processors for inspection where it can optionally be handled before it is able to reach the service implementation. Once the request reaches the service it invokes the best matching selector, by default it will look for a method with the same name as a HTTP Verb, if it doesn't exist it falls back to using a catch-all 'Any' method that can be used to handle the request on any endpoint or route in any format. Even when inside the Service implementation it is able to further delegate the request to an alternative service or easily proxy the request to a remote sharded instance if it needs to. 

Conceptually in ServiceStack you're just sending a message to a ServiceStack instance, the client is not concerned with what ultimately handles it, only that a response is returned for reply requests or that the request is successfully accepted for oneway messages. In a RPC API you're conceptually invoking a remote method which has the request tightly coupled to its remote implementation method signature.

### Benefits of adopting a Message-based design

There are [many natural benefits gained when adopting a message-based design](/advantages-of-message-based-web-services) they offer better resilience, flexibility, versionability than their RPC cousins. An example of one of the benefits possible is when you send a request to its one-way endpoint, if the ServiceStack instance has a MQ Host configured, the request is automatically deferred to the configured MQ Broker and processed in the background. So even if the ServiceStack Host goes down none of the pending messages are lost and are automatically processed the next time the Host starts up. This is the type of behavior that is enabled for free in ServiceStack. When no MQ host is enabled the request is just processed normally, i.e. synchronously by a HTTP web worker.

Most of the benefits of message-based designs are gained over time as you're developing and evolving your existing services and adding support for more clients. **One immediate benefit is being able to provide an end-to-end typed API without the use of code-gen**. This is impossible to achieve without a message-based design which ensures the essence of your Service Contract is captured in re-usable DTOs. Being able to share your server DTOs you defined your web services with on the client completely by-pass the normal development workflow required in re-generating your clients proxies from your services interim WSDL/XSD schemas.

### Typed, Native SDK's provide maximum end-user value

Typed clients are the under-pinnings for **Native SDK's which provide the most value to end-users of your service** as they reduce the most of the burden required in order to consume your API. This approach is popular for companies that really, really want you to use their APIs, i.e. where their businesses success depends on its popular use. This is the preferred approach taken by Amazon EC2, Google App Engine, Azure, Facebook, Ebay, Stripe, Braintree, etc.

More importantly, message-based designs encourage the design of coarse-grained and more re-usable services. By contrast RPC method signatures are generally designed to serve a single-purpose, i.e. Rather than adding more RPC methods for every client requirement (which introduces a new external endpoint each time), message-based designs instead encourages enhancing existing services with extra functionality since they can be added without friction. This additionally has the benefit of providing instant utility to existing clients already consuming existing services, since they can easily access the extra features without introducing a new code-path to call a new external endpoint.

### Ideal for SOA

This is an especially important approach to take whenever implementing service-intensive systems like SOA platforms, as services routinely end up out-living and serving more clients that the original client that consume them, so it's important not to have your service APIs driven by adhoc client-specific requirements. It's more useful to think about designing APIs from the system's perspective with the goal of exposing the underlying systems capabilities in a generically re-usable API. This is the main reason why I now only ever adopt message-based designs for all my services endpoints as Coarse-grained APIs naturally encourage the design of more re-usable and feature-rich APIs.

## Adopted by most leading distributed frameworks

Benefits of message-based designs are already well-known to developers of leading distributed frameworks who have adopted message-based designs in leading platforms, e.g: Google's Protocol Buffers, Amazon's Web Services platform, Erlang processes, F# mailboxes, Scala's Actors, Go's Channels, Dart's Isolates and Clojure's agents, etc.

### Message-based Services in ServiceStack

![](/img/pages/messaging/example-servicestack-csharp.png)

### Message-based Services in AWS

![](/img/pages/messaging/example-simpledb-csharp.png)

### Concurrency in F# - Erlang Style Message Passing  

![](/img/pages/messaging/example-fsharp.png)

### Google Protobuf Messages

![](/img/pages/messaging/example-google-protobuf.png)

### Scala Actors

![](/img/pages/messaging/example-scala-actors.png)

### Go Channels

![](/img/pages/messaging/example-go-channels.png)


# Advantages of message-based WebServices
Source: https://docs.servicestack.net/advantages-of-message-based-web-services

### This is in response to a recent question from [mailing group](https://groups.google.com/forum/?fromgroups#!topic/servicestack/qkV5fzdnzt8):

> It seems like ServiceStack is designed for use primarily in a greenfield 
SOA implementation where the technology environment is quite homogeneous, 
and more or less the same people have ownership of the servers and all the clients.  
Is that correct?

ServiceStack's message-based design is optimal for the design of **any remote service**. We believe .NET has never gotten web services right, which was the inspiration for starting ServiceStack. If .NET was lucky enough to have had someone like Martin Fowler (or just someone following his decade-old guidance) at the helm of the Microsoft Patterns & Practices and VS.NET tools teams from the start we would've likely been able to avoid the multiple replacement web service frameworks from Microsoft that .NET web service developers have endured over the years - and still haven't got right. This is unfortunate considering remote services are the most important APIs developers can create as they ultimately offer the highest-level of software re-use possible whilst remaining programmatically composable.

## Best-practices for remote services

Inspiration should've ideally been taken from Martin Fowler or from companies that have [SOA](http://en.wikipedia.org/wiki/Service-oriented_architecture) ingrained in their DNA who have successfully run long-term evolving SOA solutions that have enabled rich and complex platforms.
Amazon is a shining example of this, where even Steve Yegge admits [it's the only thing they do better than Google](https://gigaom.com/2011/10/12/419-the-biggest-thing-amazon-got-right-the-platform/). Where their relentless dedication to exposing SOA services over all their systems have enabled their industry leading EC2 and [aws.amazon.com](http://aws.amazon.com/) cloud services.

## The Service API of Amazon's Web Services

If you look at an [example of Amazons EC2 Web Service APIs](http://docs.amazonwebservices.com/AWSEC2/latest/APIReference/ApiReference-query-AttachVolume.html) you'll see a strong similarity with ServiceStack's approach where they accept a Request message and return a response message for all their services, e.g:

### Example Request

```
https://ec2.amazonaws.com/?Action=AttachVolume
&VolumeId=vol-4d826724
&InstanceId=i-6058a509
&Device=/dev/sdh
&AUTHPARAMS
```
 
### Example Response

```xml
<AttachVolumeResponse xmlns="http://ec2.amazonaws.com/doc/2012-06-01/">
    <requestId>59dbff89-35bd-4eac-99ed-be587EXAMPLE</requestId>
    <volumeId>vol-4d826724</volumeId>
    <instanceId>i-6058a509</instanceId>
    <device>/dev/sdh</device>
    <status>attaching</status>
    <attachTime>2008-05-07T11:51:50.000Z</attachTime>
</AttachVolumeResponse>
```

From this we can attest Amazon maintains a Request [DTO](http://en.wikipedia.org/wiki/Data_Transfer_Object) named `AttachVolume` and a Response DTO named `AttachVolumeResponse`. This is the same design ServiceStack encourages and with some minor customisations the Request can be easily made to be more REST-ful with:

```
POST https://ec2.amazonaws.com/volumes/vol-4d826724/attach 
FormData: InstanceId=i-6058a509&Device=/dev/sdh&AUTHPARAMS
```

In-terms of accessibility and interoperability, ServiceStack 1-ups Amazon here since the same Request DTO can be populated with any combination of a [Custom Route, QueryString, FormData or a POST'ed XML, JSON, JSV, SOAP 1.1/1.2 or ProtoBuf Request DTO payload](/architecture-overview). Although this is really inconsequential since both Amazon and ServiceStack also provide **typed service clients** so you're never required to manually construct the request by hand. 

## Messaging at Google

Although Amazon holds the SOA edge, Google, like Amazon also benefits from message-based design for nearly all their internal communications using their own Data Interchange Format - [Protocol Buffers](http://code.google.com/p/protobuf/), which like JSON is both fast, compact and tolerant:

::: info
Protocol Buffers are a way of encoding structured data in an efficient yet extensible format. Google uses Protocol Buffers for almost all of its internal RPC protocols and file formats
:::

A simple DSL is used to define their Protocol Buffer message DTOs:

```js
message Person {
    required int32 id = 1;
    required string name = 2;
    optional string email = 3;
}
```

From this they use their `protoc` command-line utility to generate native types in C++, Java and Python, which like Amazon and ServiceStack, enables them to benefit from using an end-to-end, typed API. 

> Add a reference to [ServiceStack.ProtoBuf](http://nuget.org/packages/ServiceStack.ProtoBuf)  to enable [@marcgravell's](http://stackoverflow.com/users/23354/marc-gravell) excellent implementation of Protocol Buffers: [protobuf-net](https://github.com/mgravell/protobuf-net).

## A Productivity Win 

We've been building SOA systems like this with ServiceStack for years: the productivity boost you get from using typed, end-to-end, resilient, message-based API is unmatched. An example of this was having developed over 100+ Web Services for the [Redis WebServices](http://redisadminui.servicestack.net/redis/metadata) project in just 1 weekend. Others that have tried ServiceStack also agree its ease-of-development and **"pit of success"** design it promotes ultimately yields a productivity win - this positive sentiment is captured in [@ServiceStack's favorites](https://twitter.com/ServiceStack/likes) and throughout the [mailing group](https://groups.google.com/forum/?fromgroups#!forum/servicestack).

### The anatomy of a ServiceStack service

For normal services, ServiceStack is an invisible library i.e. it lets you implement your service in pure, untainted C# accepting any user-defined Request and lets you return any Response DTO without any regard to endpoints and formats. Any dependencies your services need can be declared as public properties and are automatically auto-wired on each request. A complete example of this is the self-contained [Backbone TODO backend persisted using Redis](https://github.com/ServiceStack/ServiceStack.Examples/blob/master/src/Backbone.Todos/Global.asax.cs).

### [In contrast with SOAP](http://www.infoq.com/articles/interview-servicestack)

By contrast we've witnessed .NET devs struggling to implement much fewer SOAP web services within the same timeframe, especially when they're fighting un-expected and unknown WCF interoperability issues. Not only is SOAP more verbose and slower, its less tolerant and version-able, it was never a good choice for the open web and is now effectively deprecated.

## The many webservice frameworks of Microsoft

Unfortunately despite Microsoft having hosted Martin Fowler's respected [Data Transfer Object](http://msdn.microsoft.com/en-us/library/ff649585.aspx) and [Service Gateway](http://msdn.microsoft.com/en-us/library/ff650101.aspx) patterns on MSDN for years - none of their web frameworks have encouraged their use. Instead in .NET we've been forced to code against the multiple generation of replacement web service frameworks they've churned out over the years like .asmx, CSF, WCF, WCF/REST, WSE, WCF DataServices, RIA, MVC (escaping earlier cruft) and now WebApi. Each of these frameworks share the same mistake of mapping to C# methods, which we believe is a terrible idea for network  services since it promotes chatty and brittle remote interfaces, that fail to facilitate the easy creation of SOA-like Apis. 

Throughout all these generations of frameworks ServiceStack's underlying core message-based design has remained 
a constant powerful primitive that drives much of its simplicity. At a minimum ServiceStack Services just need 
to implement the empty marker interface:

```csharp
public interface IService { }
```

Which lets you handle any HTTP Verb, as well as a 'Catch All' **Any** fall-back to handle any un-specified HTTP verbs, e.g:

```csharp
public class MyService : IService 
{
    public Response Get(Request request)  => ...;
    public Response Post(Request request) => ...;

    //Fallback for Anything else e.g DELETE, PUT, PATCH, OPTIONS, etc.
    public Response Any(Request request)  => ...;
}
```

It simply accepts any user-defined Request DTO and returns any Response DTO - that you're given complete freedom to create. If ever more customization/headers is needed you can return the decorated response inside a `HttpResult` or `HttpError` to maintain full control over the HTTP output.

### Message APIs minimizes round-trips, creates fewer, more re-usable and extensible services

Messages APIs are naturally batchful and promote the development of coarse-grained service interfaces. This encourages fewer, more re-usable services that are better positioned for extensibility - this is a key benefit, since well-defined (i.e. non RPC/client-specific) back-end services tend to out live the UIs and clients that consume them. 

This is illustrated in this example between the [different style of services that WCF and ServiceStack encourages](https://gist.github.com/1386381). Another example showcasing the differences is in many of jQuery's APIs that take in an array of key/value pairs, like [$.ajax()](http://api.jquery.com/jQuery.ajax/). Imagine if every configuration permutation was a different or overloaded method? This gets unwieldy, very quickly. A coarse-grained interface enables richer functionality in a single call, whilst sharing the same well-tested code-path.

### Code-first POCO's

Since it promotes clean, re-usable code, ServiceStack has always encouraged the use of code-first [POCO](http://en.wikipedia.org/wiki/Plain_Old_CLR_Object)'s for just about everything. i.e. the same POCO can be used: 

  - In Request and Response DTO's (on client and server) 
  - In [JSON, JSV and CSV Text Serializers](/formats)
  - As the data model in [OrmLite](https://github.com/ServiceStack/ServiceStack.OrmLite), [db4o](http://code.google.com/p/servicestack/source/browse/#svn%2Ftrunk%2FCommon%2FServiceStack.DataAccess%2FServiceStack.DataAccess.Db4oProvider) and [NHibernate](http://code.google.com/p/servicestack/source/browse/#svn%2Ftrunk%2FCommon%2FServiceStack.DataAccess%2FServiceStack.DataAccess.NHibernateProvider%253Fstate%253Dclosed)
  - As the entities stored in [Redis](https://github.com/ServiceStack/ServiceStack.Redis)
  - As blobs stored in [Caches](/caching) and [Sessions](/auth/sessions)
  - Dropped and executed in [MQ's services](/redis-mq)
  - Dehydrating [complex configurations](http://www.servicestack.net/mvc-powerpack/) into

Leveraging different technologies whose functionality is built around POCO's offer un-precedented levels of re-use, reduces friction, promotes consistent, more usable and easier to rationale code-bases.

## The case against mapping to method signatures

The programmer convenience and familiarity of using method signatures for Service APIs is just not worth what you give up:
 
It encourages developers to treat web services as just another method call even though they're millions of times slower, the different properties between service endpoints and C# methods highlight more of the short comings of this approach where in order to be able to evolve your services without friction, services should be both forward and backwards compatible - not fail-fast. When you evolve and refactor a C# method you have the opportunity to refactor all the call sites to meet the new method signature - whereas in a disconnected (and already deployed) client/server solution you don't, you need to support both old and new clients requests and the only way to do this cleanly whilst still maintaining the same code-path is to pass messages between them. 

But the main disadvantage of method signature service APIs is that they mandate the use of code-gen in order to provide a typed client API. Using messages allows you to re-use generic service clients for all your service communications. This is how, even up to this day ServiceStack remains the only .NET framework to maintain a terse, (both sync and async), typed, end-to-end client libraries without any code-gen, e.g:

```cs
Todo createdTodo = client.Post(new Todo { Content = "New Todo", Order = 1 });
```

### Code-gen'ing service clients is evil

Although a subject of another post we consider code-gen an arthritis that imposes undue friction to a project, it adds un-necessary build steps, increases compile times, forces lock-step deployment of client/server endpoints (usually requiring downtime), inhibits DRY/code re-use amongst code-gen types, has your domain logic binded to external moving types (that are outside of your control), are less resilient since code-gen types parse the entire payload - so unwanted breakages can occur on changes to un-used parts of the request or response.

The only way to maintain a succinct API that maps to method signatures without code-gen is to use dynamic. We're a fan of dynamic languages for most (fuzzy) development tasks like creating/binding UIs, html generation, scripting, etc. But we don't think they're optimal for creating evolving service APIs with - which stand to benefit most from statically typed annotations, compiler warnings and the refactoring support that statically typed languages can provide. 

### Twitter benefitting from Typed Services

After having rewrote their Ruby APIs in Scala, Twitter also comes to the same conclusion:
http://www.infoq.com/articles/twitter-java-use

> I would say about half of the productivity gain is purely because of accumulated technical debt in the search Rails stack. And the other half is that, as search has moved into a Service Oriented Architecture and exposes various APIs, static typing becomes a big convenience in enforcing coherency across all the systems. You can guarantee that your dataflow is more or less going to work, and focus on the functional aspects. Whereas for something like building a web page you don't want to recompile all the time, you don't really want to worry about whether in some edge condition you are going to get a type you didn't expect. But as we move into a light-weight Service Oriented Architecture model, static typing becomes a genuine productivity boon. And Scala gives you the same thing.

## Advantages of Message-based designs

So in contrast to method signatures, message-based designs offer many advantages:

  - They're easy to version and evolve since you're freely able to add/remove functionality and properties without error
  - They're easy to route, chain and decorate through to different handlers and pipelines
  - They're easy to serialize and proxy through to remote services 
  - They're easy to record, defer and replay - evident by ServiceStack's [IMessaging API](/redis-mq) which can automatically drop one-way services into MQ's and have them executed inside an MQ Host, you get this functionality for free since the MQ host can re-use the same web service implementation. It works the other way too where you can supply a Url in the ReplyTo property to have the MQ response POST'ed to a ServiceStack HTTP Service.
  - They're easy to log, evident by ServiceStack's trivially simple but useful [IRequestLogger service](/request-logger)
  - They're easy to map and translate to and from domain models using convention and auto mappers
  - Ideal for concurrency as immutable messages are thread-safe and can be easily multi-plexed with their handlers over multiple threads.

All these properties make messages a better choice for distributed systems, where all this functionality can be achieved with generic solutions since it's much easier to pass around and serialize messages than method signature invocations.

<lite-youtube class="w-full mx-4 my-4" width="560" height="315" videoid="Vae0ALalIP0" style="background-image: url('https://img.youtube.com/vi/Vae0ALalIP0/maxresdefault.jpg')"></lite-youtube>

### Message designs are well known

Although none of these qualities are new, message-based designs have been very well known for decades and are used in many of the most highly respected real-time distributed technologies: including Erlang processes, Java's JMS, Scala's Actors, Go's go-routines, Dart's isolates, F#'s Mailboxes as well as in industrial strength Message Queues which (amongst many other benefits) provide deferred, durable and reliable execution - which are a strong force in most other platforms.

### Messaging practically non-existant in .NET

They're just weak in .NET since Microsoft has an un-naturally strong influence over .NET developer mindshare and have been able to steer mainstream .NET into using SOAP Web Services at the expense of MQ's and message-based solutions. Our guess for this was because they've only had a poor, outdated MQ option in MSMQ and that the 1) right-click 'Add Service Reference' and 2) call a remote service like a c# method, demos very well. 

This could change with the advent of [Azure Service Bus](https://azure.microsoft.com/en-us/services/service-bus/) if Microsoft devotes some attention into pointing mainstream .NET devs towards a messaging approach. Although with the imminent release of WebApi and Microsoft's full marketing force, army of employees and full-time developer advocates behind it, they will likely be once again successful into moving most of mainstream .NET onto yet another replacement web-service framework for all their remote communication needs - when often message-based / SOA designs provide a better fit.

For those interested in discovering advantages of MQ's and message-based designs and their abilities in enabling loosely coupled distributed systems, we recommend the excellent book from Martin Fowler's signature series - [Enterprise Integration Patterns](http://www.eaipatterns.com/).

## So is ServiceStack only suitable for homogeneous environments that control client / server? 

This is fairly inaccurate considering ServiceStack's mission is close to the exact opposite: i.e. to encapsulate and empower your services logic and host them in the most accessible and re-usable ways possible on the most popular endpoints and formats. This is, after all what the core objectives of a service should be, i.e. to expose high-level functionality in the most accessible way and consume them in least-effort possible.

### Excellent built-in support of HTTP on most open and popular formats

Not only do all ServiceStack services accept a Request DTO populated with any combination of Custom Routes, QueryString and HTML FormData. You can also POST the serialized Request DTO in any of the in-built formats: i.e. XML, JSON, JSV, SOAP 1.1/1.2, ProtoBuf (when enabled) or your own [custom format](https://northwind.netcore.io/vcard-format.htm). All services immediately support JSONP and its trivial to [enable CORS on all services](http://stackoverflow.com/questions/8211930/servicestack-rest-api-and-cors). Should you wish, you're also able to have all HTTP Verbs execute the same service. 

Support is included for registering raw custom IHttpHandler's, [Request / Response Filters](/request-and-response-filters) and HttpResult/HttpError results - giving you a multitude of options to maintain full control over the entire HTTP Output - should you need to meet any extraneous external requirements. 

### Text serializers are fast, resilient and idiomatic

ServiceStack's JSON & JSV serializers are **case-insensitive** (i.e. supports both camelCase and PascalCase properties) and the 1-line below (already included in most Example templates) emits idiomatic camelCase JSON output:

```cs
JsConfig.Init(Config { TextCase = TextCase.CamelCase });
```

They're both [very resilient and can withstand extreme versioning without error](./redis/schemaless-migration.md) making it easy to consume 3rd party APIs.

### Your services can be consumed by more than just HTTP

Your services implementation can even be re-used inside any [IMessageService hosts](/redis-mq), which at this time includes support for 
[Background MQ, Rabbit MQ, Redis MQ, AWS SQS and Azure Service Bus MQ Servers](/messaging) and for Maximum Performance
Services can also be consumed from [high-performance HTTP/2 gRPC endpoints](/grpc/) and its universe of [protoc Generated Clients](https://grpc.servicestack.net/). All these features actually make ServiceStack one of the most versatile and flexible web service frameworks in existence - enabling your services accessible in a myriad of different use-cases.

### Most examples don't actually have .NET clients

This is also a peculiar assumption in light of the fact that most [ServiceStack Examples](https://github.com/ServiceStack/ServiceStack.Examples/) (as seen on http://servicestack.net) are actually Single Page Apps being consumed with Ajax clients (i.e. no .NET clients in sight). 

The [Backbone TODOs example](http://www.servicestack.net/Backbone.Todos/) shows how trivial it was to retrofit Backbone's REST service with a ServiceStack backend and the [SocialBootstrapApi](https://github.com/ServiceStack/SocialBootstrapApi) example show-cases an internet-ready Single Page Backbone App with Facebook, Twitter, HTML Form credentials, Basic Auth & Digest Auth, all enabled. It also makes use of ServiceStack's [cross-platform node.js bundler](https://github.com/ServiceStack/Bundler) for statically compiling, minifying and concatenating your websites .coffee, .js, .less, .sass and .css assets - and since it works headless and without .NET, is able to be used for non .NET projects as well.

### .NET clients can benefit from a typed API

.NET clients do benefit from being able to re-use the same types you've defined your web services with, which in addition to [pre-defined auto routes](http://www.servicestack.net/ServiceStack.Hello/#predefinedroutes) and generic service clients, is what enables the typed, end-to-end client gateways.

### Just as consumable as any other web service

But even without this, ServiceStack services are just as consumable as any other web service framework since they're just pure DTOs serialized into the preferred Content-Type, with no additional bytes or wrappers added to the response. Different client examples in contrast:

The earlier typed API example of creating a new TODO in C#:

```csharp
var client = new JsonApiClient(baseUrl);
Todo createdTodo = client.Post(new Todo { Content = "New Todo", Order = 1 });
```

Is like this in [TypeScript](/typescript-add-servicestack-reference):

```ts
var client = new JsonApiClient(baseUrl);
var request = Todo();
request.Content = "New Todo";
request.Order = 1;
client.post(request)
    .then((createdTodo) => ...)
```

and this in Dart (using the [Dart JSON Client](https://github.com/mythz/DartJsonClient)):

```dart
var client = new JsonClient(baseUrl);
client.todos({'content':'New Todo', 'order':1})
        .then((createdTodo) => ...);
```

Or in jQuery:

```js
$.post(baseUrl + '/todos', {content:'New Todo', order:1}, 
       function(createdTodo) { ... }, 'json');
```

And you still have the option to consume all services in other Content-Types. Some languages may prefer to deal with XML - which can easily be accessed by adding the appropriate `Accept` and `Content-Type` headers.

## What's the best way to expose our services to clients today?

### What was SOAP's original vision?

Back in the W3C glory days, existed think-tanks who imagined a beautiful world were you could easily discover and connect to services through the magical properties of UDDI and WSDLs. However this pipe-dream never came to pass, the closest .NET got was the 'Add Service Reference' dialog ingrained in VS.NET - which we refer to internally as the technical-debt-creating-anti-pattern dialog :)

### So how should we expose our services now?

The natural choice would be to just document your services' uniform HTTP Interface using XML or JSON REST APIs. This is a popular choice for many companies today, some good examples include [StackOverflow](http://api.stackoverflow.com/1.0/usage) and [GitHub](http://developer.github.com/v3/). This approach easily supports dynamic clients who are able to trivially consume JSON responses.

### Native language client libraries

A more productive option for clients however would be to provide a native client library for each of the popular languages you wish to support. This is generally the approach of companies who really, really want to help you use their services - they tend to call their clients **SDK's** which abstract away the underlying connection transport behind optimal native language bindings. This is especially evident from companies whose business relies on the popular use of their APIs, like [Amazon](http://aws.amazon.com/sdkfornet/), [Facebook](https://developers.facebook.com/docs/sdks/) and [Windows Azure](https://github.com/WindowsAzure). This is an especially good idea if you want to support static languages (i.e. C# and Java) where having typed client libraries saves end-users from reverse engineering the types and API calls. It also saves them having to look up documentation since a lot of it can be inferred from the type info. ServiceStack's and Amazons convention of having `ServiceName` and `ServiceNameResponse` for each service also saves users from continually checking documentation to work out what the response of each service will be.

### Packaging client libraries

In terms of packaging your client libraries, sticking a link to a zip file on your Websites APIs documentation page would be the easiest approach. It would be better if the zip file was a link to a master archive of a Github repository as you'll be able to accept bug fixes and usability tips from the community. Finally we believe the best way to make your client libraries available would be to host them in the target languages native package manager - letting end-users issue 1-command to automatically add it to their project, and another to easily update it when your service has changed. 

### NuGet is the new Add Service Reference

For .NET this means adding it to NuGet. If you use ServiceStack your package would just need to contain your types with a reference to [ServiceStack.Client](http://nuget.org/packages/ServiceStack.Client) - which contains all ServiceStack's generic JSON, XML, JSV and SOAP 1.1/1.2 service clients. Add a reference to [ServiceStack.ProtoBuf](http://nuget.org/packages/ServiceStack.ProtoBuf) if you want to support Protocol Buffers as well. One of the benefits of using ServiceStack is that all your types are already created since it's what you used to define your web services with!


# Why Remote Services should use DTOs
Source: https://docs.servicestack.net/why-remote-services-use-dtos

Types provide several productivity and compiler benefits when used within the same solution, they're especially more useful 
across process boundaries where they're the only mechanical tool that will be able to determine if Remote Services are being 
consumed correctly, mitigating run-time errors from making it into production where they'll ultimately be discovered by 
end-users who'll exhaust untested corner cases.

## The Service Layer is your most important Contract

The most important interface that you can ever create in your entire system is your external facing service contract, this is what consumers of your service or application will bind to, i.e. the existing call-sites that often won't get updated along with your code-base - every other model is secondary. 

### DTOs are Best practices for remote services

In following of [Martin Fowler's recommendation for using DTOs](http://martinfowler.com/eaaCatalog/dataTransferObject.html) (Data Transfer Objects) for remote services ([MSDN](http://msdn.microsoft.com/en-us/library/ff649585.aspx)), ServiceStack encourages the use of clean, untainted POCOs to define a well-defined contract with that should kept in a largely implementation and dependency-free .dll. The benefits of this allows you to be able to re-use typed DTOs used to define your services with, as-is, in your [C#/.NET Clients](/csharp-client) - providing an end-to-end typed API without the use of any code-gen or other artificial machinery.

### DRY vs Intent

Keeping things DRY should not be confused with clearly stating of intent, which you should avoid trying to DRY or [hide behind inheritance](http://ayende.com/blog/4769/code-review-guidelines-avoid-inheritance-for-properties), magic properties or any other mechanism. Having clean, well-defined DTOs provides a single source of reference that anyone can look at to see what each service accepts and returns, it allows your client and server developers to start their work straight away and bind to the external service models without the implementation having been written. 

Keeping the DTOs separated also gives you the freedom to re-factor the implementation from within without breaking external clients, i.e. your service starts to cache responses or leverages a NoSQL solution to populate your responses with.

It's also provides the authoritative source (that's not leaked or coupled inside your app logic) that's used to create the auto-generated metadata pages, example responses, Swagger support, XSDs, WSDLs, etc. 

### [Using ServiceStack's Built-in auto-mapping](/auto-mapping)

Whilst we encourage keeping separate DTO models, you don't need to maintain your own manual mapping as you can use a mapper like [AutoMapper](https://github.com/AutoMapper/AutoMapper) or using ServiceStack's built-in Auto Mapping support, e.g:

Create a new DTO instance, populated with matching properties on viewModel:

```csharp
var dto = viewModel.ConvertTo<MyDto>();
```

Initialize DTO and populate it with matching properties on a view model:

```csharp
var dto = new MyDto { A = 1, B = 2 }.PopulateWith(viewModel);
```

Initialize DTO and populate it with **non-default** matching properties on a view model:

```csharp
var dto = new MyDto { A = 1, B = 2 }.PopulateWithNonDefaultValues(viewModel);
```

Initialize DTO and populate it with matching properties that are annotated with the **Attr** Attribute on a view model:

```csharp
var dto = new MyDto { A=1 }.PopulateFromPropertiesWithAttribute<Attr>(viewModel);
```

When mapping logic becomes more complicated we like to use extension methods to keep code DRY and maintain the mapping in one place that's easily consumable from within your application, e.g:

```csharp
public static class MappingExtensions
{
    public static MyDto ToDto(this MyViewModel viewModel)
    {
        var dto = viewModel.ConvertTo<MyDto>();
        dto.Items = viewModel.Items.ConvertAll(x => x.ToDto());
        dto.CalculatedProperty = Calculate(viewModel.Seed);
        return dto;
    }
}
```

Which is now easily consumable with just:

```csharp
var dto = viewModel.ToDto();
```


  [3]: http://www.palmmedia.de/Blog/2011/8/30/ioc-container-benchmark-performance-comparison
  [4]: /clients-overview
  [5]: http://ayende.com/blog/4769/code-review-guidelines-avoid-inheritance-for-properties
  [6]: /auto-mapping
  [7]: https://github.com/AutoMapper/AutoMapper


# Complexity, Services and Role of DTOs
Source: https://docs.servicestack.net/service-complexity-and-dto-roles

The Software world has an overload of contrasting and competing knowledge that it can be daunting to know how 
to develop software, what tools and patterns we should use, which technical literature we should follow and
when and how we should adopt patterns. The overarching theme that has served us well over the years is a relentless 
pursuit for simplicity and seeking out the simplest solutions, with minimal abstractions, concepts that best solves 
any given problem. 

Since its inception in 2008, this philosophy has helped ServiceStack become the worlds most versatile 
Services Framework - supporting an unparalleled number of 
[Pluggable Formats](/why-servicestack#multiple-pluggable-formats), 
multitude of [HTTP, SOAP and MQ Endpoints](/why-servicestack#multiple-endpoints)
that can be hosted in a [variety of hosting scenarios](/why-servicestack#multiple-hosting-options) whilst 
providing a productive succinct, end-to-end Typed API for the most popular 
[native Mobile and Desktop](/add-servicestack-reference)
and [.NET platforms](https://github.com/ServiceStackApps/HelloMobile#client-applications). 
In the time other vendors have left a 
[number of abandoned frameworks](/advantages-of-message-based-web-services#the-many-webservice-frameworks-of-microsoft) 
and failed HTTP abstractions behind for their next framework rewrite, ServiceStack has managed to stay lean, fast and 
continually enhance and evolve its single code-base to support every major HTTP Host delivered with .NET with an order of 
magnitude less resources. This is only achievable due to our relentness pursuit of simplicity, focus on underlying value, 
[rewriting friction-encumbered providers](/architecture-overview)
whilst actively rejecting 
[unnecessary complexity and abstractions](https://www.infoq.com/articles/interview-servicestack) and slow
[bloated technologies promoting well-known anti-patterns](/autoquery/why-not-odata) whose resulting value does not justify the 
level of investment and effort required to adopt it. We hope our experience can provide valuable insight and help 
with deciding what areas to focus on and which to avoid.

## Software's biggest enemy

We consider [Complexity and Large Code bases](http://steve-yegge.blogspot.com/2007/12/codes-worst-enemy.html)
the **single worst enemy** of software development, and that along with meeting the project requirements 
and deriving value from our software, managing complexity and maintaining a minimal and low friction, 
evolvable code-base should be at the forefront of our minds as we're continually enhancing our software with 
new features and requirements. Any guidelines, rules or processes we add to increase software quality should 
be directly focused on managing its essential complexity. One of the best things we can do to reduce complexity 
is to reduce code-base size, i.e. DRYing repeatable code and eliminating any unnecessary abstractions, 
indirection, concepts, types and friction that isn't absolutely essential to the software's function.

In this light, [YAGNI](https://en.wikipedia.org/wiki/You_aren%27t_gonna_need_it) is one of the best principles 
to follow to ensure a simple and lean code-base by focusing on what's essential to delivering value.

### Avoid blanket rules

We recommend avoiding "blanket rules" which we consider one of the primary causes of unnecessary complexity in Software, 
where it's often liberally and thoughtlessly applied, infecting a code-base without justification.
Every time you impose an artificial limitation, you're creating friction and inertia to develop within its bounds 
in order to satisfy it, which is why any rule you enforce should be thoughtfully and carefully applied 
and limited to places where it adds value.

### Be wary of invalid Rules and Patterns

Even Software Design Patterns are in many cases 
[programming language deficiencies](http://c2.com/cgi/wiki?AreDesignPatternsMissingLanguageFeatures), where 
what's a useful in one language is unnecessary and 
more elegantly solved in more expressive and powerful languages. Likewise with "rules", what's a 
cautionary guideline in one domain may not be applicable in others. Therefore what's more important than 
"the rule" itself, is the value it actually provides and what concrete side-effect it's trying to prevent. 
Once we understand its true value, we can optimize to derive maximum value from it and together with YAGNI, 
know when to selectively apply it.

## The Simple POCO Life

ServiceStack achieves a lot of its simplicity and reuse by being able to reuse the same POCOs indiscriminately anywhere 
to interface and freely communicate between its different libraries and components. 
This enables maximum value and reuse of your Models and reduces the friction in mapping between different domains 
which typically require having purpose-specific types, each with its own unique configuration limiting its 
applicability and potential re-use.

### Heavy ORM models are poor DTOs

Not reusing data models as DTOs applies to Heavy ORM's which encourage Data Models with cyclical dependencies 
and proxied objects with tight coupling and embedded logic that can trigger unintended N+1 data access, making 
these models poor candidates for use as DTOs and why you should always copy them into purpose-specific
DTOs that your Services can return so they're serializable without issue.

### Clean POCOs

The complex Data Models stored in 
[OrmLite](https://github.com/ServiceStack/ServiceStack.OrmLite) or 
[Redis](https://github.com/ServiceStack/ServiceStack.Redis) doesn't suffer from any of these issues which are able to use 
clean, disconnected POCOs. They're loosely-coupled, where only the "Shape" of the POCO is significant, i.e. 
moving projects and changing namespaces won't impact serialization, how it's stored in RDBMS tables, 
Redis data structures, Caching providers, etc. 
You're also not coupled to specific types, you can use a different type to insert data in OrmLite than what you
use to read from it, nor does it need to be the "exact Shape", as OrmLite can populate a DTO with only a
subset of the fields available in the underlying table. There's also no distinction between Table, View or 
Stored procedure, OrmLite will happily map any result-set into any matching fields on the specified POCO, 
ignoring others.

Effectively this means POCOs in ServiceStack are extremely resilient and interoperable, so you can happily
re-use the same DTOs in OrmLite and vice-versa without issue. If the DTO and Data models only deviate slightly, 
you can [hide them from being serialized](https://stackoverflow.com/a/14859968/85785) or stored in OrmLite with 
the attributes below:

```csharp
public class Poco
{
    [Ignore]
    public int IgnoreInOrmLite { get; set; }

    [IgnoreDataMember]
    public int IgnoreInSerialization { get; set; }
}
```

Otherwise when you need to separate them, e.g. more fields were added to the RDBMS table than you want to 
return, the DTO includes additional fields populated from alternative sources, or you just want your Services
to project them differently. At that point (YAGNI) you can take a copy of the DTO and add it to your Services 
Implementation so they can grow separately, unimpeded by their different concerns. 
You can then effortlessly convert between them using  
[ServiceStack's built-in Auto Mapping](/auto-mapping), e.g:

```csharp
var dto = dbPoco.ConvertTo<Poco>();
```

::: info
The built-in Auto Mapping is also very tolerant and can co-erce properties with different types,
 e.g. to/from strings, different collection types, etc
:::

## Data Transfer Objects - DTOs

So if you're using clean, serializable POCOs without external dependencies (e.g. from OrmLite, Redis or alt 
ServiceStack sources) you can happily re-use them as DTOs and freely refactor them out into different models 
as-and-when you need to. But when you are re-using Data Models as DTOs they should still be maintained in the 
**ServiceModel** project (aka DTO .dll) which should contain **all the types** that your Service returns.
DTOs should be logic and dependency-free so the only dependency the ServiceModel project references is the 
impl-free  `ServiceStack.Interfaces.dll` which as it's a .NET v4.5 and .NET Standard 2.0 .dll, can be freely referenced from all 
[.NET Mobile and Desktop platforms](https://github.com/ServiceStackApps/HelloMobile).

You want to ensure all types your Services return are in the DTO .dll since this, along with the base url of 
where your Services are hosted is **all that's required** for your Service Consumers to know in order to 
consume your Services. Which they can use with any of the 
[.NET Service Clients](/csharp-client)
to get an end-to-end Typed API without code-gen, tooling or any other artificial machinery. 
If clients prefer source code instead, they can use 
[Add ServiceStack Reference](/add-servicestack-reference) 
to access the Servers typed DTOs in their preferred platform and language of choice.

## Services

Services are the ultimate form of encapsulating complexity and offers the highest level of software reuse.
They package its capabilities and makes them available remotely to your consumers with never any more 
complexity than the cost of a Service call. They're also a vital tool in managing the complexity of large
systems which when modelled correctly are able to divide Monoliths into cohesive, reusable and composable 
functionality at a macro-level. 

![DTO Interface vs Service Implementation](/img/pages/dtos-role.png)

The DTOs are what defines your Services contract, keeping them isolated from any Server implementation is 
how your Service is able to encapsulate its capabilities (which can be of unbounded complexity) and make them
available behind a remote facade. It separates what your Service provides from the complexity in how it 
realizes it. It defines the API for your Service and tells Service Consumers the minimum info they need to know 
to discover what functionality your Services provide and how to consume them 
(maintaining a similar role to Header files in C/C++ source code). 
Well-defined Service contracts decoupled from implementation, enforces interoperability ensuring that 
your Services don't mandate specific client implementations, ensuring they can be consumed by any HTTP 
Client on any platform. DTOs also define the shape and structure of your Services wire-format, ensuring they can
be cleanly deserialized into native data structures, eliminating the effort in manually parsing Service Responses.

### Parallel Client development

Since they capture the entire contract it also enables clients to develop their applications before the 
Services are implemented as they're able to bind their application to its concrete DTO models and can easily 
mock their Service client to return test data until the back-end Services are implemented.

As far as rules go, ensuring a well-defined Service Contract (DTOs) decoupled from its implementation 
goes to the very essence of what a Service is and the value it provides. 

### Request and Response DTOs

As for which DTOs make good candidates for re-use as Data Models, you don't want to use **Request DTOs**
for anything other than defining your external Services API which is typically a **Verb** that's ideally 
[grouped by Call Semantics and Response Types](https://stackoverflow.com/a/15941229/85785), e.g:

```csharp
public class SearchProducts : IReturn<SearchProductsResponse> 
{
    public string Category { get; set; }
    public decimal? PriceGreaterThan { get; set; }
}
```

Your RDBMS tables are normally entities defined as **Nouns**, i.e. what your Service returns:
    
```csharp
public class SearchProductsResponse
{
    public List<Product> Results { get; set; }        
    public ResponseStatus ResponseStatus { get; set; }
}
```

Even the containing **Response DTO** which defines what your Service returns isn't a good candidate for re-use 
as a Data Model. I'd typically use discrete DTOs for Service Responses as it allows freely extending existing 
Services to return extra data or metadata without breaking existing clients.

Other than the Request and Response DTOs, all other the **Types** that your Service returns would be 
candidates for re-use as Data Models, keeping them in the **ServiceModel** project for the reasons above.


# API First Development
Source: https://docs.servicestack.net/api-first-development

One message we continually try to re-iterate is the importance of Services (aka APIs) having a well-defined coarse-grained Services Contract 
which serves as the interface into your system by which all external consumers bind to - making it the most important contract in your system.

A strategy we recommend for maximizing re-use of your Services is to design them from an API-first point of view where all consumers 
(e.g. Desktop, Mobile and Web UIs) have equal accessibility to your services since they all consume the same published API's for all of 
their functionality.

## Benefits of Services

This is the development model ServiceStack has always promoted and what most of its features are centered around, where your Services Contract is 
defined by decoupled impl-free DTOs. If your Services retain this property then they'll be able to encapsulate any of its capabilities of 
infinite complexity and make it available remotely to all consumers with never any more complexity than the cost of a Service call:

![](/img/pages/dtos-role.png)

This is ultimately where most of the value of Services are derived, they're the ultimate form of encapsulating complexity and offers the highest level 
of software reuse. ServiceStack amplifies your Services capabilities by making them available in multiple [Hosting Options](/why-servicestack#multiple-hosting-options), 
[serialization formats](/why-servicestack#multiple-pluggable-formats), [MQ and SOAP endpoints](/why-servicestack#multiple-endpoints) to
enable more seamless integrations in a variety of different scenarios including native end-to-end Typed APIs for the most popular 
[Web, Mobile and Desktop Apps](/why-servicestack#multiple-clients) that reduce the effort and complexity required to call your Services 
in all consumers - multiplicatively increasing the value provided.

## API First Development Model

The typical practice in .NET has been you need to maintain **separate controllers** and logic for your **HTML UIs** and **API controllers** 
for your **HTTP APIs**. This approach forces code duplication and breaks your systems well-defined Service Contracts where any custom
logic in your MVC Controllers and Razor pages becomes another entry point into your system where no longer are all your system capabilities available 
to all clients, some are only available when using a browser to navigate MVC pages.

Whereas if you develop your APIs first, focusing instead of exposing your System's functionality behind pure-logic APIs, all clients 
including Web, Mobile, Desktop clients and B2B integrations will be able to utilize your same well-tested System Interfaces.

In ServiceStack there are no "MVC Controllers" just for HTML pages, there are only Services, which are written with pure logic that's unopinionated 
as to what clients are calling it, with clean **Request DTOs** received as Inputs that typically return clean **Response DTOs** as outputs. 
HTML is then just another serialization format, providing a View of your Services or serving as a bundled UI that works on top of your 
existing Services, in all cases calling the same well tested and defined Services that all other clients use.

For web development this means that UI logic and Error handling should ideally be utilizing the pure API Error Responses rather than behind 
server-side pages which gets easily coupled to your server implementation rather than your external published APIs. 

### Multiple Web UI Validation Examples using same Services

To better demonstrate the benefits of this approach and and show how there's no loss of flexibility, we've created the 
[World Validation](https://github.com/NetCoreApps/Validation) .NET Core App which uses the same pure unopinionated ServiceStack Services to support 
**8 different HTML UI strategies** including server HTML Rendered and Ajax Client forms, multiple View Engines, multiple layouts - all utilizing 
the same Services and declarative [Fluent Validation](/validation).

[![](https://raw.githubusercontent.com/ServiceStack/Assets/master/img/apps/Validation/home.png)](https://github.com/NetCoreApps/Validation)

<h4 align="center">View Source on GitHub <a href="https://github.com/NetCoreApps/Validation">NetCoreApps/Validation</a></h4>

It should be noted that these are just examples of different HTML UIs, with no additional effort, all ServiceStack Services automatically
provide native integrations into **all popular Mobile and Desktop Apps** with [Add ServiceStack Reference](/add-servicestack-reference). 

## [World Validation](/world-validation)

The annotated [World Validation Docs](/world-validation) walks through and showcases the implementation of how the most popular **Server HTML rendered**
approaches and **Client UI rendered** technologies which are able all to use the same single suite of ServiceStack Services.


# Auto HTML API Page
Source: https://docs.servicestack.net/auto-html-api

The Auto HTML Page provides instant utility for API consumers in consuming your APIs with a built-in API Response Visualizer, JSON syntax highlighting, integrated Postman-like UI and API SDK integration all-in-one.

<div class="not-prose hide-title my-16 px-4 sm:px-6">
    <div class="text-center">
        <h3 id="autohtml" class="text-4xl sm:text-5xl md:text-6xl tracking-tight font-extrabold text-gray-900">
            Auto HTML API
        </h3>
    </div>
    <p class="mx-auto mt-5 max-w-prose text-xl text-gray-500"> The best way to visualize, inspect and integrate with your APIs in an instant!</p>
    <div class="my-8">
        <lite-youtube class="w-full mx-4 my-4" width="560" height="315" videoid="3gjisRVqhLo" style="background-image: url('https://img.youtube.com/vi/3gjisRVqhLo/maxresdefault.jpg')"></lite-youtube>
    </div>
</div>

Lets take a quick tour through each of these features:

## PREVIEW

Calling our APIs in a browser will greet us with the Preview page which uses the [HtmlFormat](/vue/formats#htmlformat) to display the API response in a
beautiful Tailwind style with links to different [Content-Type Formats](/formats) and direct links to view it in [API Explorer](/api-explorer) and [Locode](/locode/) for [AutoQuery](/autoquery/rdbms) APIs:

<a href="https://northwind.netcore.io/customers/ALFKI" class="not-prose max-w-4xl">
    <div class="block flex justify-center shadow hover:shadow-lg rounded">
        <img class="" src="/img/pages/ui/autohtml-preview.png">
    </div>
</a>

## JSON

Developers who wish to view the actual JSON API Response can click on the **JSON** tab to view the JSON in pretty-formatted syntax-highlighted form with a 1-click button to copy:

<a href="https://northwind.netcore.io/customers/ALFKI?tab=json" class="not-prose max-w-4xl">
    <div class="block flex justify-center shadow hover:shadow-lg rounded">
        <img class="" src="/img/pages/ui/autohtml-json.png">
    </div>
</a>

## FORM

You don't need to build UIs before non-developers can access your APIs with the **FORM** tab which uses the new [AutoForm](/vue/autoform) component
to render an optimal UI to call an API that you can further customize from your C# Request DTOs:

<a href="https://blazor-gallery.servicestack.net/bookings/1?tab=form" class="not-prose max-w-4xl">
    <div class="block flex justify-center shadow hover:shadow-lg rounded">
        <img class="" src="/img/pages/ui/autohtml-form-bookings.png">
    </div>
</a>

## CODE

The **CODE** tab gives you an appealing API docs page you can immediately share with any 3rd Party Developers that want to consume your APIs, with simple
step-by-step instructions for how to call your APIs from their preferred programming language:

<a href="https://northwind.netcore.io/customers/ALFKI?tab=code" class="not-prose max-w-4xl">
    <div class="block flex justify-center shadow hover:shadow-lg rounded">
        <img class="" src="/img/pages/ui/autohtml-code.png">
    </div>
</a>

A nice benefit of ServiceStack's API Design is that consuming APIs are fundamentally all done the same way in all languages, which just requires adding a 
dependency containing a generic ServiceClient which can be used to call any ServiceStack API using the typed DTOs copied directly from the API docs page
to enable an end-to-end typed API without any external tooling or build steps.

## API Fallback HTML Page

The Auto HTML API is the fallback HTML page returned for APIs when calling user-defined routes from a browser (i.e. **Accept: text/html**):

### [https://northwind.netcore.io/customers/ALFKI](https://northwind.netcore.io/customers/ALFKI)

When calling the [/api pre-defined route](/routing#json-api-pre-defined-route) with the `.html` extension:

### [https://northwind.netcore.io/api/GetCustomerDetails.html?Id=ALFKI](https://northwind.netcore.io/api/GetCustomerDetails.html?Id=ALFKI)

When calling the [/api pre-defined route](/routing#json-api-pre-defined-route) with `?format=html`:

### [https://northwind.netcore.io/api/GetCustomerDetails?Id=ALFKI&format=html](https://northwind.netcore.io/api/GetCustomerDetails?Id=ALFKI&format=html)


# API Explorer
Source: https://docs.servicestack.net/api-explorer

API Explorer is a Postman & Swagger UI alternative built into every ServiceStack **v6+** App that lets you explore, discover & call your APIs with an Auto UI dynamically generated from your APIs typed C# classes. 

It's built from the ground up with multiple levels of customizations, supporting both declarative & programmatic models for customizing each properties Input UI control, each APIs form grid layout whilst also providing the ability to provide rich interactive HTML Components to document each of your APIs & their Types.

This video provides a quick overview of API Explorer's v1 featureset:

<lite-youtube class="w-full mx-4 my-4" width="560" height="315" videoid="lUDlTMq9DHU" style="background-image: url('https://img.youtube.com/vi/lUDlTMq9DHU/maxresdefault.jpg')"></lite-youtube>

::: info DEMO
A Live demo is available at **/ui** in all ServiceStack **v6+** Apps, e.g: [vue-vite-api.jamstacks.net/ui](https://vue-vite-api.jamstacks.net/ui)
:::

The entire API Explorer UI is driven by the **rich metadata** around your APIs typed Service Contracts and AppHost's **registered plugins**.

- The **Sidebar** - Displaying a list of APIs each user has access to
- The **API** tab - Providing dynamic form to call & inspect your APIs
- The **Details** tab - Containing a complete description of your APIs & its dependent types
- The **Code** tab - Letting API consumers browse API Service contracts in their preferred language ([11 languages supported](https://servicestack.net/service-reference))

<p class="text-center py-4 text-xl">Lets learn about each feature with screenshots 📷</p>

If your AppHost has the ServiceStack [AuthFeature](/auth/authentication-and-authorization) plugin registered, the home page will display a **Sign In** dialog based on the its **configured Auth Providers**. 

This is what you'll see in a new [Vue Vite](https://vue-vite-api.jamstacks.net/ui) project which has **Credentials** Auth, **JWT** as well as **Facebook**, **Google** and **Microsoft** OAuth providers registered in [Configure.Auth.cs](https://github.com/NetCoreTemplates/vue-vite/blob/main/api/MyApp/Configure.Auth.cs)

```csharp
Plugins.Add(new AuthFeature(() => new CustomUserSession(),
    new IAuthProvider[] {
        new JwtAuthProvider(appSettings) {
            AuthKeyBase64 = appSettings.GetString("AuthKeyBase64"),
        },
        new CredentialsAuthProvider(appSettings),
        new FacebookAuthProvider(appSettings),
        new GoogleAuthProvider(appSettings),
        new MicrosoftGraphAuthProvider(appSettings),
    })
{
    IncludeDefaultLogin = false
});
```

## Integrated Sign In

Where it will dynamically render the **Sign Up** form with the App's enabled Auth capabilities.

<a href="https://vue-vite-api.jamstacks.net/ui" class="block my-8 p-4 rounded shadow hover:shadow-lg">
    <img src="/img/pages/apiexplorer/signin.png">
</a>

Custom Auth Providers can provide their own Form Layout by overriding the `FormLayout`, e.g. the above Credentials UI is creatable with:

```csharp
public class CustomCredentialsAuthProvider : CredentialsAuthProvider
{
    public CustomCredentialsAuthProvider()
    {
        FormLayout = new() {
            Input.For<Authenticate>(x => x.UserName, c =>
            {
                c.Label = "Email address";
                c.Required = true;
            }),
            Input.For<Authenticate>(x => x.Password, c =>
            {
                c.Type = "Password";
                c.Required = true;
            }),
            Input.For<Authenticate>(x => x.RememberMe),
        };
    }
    //...
}
```

Where the `Input` utility can be used to configure most HTML Form Input control properties that automatically configures to use the desired Input control for each property Type.

You can Sign In with any of the users in the [Vue Vite Sign In](https://vue-vite.jamstacks.net/signin) page configured in 
[Configure.AuthRepository.cs](https://github.com/NetCoreTemplates/vue-vite/blob/main/api/MyApp/Configure.AuthRepository.cs), i.e:

| Username           | Password | Role     |
| ------------------ | -------- | -------- |
| admin@email.com    | p@55wOrd | Admin    |
| manager@email.com  | p@55wOrd | Manager  |
| employee@email.com | p@55wOrd | Employee |

If signed in with the **Admin** User and the [Admin Users](/admin-ui-users) plugin is configured:

```csharp
Plugins.Add(new AdminUsersFeature());
```

It also displays **Admin UI** links that only **Admin** Users have access to.

<a href="https://vue-vite-api.jamstacks.net/ui" class="block my-8 p-4 rounded shadow hover:shadow-lg">
    <img src="/img/pages/apiexplorer/admin-user.png">
</a>

If you'd like to, you can add personalized links for users in different roles, e.g. this is what's used to populate the above UI for Admins:

```csharp
appHost.AddToAppMetadata(meta =>
{
    meta.Plugins.Auth.RoleLinks[RoleNames.Admin] = new List<LinkInfo>
    {
        new() { Href = "../admin-ui", Label = "Dashboard", Icon = Svg.ImageSvg(Svg.Create(Svg.Body.Home)) },
        new() { Href = "../admin-ui/users", Label = "Manage Users", Icon = Svg.ImageSvg(Svg.GetImage(Svg.Icons.Users, "currentColor")) },
    };
});
```

Once signed in, API Explorer expands to include all the protected APIs the signed in user has access to, identifiable with the padlock icon.

### Disable API Explorer

::: info
API Explorer is powered by the rich API metadata provided by the `MetadataFeature` and can be customized through the `UiFeature` plugin. 
Removing either plugin disables API Explorer.
```csharp
Plugins.RemoveAll(x => x is UiFeature);
```
:::

## API Tab

After selecting an API to use from the left-hand menu, you will be greeted with a way to **call APIs** through an **Auto UI** generated based on the **Request DTO** schema. Submitting the form returns API results with:

- **Body** displaying a syntax highlighted JSON response
- **Raw** showing raw JSON output in a textarea
- **Preview** tab displaying results in a human-friendly view

::: info
The `Raw` response forces a `CamelCase` response since the API Explorer interface needs consistent casing outside your applications default `TextCase`.
Those using `SnakeCase` or `PascalCase` will see a different response outside of API Explorer.
:::

<a href="https://vue-vite-api.jamstacks.net/ui/QueryBookings?body=preview" class="block my-8 p-4 rounded shadow hover:shadow-lg">
    <img src="/img/pages/apiexplorer/api-form-QueryBookings.png">
</a>

Control types are based on the property types in your DTOs. 

| UI Input                | Data Types |
| ----------------------- | ---------- |
| `<select>`              | Enum, Custom Values |
| `<input type=number>`   | Numeric Types |
| `<input type=date>`     | DateTime, DateTimeOffset, DateOnly |
| `<input type=time>`     | TimeSpan, TimeOnly |
| `<input type=checkbox>` | Boolean |
| `<input type=text>`     | default |

Where the `CreateBooking` Request DTO defined in [Bookings.cs](https://github.com/NetCoreTemplates/blazor-wasm/blob/main/MyApp.ServiceModel/Bookings.cs):

```csharp
[Tag("bookings"), Description("Create a new Booking")]
[Route("/bookings", "POST")]
[ValidateHasRole("Employee")]
[AutoApply(Behavior.AuditCreate)]
public class CreateBooking : ICreateDb<Booking>, IReturn<IdResponse>
{
    [Description("Name this Booking is for"), ValidateNotEmpty]
    public string Name { get; set; }
    public RoomType RoomType { get; set; }
    [ValidateGreaterThan(0)]
    public int RoomNumber { get; set; }
    [ValidateGreaterThan(0)]
    public decimal Cost { get; set; }
    public DateTime BookingStartDate { get; set; }
    public DateTime? BookingEndDate { get; set; }
    [Input(Type = "textarea")]
    public string? Notes { get; set; }
}
```

Generates the following UI:

<div class="flex justify-center py-8">
    <a href="https://vue-vite-api.jamstacks.net/ui/CreateBooking">
        <img src="/img/pages/apiexplorer/api-form-CreateBooking.png" style="max-width:850px;">
    </a>
</div>


This also shows how we can use the [[Input]](https://github.com/ServiceStack/ServiceStack/blob/master/src/ServiceStack.Interfaces/InputAttribute.cs) attribute
to further customize the Input UI control for each property as a **declarative alternative** to using `Input.For<T>()` above that the `Notes` property utilizes to change to use a **textarea** control instead.

API Form also supports auto binding [Argument Exceptions](/error-handling) or [Fluent](/validation) & [Declarative](/declarative-validation) Validation rules where any validation errors will be contextually displayed next to the invalid property. Here's both the resulting invalid UI & the Error Response DTO that generated it:

<div class="flex justify-center py-8">
    <a href="https://vue-vite-api.jamstacks.net/ui/CreateBooking">
        <img src="/img/pages/apiexplorer/api-form-CreateBooking-invalid.png" style="max-width:850px;">
    </a>
</div>

Contextual validation errors is used where possible, otherwise an **Error Summary** notification is displayed along with the API Response body containing the full API error information.

### JSON Form

Another useful API form feature is being able to call APIs with a **JSON request payload** which maintains a **2-way sync** with the Form's UI allowing you to quickly cycle between input modes to quickly construct your API request.

Real-time JSON validation is also displayed for added assistance, warning you whenever the JSON is malformed.

<div class="flex justify-center py-8">
    <a href="https://vue-vite-api.jamstacks.net/ui/CreateBooking">
        <img src="/img/pages/apiexplorer/api-form-CreateBooking-json.png" style="max-width:850px;">
    </a>
</div>

## Details Tab

API Explorer also provides a place for users to find out more about your API through documentation generated by metadata about in your API and optionally custom HTML modules to give additional context. 

This is where API consumers would go to learn about each API where it displays all relevant information about the API at a glance. For `CreateBooking` it shows that:

 - **POST** is the APIs **preferred** HTTP Method 
 - List its **user-defined** and **pre-defined** routes 
 - It's a **protected** API limited to Authenticated Users with the **Employee** role
 - It's categorized in the **bookings** tag group 
 - It's an [AutoQuery CRUD](/autoquery/crud) API implementing `ICreateDb<Booking>` indicating it creates entries in the **Booking** RDBMS Table 
 - It returns an `IdResponse` which we can intuitively infer returns the new Booking **Id** for successfully created Bookings

<a href="https://vue-vite-api.jamstacks.net/ui/CreateBooking?tab=details" class="block my-8 p-4 rounded shadow hover:shadow-lg">
    <img src="/img/pages/apiexplorer/api-details-CreateBooking.png">
</a>

This API Definition was generated from the `CreateBooking` DTO shows that the **Required** column used to document the APIs required properties is required for all properties except for the **nullable** Value and Reference Types when `#nullable` is enabled. 

```csharp
public class CreateBooking : ICreateDb<Booking>, IReturn<IdResponse>
{
    [Description("Name this Booking is for"), ValidateNotEmpty]
    public string Name { get; set; }
    public RoomType RoomType { get; set; }
    [ValidateGreaterThan(0)]
    public int RoomNumber { get; set; }
    [ValidateGreaterThan(0)]
    public decimal Cost { get; set; }
    public DateTime BookingStartDate { get; set; }
    public DateTime? BookingEndDate { get; set; }
    [Input(Type = "textarea")]
    public string? Notes { get; set; }
}
```

::: info
Importantly **Required** annotations are only documentative, your API still has to validate **required reference types** like `string` using your preferred validation method, e.g. Using the `[ValidateNotEmpty]` declarative attribute, [Fluent Validation](/validation) or manual verification in your Service C# implementation and throwing `ArgumentException` for invalid properties
:::

All this data is inferred from your services, with the ability to present data from additional metadata attributes such as:

| Attribute name          | Description                                                     |
|-------------------------|-----------------------------------------------------------------|
| `[Description]`         | Class and properties text only description.                     |
| `[Notes]`               | Class only text and HTML description.                           |
| `[Tag]`                 | Class only categorization of services, a way to group services. |
| `[Input]`               | Properties only presentation data for input fields.             |

If services require authentication using `Authenticate` or validation checking for role or permission, services will be shown with a padlock (🔒) signifying requiring authentication.

Request and response names are links to show C# generated code representations of your DTOs and dependent types. Text metadata such as `[Description]` will also flow down into the generated code as comments for additional context. 

<a class="block my-8 p-4 rounded shadow hover:shadow-lg">
    <img src="/img/pages/apiexplorer/api-details-QueryBookings-code.png">
</a>

## Code Tab

The **Code** tab allows developers consuming your APIs from different programming backgrounds explore each APIs in their **preferred programming language** - currently supporting [11 different languages](https://servicestack.net/service-reference).

It includes the necessary steps to call your APIs from client Apps, following the same pattern for each language:

 1. Copy your API DTOs
 2. Copy and install the package containing ServiceStack's generic JSON Service Client
 3. Copy the initial source code pre-configured to call the API they want

At which point without any code-gen or build tools, they'll end up with an Typed API configured to your APIs endpoint. E.g. this is what it looks like to **Python** developers utilizing our [most recently supported language](/releases/v5_12):

<a href="https://vue-vite-api.jamstacks.net/ui/QueryBookings?tab=code&lang=python" class="block my-8 p-4 rounded shadow hover:shadow-lg">
    <img src="/img/pages/apiexplorer/api-code-QueryBookings-python.png">
</a>

That they can follow to quickly incorporate your API into their existing Apps, in addition **Python**, **C#** or **F#** developers could also copy this source code to their [Jupyter Notebooks](/jupyter-notebooks) for an instant typed visual REPL to explore your APIs.

This is driven by the services that power the [Add ServiceStack Reference](./add-servicestack-reference.md) feature. This growing list of support languages shows example code using the specific API as well as required ServiceStack client libraries to use, and how to update the APIs DTOs.

## Responsive Design

API Explorer's responsive layout works well in Smart Phones and Tablets letting you comfortably browse and call APIs on the go:

<div class="bg-gray-200 flex justify-center py-8">
    <img src="/img/pages/apiexplorer/api-explorer.gif" style="width:500px; border-left:1px solid #CACACA;border-bottom:1px solid #CACACA;">
</div>


## API Customizations

To become the preferred solution to document APIs, API Explorer was designed from scratch to support multiple customization levels, from being able to customize each properties Input control, its Form Grid Layout and further annotating each API or Type with declarative attributes & rich markup. 

### API Annotations

Whilst the capability of adding rich API Docs is essential when needed, we expect plain C# attributes will often be used to document APIs where `[Description]` can be used to provide a short summary on a **Type** and its **Properties** whilst richer HTML markup can be added to any Type using `[Notes]` 
as done in [Bookings.cs](https://github.com/NetCoreTemplates/blazor-wasm/blob/main/MyApp.ServiceModel/Bookings.cs):

```csharp
[Tag("bookings"), Description("Find Bookings")]
[Notes("Find out how to quickly create a <a class='svg-external' target='_blank' href='https://youtu.be/rSFiikDjGos'>C# Bookings App from Scratch</a>")]
[Route("/bookings", "GET")]
[Route("/bookings/{Id}", "GET")]
[AutoApply(Behavior.AuditQuery)]
public class QueryBookings : QueryDb<Booking> 
{
    public int? Id { get; set; }
}

[Description("Booking Details")]
[Notes("Captures a Persons Name & Room Booking information")]
public class Booking : AuditBase
{
    [AutoIncrement]
    public int Id { get; set; }
    //...
}
```

Where it generates clean API docs displayed in a human-friendly table layout containing properties of its **Request DTO** Type and inherited **base class** properties, starting with the APIs Request DTO followed by all its referenced dependent types - resulting in the details page containing a complete snapshot of all types used in the API:

<a href="https://vue-vite-api.jamstacks.net/ui/QueryBookings?tab=details" class="block my-8 p-4 rounded shadow hover:shadow-lg">
    <img src="/img/pages/apiexplorer/api-details-QueryBookings.png">
</a>


## API Docs

We can further enhance API Explorer with our own custom [Vue.js Components](https://vuejs.org/guide/essentials/component-basics.html) by adding them to your Host projects local `/modules/ui/docs` folder which the Blazor WASM project template utilizes to showcase some customization examples:

<ul class="list-none">
    <li>
        <a href="https://github.com/NetCoreTemplates/blazor-wasm/tree/main/MyApp/wwwroot/modules" class="font-medium">/modules</a>
        <ul class="list-none">
            <li>
                <span class="font-medium">/ui/docs</span>
                <ul class="list-none">
                    <li>
                        <a href="https://github.com/ServiceStack/ServiceStack/blob/main/ServiceStack.Blazor/tests/ServiceStack.Blazor.Bootstrap.Tests/Server/modules/ui/docs/CreateBookingDocs.mjs">
                            CreateBookingDocs.mjs
                        </a>
                    </li>
                    <li>
                        <a href="https://github.com/ServiceStack/ServiceStack/blob/main/ServiceStack.Blazor/tests/ServiceStack.Blazor.Bootstrap.Tests/Server/modules/ui/docs/TodoDocs.mjs">
                            TodoDocs.mjs
                        </a>
                    </li>
                </ul>
            </li>
        </ul>
    </li>
</ul>


Where you can enhance any of your APIs or DTOs with rich API docs by adding **Vue Components** to `/modules/ui/docs/*.mjs` which gets included together with API Explorers own components in its single file download. API Explorer is built using [Vue.js](https://vuejs.org/guide/introduction.html) which is a popular 
JavaScript framework that's optimal for progressive enhancement that your components can also take advantage of to enhance it with rich dynamic UIs. 

For auto registration of components the `*.mjs` should match the API doc component which needs to be named `{Type}Docs`.

Here's a simple [CreateBookingDocs.mjs](https://github.com/ServiceStack/ServiceStack/blob/main/ServiceStack.Blazor/tests/ServiceStack.Blazor.Bootstrap.Tests/Server/modules/ui/docs/CreateBookingDocs.mjs) component example used to generate API Docs for the `CreateBooking` API  which just references **server** [AppMetadata](https://api.locode.dev/classes/shared.AppMetadata.html) to access server API info from the `/metadata/app.json` endpoint:

```js
import { inject } from "vue"

export const CreateBookingDocs = {
    template:`
    <div class="text-center my-3">
        <div class="flex justify-center">
            <svg class="w-10 h-10" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 48 48">
                <path fill="#CFD8DC" d="M5 38V14h38v24c0 2.2-1.8 4-4 4H9c-2.2 0-4-1.8-4-4z"/><path fill="#F44336" d="M43 10v6H5v-6c0-2.2 1.8-4 4-4h30c2.2 0 4 1.8 4 4z"/>
                <g fill="#B71C1C"><circle cx="33" cy="10" r="3"/><circle cx="15" cy="10" r="3"/></g>
                <g fill="#B0BEC5"><path d="M33 3c-1.1 0-2 .9-2 2v5c0 1.1.9 2 2 2s2-.9 2-2V5c0-1.1-.9-2-2-2z"/><path d="M15 3c-1.1 0-2 .9-2 2v5c0 1.1.9 2 2 2s2-.9 2-2V5c0-1.1-.9-2-2-2z"/></g>
                <g fill="#90A4AE"><path d="M13 20h4v4h-4z"/><path d="M19 20h4v4h-4z"/><path d="M25 20h4v4h-4z"/><path d="M31 20h4v4h-4z"/><path d="M13 26h4v4h-4z"/><path d="M19 26h4v4h-4z"/><path d="M25 26h4v4h-4z"/><path d="M31 26h4v4h-4z"/><path d="M13 32h4v4h-4z"/><path d="M19 32h4v4h-4z"/><path d="M25 32h4v4h-4z"/><path d="M31 32h4v4h-4z"/></g>
            </svg>
            <h2 class="text-3xl ml-3 mb-3">Create Bookings API</h2>
        </div>
        <div class="text-gray-500 text-lg">
            <p>
                Create a new room Booking for our {{serviceName}} hotels.
            </p>
            <p>
                Here are some
                <a class="svg-external text-blue-800" target="_blank"
                    href="https://edition.cnn.com/travel/article/scoring-best-hotel-rooms/index.html">
                    good tips on making room reservations
                </a>
            </p>
        </div>
    </div>
    `,
    setup() {
        const server = inject('server')
        return { serviceName: server.app.serviceName }
    }
}
```

### Dynamic Components

[QueryTodos](https://vue-vite-api.jamstacks.net/ui/QueryTodos?tab=details) is a more advanced example that generates a dynamic UI shared by all TODO APIs
that generate its reactive **Mini Navigation UI** users can use to cycle through **all TODO API docs** with a `v-href="{ op }"` custom directive:

<a href="https://vue-vite-api.jamstacks.net/ui/QueryTodos?tab=details" class="block my-8 p-4 rounded shadow hover:shadow-lg">
    <img src="/img/pages/apiexplorer/api-details-docs-Todos.png">
</a>

Where instead of registering a single component, it exports a `install(app)` function to register API Doc components for all TODO CRUD APIs, all registered
with the same `TodosDocs` component:

```js
import { inject, computed } from "vue"
import { humanize } from "@servicestack/client"

export function install(app) {
    const apis = {
        QueryTodos:  'Query Todos, returns all Todos by default',
        CreateTodo:  'Create a Todo',
        UpdateTodo:  'Update a Todo',
        DeleteTodo:  'Delete Todo by Id',
        DeleteTodos: 'Delete multiple Todos by Ids',
    }
    const apiNames = Object.keys(apis)
    const TodosDocs = {
        template:`
        <div class="mx-auto max-w-screen-md text-center py-8">
            <h2 class="text-center text-3xl">{{humanize(op.request.name)}}</h2>
            <p class="text-gray-500 text-lg my-3">{{apis[op.request.name]}}</p>
            <div class="flex justify-center text-left">
                <table>
                    <caption class="mt-3 text-lg font-normal">Other Todo APIs</caption>
                    <tr v-for="(info,name) in otherApis">
                        <th class="text-right font-medium pr-3">
                            <a v-href="{ op:name }" class="text-blue-800">{{humanize(name)}}</a>
                        </th>
                        <td class="text-gray-500">{{info}}</td>
                    </tr>
                </table>
            </div>
        </div>`,
        setup() {
            const store = inject('store')
            const op = computed(() => store.op)
            const otherApis = computed(() => apiNames.filter(x => x !== store.op.request.name)
                 .reduce((acc,x) => { acc[x] = apis[x]; return acc }, {}))
            return { 
                op,
                apis,
                otherApis,
                humanize,
            }
        }
    }
    const components = apiNames.reduce((acc, x) => { acc[x + 'Docs'] = TodosDocs; return acc }, {})
    app.components(components)
}
```

## Built-in App functionality

### JavaScript Libraries

Your custom components can utilize built in libraries embedded in ServiceStack.dll where they will have access to the latest [Vue 3](https://vuejs.org/guide/introduction.html) reactive fx, [@servicestack/client](/javascript-client) client library and [Vue 3 Tailwind Component library](/vue/) which they can import by package name, e.g:

```js
import { ref } from "vue"
import { useClient } from "@servicestack/vue"
import { humanify } from "@servicestack/client"
```

**Static Analysis**

As all package dependencies are written in TypeScript you can install them as dev dependencies to get static analysis from its TypeScript definitions at dev time:

```bash
npm install -D vue
npm install -D @servicestack/client
npm install -D @servicestack/vue
```

Your components can access your Apps Typed DTOs directly from the [ES6 Module DTO endpoint](/javascript-add-servicestack-reference) at `/types/mjs`, e.g:

```js
import { QueryCoupons } from "/types/mjs"
```

#### App functionality

Your components access to most App functionality via the injected dependencies for functionality defined in API Explorer's [app.mjs](https://github.com/ServiceStack/ServiceStack/blob/main/ServiceStack/tests/NorthwindAuto/ui/lib/app.mjs):

```js
const app = inject('app')                  // App for customizing Vue App, register components, providers, plugins, etc
const client = inject('client')            // JsonServiceClient for API Calls
const server = inject('server')            // AppMetadata (metadata for your Server App and APIs)
const store = inject('store')              // API Explorer's Reactive object model
const routes = inject('routes')            // usePageRoutes() Reactive store to manage its SPA routing
const breakpoints = inject('breakpoints')  // useBreakpoints() Reactive store to Tailwind responsive breakpoints
```

Most of which creates instance of common library features in [core.mjs](https://github.com/ServiceStack/ServiceStack/blob/main/ServiceStack/tests/NorthwindAuto/wwwroot/js/core.mjs) that are documented at [api.locode.dev/modules/explorer.html](https://api.locode.dev/modules/explorer.html).

You're also not limited with what's in API Explorer, with full access to [JavaScript Modules](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules)
you can import external 3rd Party packages the same way you import built-in packages.

### Built-in API Docs

ServiceStack's own built-in APIs uses custom API Doc components itself to document its APIs, e.g. [/ui/docs/RegisterDocs.mjs](https://github.com/ServiceStack/ServiceStack/blob/main/ServiceStack/src/ServiceStack/modules/ui/docs/RegisterDocs.mjs) 

```js
export const RegisterDocs = {
    template:`
      <div class="max-w-screen-md mx-auto text-center">
          <h2 class="text-2xl font-medium mb-3">Register API</h2>
          <p class="text-gray-500">
            Public API users can use to create a new User Account, can be added to your AppHost with:
          </p>
          <pre class="my-3"><code v-highlightjs="'Plugins.Add(new RegistrationFeature());'"></code></pre>
      </div>`
}
```

Generates docs for the built-in **Register** API that includes **C#** Syntax highlighting using the pre-configured [highlightjs](https://highlightjs.org) directive:

<a href="https://vue-vite-api.jamstacks.net/ui/Register?tab=details" class="block my-8 p-4 rounded shadow hover:shadow-lg">
    <img src="/img/pages/apiexplorer/api-details-docs-Register.png">
</a>

Whilst [/ui/docs/AuthenticateDocs.mjs](https://github.com/ServiceStack/ServiceStack/blob/main/ServiceStack/src/ServiceStack/modules/ui/docs/AuthenticateDocs.mjs) demonstrates a more advanced example in generating a responsive dynamic tab layout containing multiple relevant ServiceStack Auth YouTube videos:

<a href="https://vue-vite-api.jamstacks.net/ui/Authenticate?tab=details" class="block my-8 p-4 rounded shadow hover:shadow-lg">
    <img src="/img/pages/apiexplorer/api-details-docs-Authenticate.png">
</a>

### Live Reload

When your App is run with `dotnet watch` it takes advantage ASP .NET Core's built-in file watcher to enable an instant **live reload** developer UX when contributing API Docs.

<div class="flex justify-center py-8">
    <a href="https://youtu.be/lUDlTMq9DHU?t=521">
        <img src="/img/pages/apiexplorer/api-docs-livereload.gif">
    </a>
</div>

Which results in being more productive then using C# attributes as changes are immediately visible without a restart.

## Customizing API Explorer

You can override each built-in Component in API Explorer by maintaining local customized versions in `/wwwroot/modules/ui`
where each API can be documented by adding [Custom API Docs](/api-explorer#api-docs) to `/docs/*.mjs`,
whilst existing components can be overridden in 
[/components/*.mjs](https://github.com/ServiceStack/ServiceStack/tree/main/ServiceStack/src/ServiceStack/modules/ui/components)
and custom UI added to `custom.*`

```files
/wwwroot/modules/ui
  /docs
    *.mjs
  /components
    *.mjs
  custom.js
  custom.css
  custom.html
```

The `custom.html` and `custom.js` allows for further customization by including custom scripts and HTML fragments at the bottom of 
API Explorer which will let you modify API Explorer after it's loaded.

### Override built-in Components

The built-in UIs also lets you override existing components by adding custom versions in 
[/js/components](https://github.com/ServiceStack/ServiceStack/tree/main/ServiceStack/src/ServiceStack/js/components), e.g:


```js
const Brand = {
    template:`
    <div class="flex items-center flex-shrink-0 max-w-sidebar">
        <a title="My App" v-href="{ $page:'' }"
           class="text-2xl whitespace-nowrap overflow-x-hidden flex items-center">
           <svg xmlns="http://www.w3.org/2000/svg" class="w-8 h-8 ml-1 mr-2" viewBox="0 0 24 24">
               <path d="M23.834 8.101a13.912 13.912 0 0 1-13.643 11.72a10.105 10.105 0 0 1-1.994-.12a6.111 6.111 0 0 1-5.082-5.761a5.934 5.934 0 0 1 11.867-.084c.025.983-.401 1.846-1.277 1.871c-.936 0-1.374-.668-1.374-1.567v-2.5a1.531 1.531 0 0 0-1.52-1.533H8.715a3.648 3.648 0 1 0 2.695 6.08l.073-.11l.074.121a2.58 2.58 0 0 0 2.2 1.048a2.909 2.909 0 0 0 2.695-3.04a7.912 7.912 0 0 0-.217-1.933a7.404 7.404 0 0 0-14.64 1.603a7.497 7.497 0 0 0 7.308 7.405s.549.05 1.167.035a15.803 15.803 0 0 0 8.475-2.528c.036-.025.072.025.048.061a12.44 12.44 0 0 1-9.69 3.963a8.744 8.744 0 0 1-8.9-8.972a9.049 9.049 0 0 1 3.635-7.247a8.863 8.863 0 0 1 5.229-1.726h2.813a7.915 7.915 0 0 0 5.839-2.578a.11.11 0 0 1 .059-.034a.112.112 0 0 1 .12.053a.113.113 0 0 1 .015.067a7.934 7.934 0 0 1-1.227 3.549a.107.107 0 0 0-.014.06a.11.11 0 0 0 .073.095a.109.109 0 0 0 .062.004a8.505 8.505 0 0 0 5.913-4.876a.155.155 0 0 1 .055-.053a.15.15 0 0 1 .147 0a.153.153 0 0 1 .054.053A10.779 10.779 0 0 1 23.834 8.1zM8.895 11.628a2.188 2.188 0 1 0 2.188 2.188v-2.042a.158.158 0 0 0-.15-.15z" fill="#5C2D91"/>
            </svg>
           My App
        </a>
    </div>
    `
}
export default Brand
```

Which override's the built-in `Brand` component to replace the Logo on the top-right of API Explorer, [Locode](/locode/) and the [Admin UI](/admin-ui) with the custom version below:

<div class="flex justify-center py-8">
    <a href="https://vue-vite-api.jamstacks.net/ui/">
        <img src="/img/pages/apiexplorer/brand-blazor-wasm.png" style="max-width:850px;border:1px solid rgb(229 231 235);">
    </a>
</div>

Although a less invasive option if you just want to use your own logo is to configure the `UiFeature` plugin to override the default `BrandIcon` as the other Jamstack templates do in their [Configure.AppHost.cs](https://github.com/NetCoreTemplates/nextjs/blob/main/api/MyApp/Configure.AppHost.cs):

```csharp
ConfigurePlugin<UiFeature>(feature => {
    feature.Info.BrandIcon.Uri = "/assets/img/logo.svg";
    feature.Info.BrandIcon.Cls = "inline-block w-8 h-8 mr-2";
});
```

<div class="flex justify-center py-8">
    <a href="https://vue-vite-api.jamstacks.net/ui/Register">
        <img src="/img/pages/apiexplorer/brand-vue-ssg.png" style="max-width:850px;border:1px solid rgb(229 231 235);">
    </a>
</div>

## Custom Form Layouts

Generated forms default to a two column layout, but this can be controlled using `FormLayout` for a specific operation.
The `appHost.ConfigureOperation<T>` method can be used to change the layout and order of the form used in API Explorer.

For example, a `CreateCustomer` operation by default has the following properties.

```csharp
[Route("/customers", "POST")]
public class CreateCustomers
    : IReturn<IdResponse>, IPost, ICreateDb<Customers>
{
    public string FirstName { get; set; }
    public string LastName { get; set; }
    public string Company { get; set; }
    public string Address { get; set; }
    public string City { get; set; }
    public string State { get; set; }
    public string Country { get; set; }
    public string PostalCode { get; set; }
    public string Phone { get; set; }
    public string Fax { get; set; }
    public string Email { get; set; }
    public long? SupportRepId { get; set; }
}
```

### Default Form UI

And is presented in API Explorer using the following generated form by default.

<a class="block my-8 p-4 rounded shadow hover:shadow-lg">
    <img src="/img/pages/apiexplorer/create-customer-default.png">
</a>

### Custom Form Layout

Customizing this layout using `ConfigureOperation`, we can control the placement and other attributed of each `InputInfo`.
When overriding the `FormLayout`, it is in the structure of Rows, then columns in the nested list. So grouping controls like `City`, `State` and `PostalCode` in the same row allows us to control the presentation.

```csharp
appHost.ConfigureOperation<CreateCustomers>(operation => operation.FormLayout = new() {
    Input.For<CreateCustomers>(x => x.FirstName,    c => c.FieldsPerRow(2)),
    Input.For<CreateCustomers>(x => x.LastName,     c => c.FieldsPerRow(2)),

    Input.For<CreateCustomers>(x => x.Email),
    Input.For<CreateCustomers>(x => x.Company),
    Input.For<CreateCustomers>(x => x.Address),

    Input.For<CreateCustomers>(x => x.City,         c => c.FieldsPerRow(3)),
    Input.For<CreateCustomers>(x => x.State,        c => c.FieldsPerRow(3)),
    Input.For<CreateCustomers>(x => x.PostalCode,   c => c.FieldsPerRow(3)),
    
    Input.For<CreateCustomers>(x => x.Country),
    
    Input.For<CreateCustomers>(x => x.Phone,        c => c.FieldsPerRow(2)),
    Input.For<CreateCustomers>(x => x.Fax,          c => c.FieldsPerRow(2)),

    Input.For<CreateCustomers>(x => x.SupportRepId),
});
```

Gives us the updated layout in API Explorer.

<a class="block my-8 p-4 rounded shadow hover:shadow-lg">
    <img src="/img/pages/apiexplorer/create-customer-custom-layout.png">
</a>

### Custom Input Controls

Each input field can be customized with client side visual and behavioural changes by using `InputInfo` when customizing `FormLayout`.

```csharp
Input.For<CreateCustomers>(x => x.Email, info => {
    info.Label = "Personal Email Address";
    info.Placeholder = "me@email.com";
    info.Type = "email";
}) 
```

Now our `label` and `placeholder` changes are visible and trying to submit a value without an `@` we get a client side warning.

<a class="block my-8 p-4 rounded shadow hover:shadow-lg">
    <img src="/img/pages/apiexplorer/create-customer-custom-input.png">
</a>

Values for `InputInfo` are merged with the `[Input]` attribute that can be used on Request DTO class properties.
This allows you to keep the default layout while still controlling `Input` options directly on your Request DTO class.

```csharp
public class CreateCustomers : IReturn<IdResponse>, IPost, ICreateDb<Customers>
{
    [Input(Placeholder = "me@email.com", Type = "email", Label = "Personal Email Address")]
    public string Email { get; set; }
}
```

### Register Form Layout

The built-in `RegistrationFeature` also uses a custom Form layout to mask its password fields:

```csharp
appHost.ConfigureOperation<Register>(op => op.FormLayout = new()
{
    Input.For<Register>(x => x.DisplayName,     x => x.Help = "Your first and last name"),
    Input.For<Register>(x => x.Email,           x => x.Type = Input.Types.Email),
    Input.For<Register>(x => x.Password,        x => x.Type = Input.Types.Password),
    Input.For<Register>(x => x.ConfirmPassword, x => x.Type = Input.Types.Password),
});
```

Which overrides the default Auto UI Form to use this custom layout:

<div class="flex justify-center py-8">
    <a href="https://vue-vite-api.jamstacks.net/ui/Register">
        <img src="/img/pages/apiexplorer/api-form-Register.png" style="max-width:850px;">
    </a>
</div>


# Admin UI
Source: https://docs.servicestack.net/admin-ui

The Admin UI contains a suite of Admin tools providing a number of productivity features ranging from Managing Users and DB Validation Rules to gaining unprecedented insights into Live running Apps with in-depth Request Logging & Profiling where you'll be able to observe your App's behavior in real-time.

The [Admin UI](/admin-ui) is built into all ServiceStack Apps, accessible to [Admin Users](/debugging#admin-role) from:

<div class="not-prose text-center pb-3">
    <h3 class="text-4xl text-indigo-800">/admin-ui</h3>
</div>

Which will launch the Admin UI:

<analytics-ui class="not-prose"></analytics-ui>

### Dashboard

On first access you're greeted with the Admin dashboard showing high-level overview stats on the number and type of APIs your App has as well as internal stats counters surfaced right on your Dashboard where they can provide valuable insights into the health of different features at a glance:

![](/img/pages/admin-ui/dashboard-features.png)

### Advertised features

As Admin is a capability-based UI it only shows the stats and features your App has enabled. To aid in discovery the dashboard now includes a light switch of available Admin features with a link to [Admin UI Feature Docs](/admin-ui-features), providing a summary of each Admin UI component and instructions on how to enable them.

### Admin UI Features

Explore the available Admin UIs to learn more about each of their capabilities:

### [Managing Users UI](/admin-ui-users)

Containing user management functionality for creating & modifying users, assigning Roles & Permissions, locking or updating passwords:

<a href="/admin-ui-users">
    <div class="block p-4 rounded shadow hover:shadow-lg">
        <img src="/img/pages/admin-ui/users.png">
    </div>
</a>

### [Profiling & Logging UI](/admin-ui-profiling)

Enables invaluable observability into your App, from being able to quickly inspect and browse incoming requests, to tracing their behavior:

<a href="/admin-ui-profiling">
    <div class="block p-4 rounded shadow hover:shadow-lg">
        <img src="/img/pages/admin-ui/admin-ui-logging.png">
    </div>
</a>

### [Redis Admin](/admin-ui-redis)

Manage your App's configured Redis Server, query & edit core Redis data types and execute custom redis commands:

<a href="/admin-ui-redis">
    <div class="block p-4 rounded shadow hover:shadow-lg">
        <img src="/img/pages/admin-ui/admin-ui-redis.png">
    </div>
</a>

### [Database Admin](/admin-ui-database)

Quickly browse and navigate your App's configured RDBMS schemas and tables:

<a href="/admin-ui-database">
    <div class="block p-4 rounded shadow hover:shadow-lg">
        <img src="/img/pages/admin-ui/admin-ui-database.png">
    </div>
</a>

### [DB Validation UI](/admin-ui-validation)

Leverages the existing Declarative Validation infrastructure to enable dynamically managing Request DTO Type and Property Validators from a RDBMS data source

<a href="/admin-ui-validation">
    <div class="block p-4 rounded shadow hover:shadow-lg">
        <img src="/img/pages/admin-ui/admin-ui-validation.png">
    </div>
</a>


### Feedback

The Admin UI was designed with room to grow. Please let us know what other features you would like to see on our [GitHub Discussions](https://github.com/ServiceStack/Discuss/discussions/2).


# Admin UI Analytics
Source: https://docs.servicestack.net/admin-ui-analytics

Comprehensive API Analytics is available to all ServiceStack Apps configured with [SQLite Request Logging](/sqlite-request-logs).

:::youtube kjLcm1llC5Y
In Depth and Interactive API Analytics available to all ASP .NET Core ServiceStack Apps!
:::

### Benefits of API Analytics

They provide deep and invaluable insight into your System API Usage, device distribution, its Users, API Keys and the 
IPs where most traffic generates:

- **Visibility:** Provides a clear, visual summary of complex log data, making it easier to understand API usage and performance at a glance.
- **Performance Monitoring:** Helps track key metrics like request volume and response times to ensure APIs are meeting performance expectations.
- **User Understanding:** Offers insights into how users (and bots) are interacting with the APIs (devices, browsers).
- **Troubleshooting:** Aids in quickly identifying trends, anomalies, or specific endpoints related to issues.
- **Resource Planning:** Understanding usage patterns helps in scaling infrastructure appropriately.
- **Security Insight:** Identifying bot traffic and unusual request patterns can be an early indicator of security concerns.
- **Interactive Analytics:** Analytics are also interactive where you're able to drill down to monitor the activity of individual APIs, Users, API Keys and IPs with links back to the request logs which the summary analytics are derived from.

### Getting Started

As they offer significant and valuable insights they're now built into all new ASP.NET Core IdentityAuth templates, 
existing .NET 8 IdentityAuth templates can enable it with: 

:::sh
x mix sqlitelogs
:::

.NET 8 Templates that are not configured to use [Endpoint Routing](/endpoint-routing)
and [ASP.NET Core IOC](/net-ioc) will need to explicitly register `SqliteRequestLogger`
as a singleton dependency in addition to configuring it on the `RequestLogsFeature` plugin:

```csharp
public class ConfigureRequestLogs : IHostingStartup
{
    public void Configure(IWebHostBuilder builder) => builder
        .ConfigureServices((context, services) =>
        {
            var logger = new SqliteRequestLogger();
            services.AddSingleton<IRequestLogger>(logger);
            
            services.AddPlugin(new RequestLogsFeature {
                RequestLogger = logger,
                EnableRequestBodyTracking = true,
                EnableErrorTracking = true
            });
            services.AddHostedService<RequestLogsHostedService>();

            if (context.HostingEnvironment.IsDevelopment())
            {
                services.AddPlugin(new ProfilingFeature());
            }
        });
}
```

## Analytics Admin UI

Once configured, [SQLite Request Logs](/sqlite-request-logs) enable a more feature rich Request Logging Admin UI which utilizes the full queryability of an AutoQueryGrid to filter, sort and export Request Logs. 

[![](/img/pages/admin-ui/sqlitelogs.webp)](/img/pages/admin-ui/sqlitelogs.webp)

### Rolling Monthly Request Logs

Benefits of using SQLite includes removing load from your App's primary database and being able to create naturally scalable and isolated Monthly databases on-the-fly which allow requests to be easily archived into managed file storage instead of a singular growing database.

## Analytics Overview

It also enables the new **Analytics** Admin UI in the sidebar which initially displays the API Analytics overview Dashboard:

[![](/img/pages/admin-ui/analytics-apis1.webp)](/img/pages/admin-ui/analytics-apis1.webp)

Different charts displayed on the dashboard include:

### Distribution Pie Charts

Lets you quickly understand the composition of your user base and traffic sources and the 
distribution of users across different web browsers, device types, and to identify the proportion of traffic coming from automated bots. 

### Requests per day Line Chart

Lets you monitor API usage trends and performance over time. It tracks the total number of API requests and the average response 
time day-by-day. You can easily spot trends like peak usage hours/days, identify sudden spikes or drops in traffic, 
and correlate request volume with API performance which is crucial for capacity planning and performance troubleshooting.

### API tag groups Pie Chart

Lets you understand the usage patterns across different functional categories of your APIs.
By grouping API requests based on assigned tags (like Security, Authentication, User Management, Tech, etc.), you get a 
high-level view of which *types* of functionalities are most frequently used or are generating the most load. 

### API Requests Bar Chart

Lets you identify the most and least frequently used specific API endpoints which ranks individual API endpoints by 
the number of requests they receive. This helps pinpoint:
 
- **Critical Endpoints:** The most heavily used APIs that require robust performance and monitoring.
- **Optimization Targets:** High-traffic endpoints that could benefit from performance optimization.
- **Underutilized Endpoints:** APIs that might be candidates for deprecation or require promotion.
- **Troubleshooting:** If performance issues arise (seen in the line chart), this helps narrow down which specific endpoint might be responsible.

[![](/img/pages/admin-ui/analytics-apis2.webp)](/img/pages/admin-ui/analytics-apis2.webp)

### Total Duration Bar Chart

Identifies which API endpoints consume the most *cumulative processing time* over the selected period.
Even if an API endpoint is relatively fast per call, if it's called extremely frequently, it can contribute significantly to overall server load.
Optimizing these can lead to significant savings in server resources (CPU, memory).

### Average Duration Bar Chart

Pinpoints which API endpoints are the slowest on a *per-request* basis. APIs at the top of this list are prime candidates 
for performance investigation and optimization, as they represent potential user-facing slowness or system bottlenecks.

### Requests by Duration Ranges Histogram

Provides an overview of the performance distribution for *all* API requests.
This chart shows how many requests fall into different speed buckets and helps you understand the overall responsiveness of your API system at a glance. 

## Individual API Analytics

Clicking on an API's bar chart displays a dedicated, detailed view of a single API endpoint's behavior, isolating its performance 
and usage patterns from the overall system metrics offering immediate insight into the endpoint's traffic volume and reliability.

[![](/img/pages/admin-ui/analytics-api.webp)](/img/pages/admin-ui/analytics-api.webp)

### Total Requests

Displays the total requests for an API during the selected month. It includes HTTP Status Breakdown which
provide **direct access to the filtered request logs**. This is a major benefit for **rapid troubleshooting**, allowing 
you to instantly view the specific log entries corresponding to successful requests or particular error codes for this API.

### Last Request Information

Provides immediate context on the most recent activity for this endpoint with *when* the last request occurred, 
the source **IP address** and device information to help understand recent usage and check if the endpoint is still active, 
or quickly investigate the very last interaction if needed.

### Duration Summary Table (Total, Min, Max)

Quantifies the performance characteristics specifically for this endpoint with the cumulative (Total) processing load, 
the best-case performance (Min), and the worst-case performance (Max) which is useful for identifying performance outliers.

### Duration Requests Histogram

Visualizes the performance distribution for this API.

### Top Users Bar Chart

Identifies which authenticated users are most frequently calling this API and relies on this endpoint the most.
This can be useful for identifying power users, potential API abuse by a specific user account, or understanding the impact of changes to this API on key users.

### Top IP Addresses Bar Chart

Shows which source IP addresses are generating the most traffic for this API.
Useful for identifying high-volume clients, specific servers interacting with this endpoint, or potentially malicious IPs.

## Users

The **Users** tab will display the top 100 Users who make the most API Requests and lets you click on a Users bar chart
to view their individual User analytics.

[![](/img/pages/admin-ui/analytics-users.webp)](/img/pages/admin-ui/analytics-users.webp)

### Individual User Analytics

Provides a comprehensive view of a single user's complete interaction history and behavior across all APIs they've accessed, 
shifting the focus from API performance to user experience and activity.

[![](/img/pages/admin-ui/analytics-user.webp)](/img/pages/admin-ui/analytics-user.webp)

### User Info & Total Requests

Identifies the user and quantifies their overall activity level. Clicking on their ID or Name will navigate to the Users Admin UI.
It also shows their success/error rate via the clickable status code links. This helps gauge user engagement and baseline activity.

### Last Request Information

Offers a snapshot of the user's most recent interaction for immediate context.
Knowing **when**, **what** API they called, from which **IP address**, using which **client** & **device** is valuable 
for support, identifying their last action or checking recent activity.

### HTTP Status Pie Chart

Visualizes the overall success and error rate specifically for this user's API requests.

### Performance & Request Body Summary Table

Quantifies the performance experienced by this user and the data they typically send.

### Duration Requests Histogram

Shows the distribution of response times for requests made by this user to help understand the typical performance this user experiences.

### Top APIs Bar Chart

Reveals which API endpoints this user interacts with most frequently and help understanding user behavior and which features they use most.

### Top IP Addresses Bar Chart

Identifies the primary network locations or devices the user connects from.

### User Admin UI Analytics

To assist in discoverability a snapshot of a Users Analytics is also visible in the Users Admin UI:

[![](/img/pages/admin-ui/analytics-user-adminui.webp)](/img/pages/admin-ui/analytics-user-adminui.webp)

Clicking on **View User Analytics** takes you to the Users Analytics page to access to the full Analytics features and navigation.

## API Keys

The **API Keys** tab will display the top 100 API Keys who make the most API Requests and lets you click on an API Key 
bar chart to view its individual API Key analytics.

[![](/img/pages/admin-ui/analytics-apikeys.webp)](/img/pages/admin-ui/analytics-apikeys.webp)

### Individual API Key Analytics

Provides comprehensive API Key analytics Similar to User Analytics but limited to the API Usage of a single API Key:

[![](/img/pages/admin-ui/analytics-apikey.webp)](/img/pages/admin-ui/analytics-apikey.webp)

## IPs

The **IP Addresses** tab will display the top 100 IPs that make the most API Requests. Click on an IP's
bar chart to view its individual analytics made from that IP Address.

[![](/img/pages/admin-ui/analytics-ips.webp)](/img/pages/admin-ui/analytics-ips.webp)

### Individual IP Analytics

Provides comprehensive IP Address analytics Similar to User Analytics but limited to the API Usage from a single IP Address:

[![](/img/pages/admin-ui/analytics-ip.webp)](/img/pages/admin-ui/analytics-ip.webp)

## Blocking User Agents

The insights from the Analytics showed us that our [pvq.app](https://pvq.app) was experiencing significant load from
AI bots and scrapers which was the primary cause of its high resource usage and detrimental load times for normal
user requests, so much so we've intervened to prevent these bots from scraping our site.

### Disallowing Bots in robots.txt

In an ideal world you would just need to instruct problematic bots not to scrape your site by adding them to [pvq.app/robots.txt](https://pvq.app/robots.txt), e.g:

```txt
User-agent: Googlebot
Allow: /
User-agent: Bingbot
Allow: /

User-agent: bytespider
Disallow: /
User-agent: gptbot
Disallow: /
User-agent: claudebot
Disallow: /
User-agent: amazonbot
Disallow: /
User-agent: mj12bot
Disallow: /
User-agent: semrushbot
Disallow: /
User-agent: dotbot
Disallow: /
User-agent: WhatsApp Bot
Disallow: /
User-agent: *
Disallow: /
```

### Disallowing Bot Requests

As this was not having an immediate effect we took a more forceful approach to implement a middleware to reject all
requests from disallowed bots from accessing our App which you can add to your own App with:

:::sh
x mix useragent-blocking
:::

This will allow you to configure which Bot User Agents you want to reject from accessing your site, e.g:

```csharp
services.Configure<UserAgentBlockingOptions>(options =>
{
    // Add user agents to block
    options.BlockedUserAgents.AddRange([
        "bytespider",
        "gptbot",
        "gptbot",
        "claudebot",
        "amazonbot",
        "imagesiftbot",
        "semrushbot",
        "dotbot",
        "semrushbot",
        "dataforseobot",
        "WhatsApp Bot",
        "HeadlessChrome",
        "PetalBot",
    ]);
    
    // Optional: Customize the response status code
    // options.BlockedStatusCode = StatusCodes.Status429TooManyRequests;
    
    // Optional: Customize the blocked message
    options.BlockedMessage = "This bot is not allowed to access our website";
});
```


# Identity User Admin Feature
Source: https://docs.servicestack.net/admin-ui-identity-users

::: info
When using **ServiceStack Auth** refer to [Admin Users UI](/admin-ui-users) instead
:::


## Registration

The Identity Auth Admin UI can be enabled when registering the `AuthFeature` Plugin by calling `AdminUsersFeature()`:

```csharp
public class ConfigureAuth : IHostingStartup
{
    public void Configure(IWebHostBuilder builder) => builder
        .ConfigureServices(services => {
            services.AddPlugin(new AuthFeature(IdentityAuth.For<ApplicationUser>(
                options => {
                    // options.SessionFactory = () => new CustomUserSession(); //optional
                    options.CredentialsAuth();
                    options.AdminUsersFeature();
                })));
        });
}
```

Which just like the ServiceStack Auth [Admin Users UI](/admin-ui-users) enables a
Admin UI that's only accessible to **Admin** Users for managing **Identity Auth** users at `/admin-ui/users`.

## User Search Results

Which displays a limited view of a User's info due to the minimal properties on the default `IdentityAuth` model:

<div>
    <img class="shadow" src="/img/pages/auth/identity/admin-ui-users-default.png">
</div>

### Custom Search Result Properties

These User Search results are customizable by specifying the `ApplicationUser` properties you want displayed instead:

```csharp
options.AdminUsersFeature(feature =>
{
    feature.QueryIdentityUserProperties =
    [
        nameof(ApplicationUser.Id),
        nameof(ApplicationUser.DisplayName),
        nameof(ApplicationUser.Email),
        nameof(ApplicationUser.UserName),
        nameof(ApplicationUser.LockoutEnd),
    ];
});
```

<div>
    <img class="shadow" src="/img/pages/auth/identity/admin-ui-users-custom.png">
</div>

### Custom Search Result Behavior

The default display Order of Users is also customizable:

```csharp
feature.DefaultOrderBy = nameof(ApplicationUser.DisplayName);
```

As well as the Search behavior which can be replaced to search any custom fields, e.g:

```csharp
feature.SearchUsersFilter = (q, query) =>
{
    var queryUpper = query.ToUpper();
    return q.Where(x =>
        x.DisplayName!.Contains(query) ||
        x.Id.Contains(queryUpper) ||
        x.NormalizedUserName!.Contains(queryUpper) ||
        x.NormalizedEmail!.Contains(queryUpper));
};
```

## Default Create and Edit Users Forms

The default Create and Edit Admin Users UI are also limited to editing the minimal `IdentityAuth` properties:

<div>
    <img class="shadow" src="/img/pages/auth/identity/admin-ui-users-create.png">
</div>

Whilst the Edit page includes standard features to lockout users, change user passwords and manage their roles:

<div>
    <img class="shadow" src="/img/pages/auth/identity/admin-ui-users-edit.png">
</div>

### Custom Create and Edit Forms

By default Users are locked out indefinitely, but this can also be changed to lock users out to a specific date, e.g:

```csharp
feature.ResolveLockoutDate = user => DateTimeOffset.Now.AddDays(7);
```

The forms editable fields can also be customized to include additional properties, e.g:

```csharp
feature.FormLayout =
[
    Input.For<ApplicationUser>(x => x.UserName, c => c.FieldsPerRow(2)),
    Input.For<ApplicationUser>(x => x.Email, c => { 
        c.Type = Input.Types.Email;
        c.FieldsPerRow(2); 
    }),
    Input.For<ApplicationUser>(x => x.FirstName, c => c.FieldsPerRow(2)),
    Input.For<ApplicationUser>(x => x.LastName, c => c.FieldsPerRow(2)),
    Input.For<ApplicationUser>(x => x.DisplayName, c => c.FieldsPerRow(2)),
    Input.For<ApplicationUser>(x => x.PhoneNumber, c =>
    {
        c.Type = Input.Types.Tel;
        c.FieldsPerRow(2); 
    }),
];
```

That can override the new `ApplicationUser` Model that's created and any Validation:

### Custom User Creation

```csharp
feature.CreateUser = () => new ApplicationUser { EmailConfirmed = true };
feature.CreateUserValidation = async (req, createUser) =>
{
    await IdentityAdminUsers.ValidateCreateUserAsync(req, createUser);
    var displayName = createUser.GetUserProperty(nameof(ApplicationUser.DisplayName));
    if (string.IsNullOrEmpty(displayName))
        throw new ArgumentNullException(nameof(AdminUserBase.DisplayName));
    return null;
};
```

<div>
    <img class="shadow" src="/img/pages/auth/identity/admin-ui-users-create-custom.png">
</div>

<div>
    <img class="py-8 px-12" src="/img/pages/auth/identity/admin-ui-users-edit-custom.png">
</div>

### Admin User Events

Should you need to, Admin User Events can use used to execute custom logic before and after creating, updating and 
deleting users, e.g:

```csharp
feature.OnBeforeCreateUser = (request, user) => { ... };
feature.OnAfterCreateUser  = (request, user) => { ... };
feature.OnBeforeUpdateUser = (request, user) => { ... };
feature.OnAfterUpdateUser  = (request, user) => { ... };
feature.OnBeforeDeleteUser = (request, userId) => { ... };
feature.OnAfterDeleteUser  = (request, userId) => { ... };
```

### IdentityAuth User Claims

The User Claim Management UI can be used to assign Claims to individual Users: 

![](/img/pages/admin-ui/identityauth-user-claims.webp)

## Validating Claims

::include admin-ui-claims-validation.md::


# Identity Roles &amp; Claims UI
Source: https://docs.servicestack.net/admin-ui-identity-roles

The Roles Admin UI is enabled when registering the [Admin Users UI](/admin-ui-identity-users#registration)
which enables management APIs and Admin UIs for managing Identity Auth Roles and Claims for both Users and Roles. 

Once registered it will be available from the **Roles** menu item in the Admin UI sidebar which can be used Add and Remove Application Roles:  

![](/img/pages/admin-ui/identityauth-roles.webp)

### Custom Application Roles

If your App uses an extended `IdentityRole` data model, it can be configured with:

```csharp
services.AddPlugin(
    new AuthFeature(IdentityAuth.For<ApplicationUser,ApplicationRole>(...)));
```

If it's also configured to use a different `PrimaryKey` type, it can be configured with: 

```csharp
services.AddPlugin(
    new AuthFeature(IdentityAuth.For<AppUser,AppRole,int>(...)));
```

### IdentityAuth Role Claims

The Edit Role Admin UI also supports Adding and Remove Claims for a Role, e.g:

![](/img/pages/admin-ui/identityauth-role-claims.webp)

Any Added or Removed Claims are only applied after clicking **Update Role**, likewise you can exit the UI without applying any changes by clicking **Cancel**.

### Behavior of Role Claims

Claims added to Roles have similar behavior to having Claims individually applied to all Users with that Role such that
when a User is Authenticated they're populated with all claims assigned to their Roles and their individual User Claims. 

## Validating Claims

::include admin-ui-claims-validation.md::


# User Admin Feature
Source: https://docs.servicestack.net/admin-ui-users

::: info
When using ASP.NET Core **Identity Auth** refer to [Identity Auth Admin Users UI](/admin-ui-identity-users) instead
:::

The User Admin Plugin is a lightweight API for providing user management functionality around Auth Repository APIs and enables remote programmatic access to manage your registered [User Auth Repository](/auth/authentication-and-authorization#user-auth-repository), featuring:

 - Works with existing `IUserAuthRepository` sync or async providers
 - Utilizes Progressive enhancement, e.g. search functionality utilizes `IQueryUserAuth` (if exists) performing a wildcard search over multiple fields, otherwise falls back to exact match on `UserName` or `Email`
 - Supports managing Auth Repositories utilizing custom `UserAuth` data models
 - Flexible UI options for customizing which fields to include in Search Results and Create/Edit UIs
 - Rich Metadata aggregating only App-specific Roles & Permissions defined in your App
 - User Events allow you to execute custom logic before & after each Created/Updated/Deleted User

### Installation

The `AdminUsersFeature` plugin contains no additional dependencies that at a minimum can be registered with:

```csharp
Plugins.Add(new AdminUsersFeature());
```

<div class="not-prose"> 
<a href="https://razor-pages.web-templates.io/admin-ui">
    <h3 class="text-center font-medium text-3xl mb-3">/admin-ui/users</h3>
    <div class="block p-4 rounded shadow hover:shadow-lg">
        <img src="/img/pages/admin-ui/users.png">
    </div>
</a>
</div>

::: info
An `IAuthRepository` is a required registered dependency to be able to use the `AdminUsersFeature` plugin.
:::

## Managing Users

By default, the Add and Edit Users forms contains the default layout of common properties in [UserAuth.cs](https://github.com/ServiceStack/ServiceStack/blob/master/src/ServiceStack/Auth/UserAuth.cs)

<div class="flex justify-center py-8">
    <a href="https://razor-pages.web-templates.io/admin-ui/users?edit=2">
        <img src="/img/pages/admin-ui/users-edit-default.png" style="max-width:800px;">
    </a>
</div>

## Customization

To customize this user interface to accommodate custom properties, the `UserFormLayout` needs to be overridden.

For example, below we have a custom `UserAuth` called `AppUser` with additional properties.

```csharp
// Custom User Table with extended Metadata properties
public class AppUser : UserAuth
{
    public Department Department { get; set; }
    public string? ProfileUrl { get; set; }
    public string? LastLoginIp { get; set; }

    public bool IsArchived { get; set; }
    public DateTime? ArchivedDate { get; set; }

    public DateTime? LastLoginDate { get; set; }
}

public enum Department
{
    None,
    Marketing,
    Accounts,
    Legal,
    HumanResources,
}
```

The `AdminUsersFeature` has multiple fiends that can be used to customize the UI including.

| Property Name             | Description                                                        |
|---------------------------|--------------------------------------------------------------------|
| `QueryUserAuthProperties` | Columns visible in query results for users.                        |
| `QueryMediaRules`         | Which columns *start* appearing at different screen sizes.         |
| `UserFormLayout`          | Control which fields are used for Create/Edit and their placement. |

### Custom User Form Layout

Similar to the [API Explorer](./api-explorer.md#formlayout) `FormLayout` customization, `UserFormLayout` is used to control placement and details about individual fields.

```csharp
appHost.Plugins.Add(new ServiceStack.Admin.AdminUsersFeature {
    // Show custom fields in Search Results
    QueryUserAuthProperties = new() {
        nameof(AppUser.Id),
        nameof(AppUser.Email),
        nameof(AppUser.DisplayName),
        nameof(AppUser.Department),
        nameof(AppUser.CreatedDate),
        nameof(AppUser.LastLoginDate),
    },

    QueryMediaRules = new()
    {
        MediaRules.ExtraSmall.Show<AppUser>(x => new { x.Id, x.Email, x.DisplayName }),
        MediaRules.Small.Show<AppUser>(x => x.Department),
    },

    // Add Custom Fields to Create/Edit User Forms
    FormLayout = new() {
        Input.For<AppUser>(x => x.Email, x => x.Type = Input.Types.Email),
        Input.For<AppUser>(x => x.DisplayName),
        Input.For<AppUser>(x => x.UserName),
        Input.For<AppUser>(x => x.Company,      c => c.FieldsPerRow(2)),
        Input.For<AppUser>(x => x.Department,   c => c.FieldsPerRow(2)),
        Input.For<AppUser>(x => x.PhoneNumber,  c => c.Type = Input.Types.Tel),
        Input.For<AppUser>(x => x.Nickname,     c => {
            c.Help = "Public alias (3-12 lower alpha numeric chars)";
            c.Pattern = "^[a-z][a-z0-9_.-]{3,12}$";
        }),
        Input.For<AppUser>(x => x.ProfileUrl,   c => c.Type = Input.Types.Url),
        Input.For<AppUser>(x => x.IsArchived,   c => c.FieldsPerRow(2)),
        Input.For<AppUser>(x => x.ArchivedDate, c => c.FieldsPerRow(2)),
    }
});
```

Enabling the use of custom properties as well as formatting for ease of use. `UserFormLayout` updates the `Create` and `Edit` screens in the Admin UI.

<div class="flex justify-center py-8">
    <a href="https://razor-pages.web-templates.io/admin-ui/users?edit=2">
        <img src="/img/pages/admin-ui/users-edit-custom.png" style="max-width:800px;">
    </a>
</div>

## Admin User Services

The Admin User back-end APIs themselves can also be used to manage users within your own Apps. 

All the Admin Users DTOs below contains everything needed to call its APIs from [.NET Service Clients](/csharp-client) which are all contained within **ServiceStack.Client** so no additional dependencies are needed.

The APIs are fairly straight-forward with each DTO containing on the bare minimum Typed properties with all other UserAuth fields you want updated in the `UserAuthProperties` Dictionary. Whilst all User result-sets are returned in an unstructured Object Dictionary.

```csharp
public abstract class AdminUserBase : IMeta
{
    public string UserName { get; set; }
    public string FirstName { get; set; }
    public string LastName { get; set; }
    public string DisplayName { get; set; }
    public string Email { get; set; }
    public string Password { get; set; }
    public string ProfileUrl { get; set; }
    public Dictionary<string, string> UserAuthProperties { get; set; }
    public Dictionary<string, string> Meta { get; set; }
}

public partial class AdminCreateUser : AdminUserBase, IPost, IReturn<AdminUserResponse>
{
    public List<string> Roles { get; set; }
    public List<string> Permissions { get; set; }
}

public partial class AdminUpdateUser : AdminUserBase, IPut, IReturn<AdminUserResponse>
{
    public string Id { get; set; }
    public bool? LockUser { get; set; }
    public bool? UnlockUser { get; set; }
    public List<string> AddRoles { get; set; }
    public List<string> RemoveRoles { get; set; }
    public List<string> AddPermissions { get; set; }
    public List<string> RemovePermissions { get; set; }
}

public partial class AdminGetUser : IGet, IReturn<AdminUserResponse>
{
    public string Id { get; set; }
}

public partial class AdminDeleteUser : IDelete, IReturn<AdminDeleteUserResponse>
{
    public string Id { get; set; }
}

public class AdminDeleteUserResponse : IHasResponseStatus
{
    public string Id { get; set; }
    public ResponseStatus ResponseStatus { get; set; }
}

public partial class AdminUserResponse : IHasResponseStatus
{
    public string Id { get; set; }
    public Dictionary<string,object> Result { get; set; }
    public ResponseStatus ResponseStatus { get; set; }
}

public partial class AdminQueryUsers : IGet, IReturn<AdminUsersResponse>
{
    public string Query { get; set; }
    public string OrderBy { get; set; }
    public int? Skip { get; set; }
    public int? Take { get; set; }
}

public class AdminUsersResponse : IHasResponseStatus
{
    public List<Dictionary<string,object>> Results { get; set; }
    public ResponseStatus ResponseStatus { get; set; }
}
```


# Redis Admin
Source: https://docs.servicestack.net/admin-ui-redis

The Redis Admin UI lets you manage your App's configured Redis Server with a user-friendly UX for managing core Redis data types, simple search functionality to quickly find Redis values, quick navigation between related values, first class support for JSON values and a flexible command interface and command history to inspect all previously run redis commands that's easily editable & rerun.

<lite-youtube class="w-full mx-4 my-4" width="560" height="315" videoid="AACZtTOcQbg" style="background-image: url('https://img.youtube.com/vi/AACZtTOcQbg/maxresdefault.jpg')"></lite-youtube>

It can be enabled by registering the `AdminRedisFeature` plugin:

```csharp
Plugins.Add(new AdminRedisFeature());
```

### Redis Stats on Dashboard

The [Admin Dashboard](/admin-ui#dashboard) contains valuable insight into monitoring the health of your App's redis usage with both client & server counters:

[![](/img/pages/admin-ui/admin-ui-redis-stats.png)](/admin-ui#dashboard)

::: tip
A description of each of these stats is available in the [Redis Stats docs](/redis/stats)
:::

## Info

The Redis Admin home page shows the output of the Redis [INFO](https://redis.io/commands/info/) command containing detailed information on the remote redis server:

![](/img/pages/admin-ui/admin-ui-redis.png)

By default it uses the App's configured database but can easily switch between Redis databases with the numbered Database dropdown.

### Modify Redis Connection

Changing your App's Redis Configuration at runtime can be enabled with:

```csharp
Plugins.Add(new AdminRedisFeature {
    ModifiableConnection = true
});
```

Which will linkify the Redis Connection string to open the **Change Connection** Dialog:

![](/img/pages/admin-ui/admin-ui-redis-connection.png)

Be aware this will change your App's Redis Connection at runtime to different redis server than what it was configured with, which can be useful if you have a warm stand-by Redis server you want to switch to without redeploying your App.

## Search

The Search tab is where you'll find the primary functionality for being able to quickly search through the Redis keyspace to find where you can create or edit new Redis [Strings](https://redis.io/docs/data-types/strings/), [Lists](https://redis.io/docs/data-types/lists/), [Sets](https://redis.io/docs/data-types/sets/), [Sorted Sets](https://redis.io/docs/data-types/sorted-sets/) and [Hashes](https://redis.io/docs/data-types/hashes/):

![](/img/pages/admin-ui/admin-ui-redis-new.png)

### Set

Selecting a Redis Data Type displays an optimized form you can use to create a new Value of that type:

![](/img/pages/admin-ui/admin-ui-redis-new-set.png)

Which you can view in a **Pretty** view where collections like sets are displayed in a formatted JS Array letting you can copy all its values:

![](/img/pages/admin-ui/admin-ui-redis-set-pretty.png)

A **Preview** mode displaying the results in a human-friendly table view:

![](/img/pages/admin-ui/admin-ui-redis-set-preview.png)

And an **Edit** mode where you can **add** and **delete** members:

![](/img/pages/admin-ui/admin-ui-redis-set-edit.png)

### String

The same functionality is available for all Data Types, whilst **Strings** contain first-class support for JSON strings in the **Pretty** tab:

![](/img/pages/admin-ui/admin-ui-redis-string-pretty.png)

**Preview**

![](/img/pages/admin-ui/admin-ui-redis-string-preview.png)

and **Edit** views where you can **indent JSON** when creating or editing JSON Strings:

![](/img/pages/admin-ui/admin-ui-redis-string-edit.png)

### Hash

Hashes have the same functionality as **SET** with an additional field to capture the hash entries value:

![](/img/pages/admin-ui/admin-ui-redis-hash-edit.png)

### Sorted Set

Whilst Sorted Sets maintains an extra numerical field to capture Sorted Set scores:

![](/img/pages/admin-ui/admin-ui-redis-zset-edit.png)

## Command

The Command tab gives you a flexible Command bar letting you run custom Redis commands against the selected database, including a Command History capturing all previously run commands that can be reselected to quickly edit & rerun commands:

![](/img/pages/admin-ui/admin-ui-redis-command.png)

By default Redis Admin blocks running dangerous and unsuitable commands from a Web interface which can be modified when registering the `AdminRedisFeature`, that by default prevents the commands below:

```csharp
Plugins.Add(new AdminRedisFeature {
    IllegalCommands = {
        "BLMOVE",
        "BLMPOP",
        "BLPOP",
        "BRPOP",
        "BRPOPLPUSH",
        "FLUSHDB",
        "FLUSHALL",
        "MONITOR",
    }
})
```

## Profile App Redis Usage

The command history maintains a log for all commands executed in the Redis Admin UI, you can inspect the redis commands executed by your Services with the [Redis Profiling](/admin-ui-profiling#redis-profiling) built into the [Admin Profiling UI](/admin-ui-profiling).

[![](/img/pages/admin-ui/profiling-redis-CommandAfter.png)](/admin-ui-profiling#redis-profiling)

## Feedback Welcome

We hope you'll find the Redis Admin feature useful, please let us know what other features you would like in [ServiceStack/Discuss](https://github.com/ServiceStack/Discuss/discussions).


# Database Admin
Source: https://docs.servicestack.net/admin-ui-database

The Database Admin UI lets you quickly browse and navigate your App's configured RDBMS schemas and tables:

<lite-youtube class="w-full mx-4 my-4" width="560" height="315" videoid="NZkeyuc_prg" style="background-image: url('https://img.youtube.com/vi/NZkeyuc_prg/maxresdefault.jpg')"></lite-youtube>

It can be enabled by registering the `AdminDatabaseFeature` plugin from [ServiceStack.Server](https://nuget.org/packages/ServiceStack.Server):

```csharp
Plugins.Add(new AdminDatabaseFeature());
```

Which without any additional configuration your App's configured databases will be listed on the home page, including their schemas, tables and any registered [named connections](/ormlite/getting-started#multiple-database-connections):

![](/img/pages/admin-ui/admin-ui-database.png)

Selecting a table takes us to a familiar tabular search results grid, similar in appearance and functionality to [Locode's Auto UI](/locode/):

![](/img/pages/admin-ui/admin-ui-database-table.png)

Whilst Locode gives you an entire Auto Management UI with all modifications performed through managed [AutoQuery APIs](/autoquery/), Database Admin instead focuses on providing a great readonly UX for querying & inspecting your App's data, starting with multiple views or quickly previewing every row in either **Pretty** JSON format:

<div class="block flex justify-center items-center">
    <img class="max-w-screen-md" src="/img/pages/admin-ui/admin-ui-database-table-pretty.png">
</div>

Where it will also let you copy every row in JSON format, whilst the **Preview** tab shows a friendlier view of the row's fields:

<div class="block flex justify-center items-center">
    <img class="max-w-screen-md" src="/img/pages/admin-ui/admin-ui-database-table-preview.png">
</div>

The tabular grid is highly personalizable where it lets change the query preferences and display fields for each table, where they're persisted in localStorage and preserved across browser restarts:

<div class="block flex justify-center items-center">
    <img class="max-w-screen-md" src="/img/pages/admin-ui/admin-ui-database-prefs.png">
</div>

Likewise so are the flexible filtering options allowing any number of filters per column:

<div class="block flex justify-center items-center">
    <img class="max-w-screen-md" src="/img/pages/admin-ui/admin-ui-database-filter.png">
</div>

The number and type of filters are readily available from the **Filters** dropdown showing all filters grouped under their column name where they're easily cleared per filter, column or using **Clear All** to clear all filters:

![](/img/pages/admin-ui/admin-ui-database-filters.png)

After you've finished customizing your table search view, you can export the data with the **Excel** button to download the results in [CSV Format](/csv-format) where it can be opened in your favorite spreadsheet, e.g:

![](/img/pages/admin-ui/admin-ui-database-excel.png)

Alternatively the **Copy URL** button can be used to generate the API data URL to return results in JSON:

<div class="block flex justify-center items-center">
    <img class="max-w-screen-md" src="/img/pages/admin-ui/admin-ui-database-api-url.png">
</div>

## Database Admin Customizations

Some customizations is available on the `AdminDatabaseFeature` plugin where you can control the maximum size of resultsets returned and you can use the `DatabaseFilter` to control which databases and schemas are displayed as well as changing the labels shown by setting their `Alias` properties, e.g:

```csharp
Plugins.Add(new AdminDatabaseFeature {
    QueryLimit = 100,
    DatabasesFilter = dbs => {
        foreach (var db in dbs) 
        {
            if (db.Name == "main")
            {
                db.Alias = "Northwind";
                db.Schemas[0].Alias = "Traders";
            }
            else if (db.Name == "chinook")
            {
                db.Alias = "Chinook";
                db.Schemas[0].Alias = "Music";
            }
        }
    },
});
```

## Feedback Welcome

We hope you'll find the Database Admin feature useful, please let us know what other features you would like in [ServiceStack/Discuss](https://github.com/ServiceStack/Discuss/discussions).


# Admin UI Validation
Source: https://docs.servicestack.net/admin-ui-validation

The DB Validation feature leverages the existing [Declarative Validation](/declarative-validation) infrastructure where it enables dynamically managing Request DTO Type and Property Validators from a RDBMS data source which immediately takes effect at runtime and can be optionally cached where they'll only need to be re-hydrated from the database after modification.

<lite-youtube class="w-full mx-4 my-4" width="560" height="315" videoid="W5OJAlOxH98" style="background-image: url('https://img.youtube.com/vi/W5OJAlOxH98/maxresdefault.jpg')"></lite-youtube>

This feature can be easily added to existing host projects with the [mix](/mix-tool) command:

:::sh
x mix validation-source
:::

Which will add the [Modular Startup](/modular-startup) validation configuration to your project, utilizing your existing configured database:

```csharp
[assembly: HostingStartup(typeof(MyApp.ConfigureValidation))]

namespace MyApp;

public class ConfigureValidation : IHostingStartup
{
    // Add support for dynamically generated db rules
    public void Configure(IWebHostBuilder builder) => builder
        .ConfigureServices(services => services.AddSingleton<IValidationSource>(c =>
            new OrmLiteValidationSource(c.Resolve<IDbConnectionFactory>(), HostContext.LocalCache)))
        .ConfigureAppHost(appHost => {
            // Create `ValidationRule` table if it doesn't exist in AppHost.Configure() or Modular Startup
            appHost.Resolve<IValidationSource>().InitSchema();
        });
}
```

Which the built-in [Validation Feature](/validation.html#validation-feature) detects before registering the `GetValidationRules` and `ModifyValidationRules` management APIs and enables the DB Validation Admin UI:

<div class="block p-4 rounded shadow">
    <img src="/img/pages/admin-ui/validation-empty.png">
</div>

### Pre-populating Validation Rules

A minimum set of validation rules can be enforced by adding them on Startup, e.g:

```csharp
var validationSource = container.Resolve<IValidationSource>();
validationSource.InitSchema();
validationSource.SaveValidationRules(new List<ValidateRule> {
    new ValidateRule { Type=nameof(CreateTable), Validator = "NoRefTableReferences" },
    new ValidateRule { Type=nameof(MyRequest), Field=nameof(MyRequest.LastName), Validator = "NotNull" },
    new ValidateRule { Type=nameof(MyRequest), Field=nameof(MyRequest.Age), Validator = "InclusiveBetween(13,100)" },
});
```

This can also be used to support alternative data sources by pre-populating validation rules in an `MemoryValidationSource`, although the recommendation would be to implement [IValidationSourceAdmin](https://github.com/ServiceStack/ServiceStack/blob/main/ServiceStack/src/ServiceStack.Interfaces/ValidationRule.cs) to get the full features of the Admin Validation UI.

### Validation UI

We can start adding validation rules after selecting the API we want to add them to, tag groups provide a quick view popup allowing APIs to be selected with just a mouse, whilst groups with a large number of APIs can benefit from the Autocomplete textbox results filter.

<div class="block p-4 rounded shadow">
    <img src="/img/pages/admin-ui/validation-category.png">
</div>

The quick links help navigating between related AutoQuery APIs that allows jumping between different APIs with the same Data Model.

In the validation editor you'll be able to create **Type** and **Property** Validation Rules that either make use of an existing **Validator** or you can enter a custom [#Script](https://sharpscript.net) expression that validates to `true`. The DB Validationo UI is smart and will list all built-in and Custom Script Methods returning `ITypeValidator` or `IPropertyValidator` that's registered in the remote instance. The pre-defined list of validators are displayed in a list of "quick pick" buttons that enables fast adding/editing of validation rules.

### Verified Rules

The `ModifyValidationRules` API used to save validation rules performs a number of checks to ensure any Validation rules are accurate including executing the validator to make sure it returns the appropriate validator type and checking the syntax on any **Script** validation rules to ensure it's valid.

<div class="block p-4 rounded shadow">
    <img src="/img/pages/admin-ui/validation-category-CategoryName.png">
</div>

<div class="mt-4 block p-4 rounded shadow">
    <img src="/img/pages/admin-ui/validation-category-Type.png">
</div>


The `ModifyValidationRules` back-end API also takes care of invalidating the validation rule cache so that any saved Validators are immediately applied. 

Despite being sourced from a DB, after the first access the validation rules are cached in memory where they'd have similar performance profile to validators declaratively added on Request DTOs in code.

After you add your validation rules they'll be immediately enforced when calling the API, e.g. in [API Explorer](/api-explorer) or [Locode](/locode/). Be mindful of what Validation Rule you're adding to which DTO, e.g. a validation rule added to **CreateCategory** API will **only be applied** when **creating** entities, e,g. not for full entity or partial field updates.

<div class="mt-4 block p-4 rounded shadow">
    <img src="/img/pages/admin-ui/validation-category-create.png">
</div>


# Logging &amp; Profiling UI
Source: https://docs.servicestack.net/admin-ui-profiling

The Request Logging & Profiling UIs bring an invaluable new level of observability into your App, from being able to quickly inspect and browse incoming requests, to tracing their behavior from their generated events in the [Diagnostic Source](https://docs.microsoft.com/en-us/dotnet/api/system.diagnostics.diagnosticsource?view=net-6.0) capabilities added all throughout ServiceStack, which both power the new UIs and enables new introspectability from code where you can now to tap in to inspect & debug when each diagnostic event occurs.

<lite-youtube class="w-full mx-4 my-4" width="560" height="315" videoid="LgQHTSHSk1g" style="background-image: url('https://img.youtube.com/vi/LgQHTSHSk1g/maxresdefault.jpg')"></lite-youtube>

The quickest way to enable access to these new features is to [mix](/mix-tool) in the profiling configuration:

::: sh 
x mix profiling
:::

Which will add the [Modular Startup](/modular-startup) configuration to your Host project that registers both Request Logging & Profiling features when running your App in [DebugMode](/debugging#debugmode) (i.e. Development):

```csharp
public class ConfigureProfiling : IHostingStartup
{
    public void Configure(IWebHostBuilder builder) => builder
        .ConfigureServices((context, services) => {
            if (context.HostingEnvironment.IsDevelopment())
            {
                services.AddPlugin(new ProfilingFeature
                {
                    IncludeStackTrace = true,
                });
            }
        });
}
```

Whilst Request Logs can be added with:

::: sh 
x mix requestlogs
:::

Or if you prefer to store Request Logs in an SQLite database then use the following command:

::: sh 
x mix sqlitelogs
:::


The default configuration looks at providing useful information during development, where the response request bodies are captured in the Request Logger and the StackTrace is captured on the important events where they can be useful.

### Configuration

Depending on your App you'll want to change these defaults, e.g. if you're persisting the request logs using the [CSV Request Logger](/request-logger#csv-request-logger) or [Redis Request Logger](/request-logger#redis-request-logger) it may not be feasible to **capture all API responses** if they're very large.

If enabled, **StackTraces** are captured in these important events:
 - **ServiceStack:** Before a Service Gateway Request is sent
 - **OrmLite:** Opening a connection or rolling back a transaction
 - **Redis:** Opening a connection, auto retrying a failed command, renting & returning clients from a redis manager pool

The latter of which is useful when resolving [concurrent usage issues](/redis/troubleshooting).

As it adds overhead, profiling should only be added when used, e.g. during development or when needing to debug production issues. Although you may always want to capture request logs depending on how important it is to maintain an audit of completed API requests. Should it be needed, both Logging & Profiling plugins offer several configuration options to control the type, info & events captured.

Whichever features you have registered will dynamically appear in the Admin UI's sidebar for quick navigation:

![](/img/pages/admin-ui/admin-ui-nav.png)

### Request Logging UI

Clicking on **Logging** navigates to the Request Logging UI which displays each API request processed in a grid of useful summary information showing high-level information for each HTTP API request:

![](/img/pages/admin-ui/logging-splash.png)

This screenshot shows an example of a non-authenticated user navigating to a protected page before signing in then querying and submitting a new Booking in the [AutoQuery CRUD Bookings Demo](/autoquery/crud-bookings) using [Locode's](/locode/) Auto UI, in which we can see error API Responses are highlighted in **red** and redirects highlighted in **yellow**.

The top navigation controls which results are displayed with:
 - **Has Errors** - Show only requests with errors
 - **Has Response** - Show only requests with response bodies
 - **Reset Filters Icon** - Clear all filters (ESC)
 - **Left/Right Icons** - Navigate to previous/next pages (LEFT/RIGHT)
 - **Refresh Icon** - Reload the latest results

This same user workflow is also captured in the Profiling UI in much finer granularity, capturing all the events performed by APIs:

![](/img/pages/admin-ui/profiling-splash.png)

Clicking on an entry previews it in more detail, e.g. clicking on the first **/api/QueryBookings** will show the API Request and Response made:

<div class="block flex justify-center items-center">
    <img class="max-w-screen-md" src="/img/pages/admin-ui/logging-QueryBookings.png">
</div>

By default it shows the Request and Response DTOs in JSON, but clicking on preview often shows a more human-friendly view:

<div class="block flex justify-center items-center">
    <img class="max-w-screen-md" src="/img/pages/admin-ui/logging-QueryBookings-preview.png">
</div>

A useful feature from having a dedicated UX-friendly UI is enabling quick navigation where each **blue** link will display results filtered to all matching requests, whilst the **trace request** link will navigate to the Profiling UI showing all diagnostic events performed within that request.

### Inspect Cookies and JWT Tokens

In addition to Request & Response DTOs, the Logging UI also shows all captured HTTP information including HTTP Request Headers with any Cookies being extracted into its own view for better readability as well as decoded JWT payload from the **ss-tok** cookie when using [JWT Auth](/auth/jwt-authprovider) with non-encrypted JWT defaults.

<div class="block flex justify-center items-center">
    <img class="max-w-screen-md" src="/img/pages/admin-ui/logging-http-details.png">
</div>

Lets now take a look at the failed **CreateBooking** request to see what went wrong:

<div class="block flex justify-center items-center">
    <img class="max-w-screen-md" src="/img/pages/admin-ui/logging-CreateBooking-validation.png">
</div>

Ok, so the Admin User (identified from JWT info) tried to create an empty booking which was rejected by its server declarative validation rules which sees these context validation errors surfaced into Locode's UI:

<div class="block flex justify-center items-center">
    <img class="max-w-screen-md" src="/img/pages/locode/CreateBooking-invalid.png">
</div>

We can then see this was quickly rectified in the next request with a successful Booking submitted:

<div class="block flex justify-center items-center">
    <img class="max-w-screen-md" src="/img/pages/admin-ui/logging-CreateBooking.png">
</div>

Clicking on **trace request** we can see all the diagnostic events performed in this API request within the **RequestBefore** and **RequestAfter** events which took **0.07s** to complete.

## Profiling UI

Following diagnostic conventions you'll typically see 2 entries for each event, created before and after each action, measuring the duration and capturing the last event before any error occurred.

![](/img/pages/admin-ui/profiling-CreateBooking-trace.png)

### SQL Profiling

Clicking on an entry will show more useful contextual information captured for each event, e.g. if you click on OrmLite's **CommandAfter** event you'll be able to see the generated SQL + Params executed by OrmLite:

<div class="block flex justify-center items-center">
    <img class="max-w-screen-md" src="/img/pages/admin-ui/profiling-CreateBooking-CommandAfter.png">
</div>

The profiling detail view also contains **blue** links to filter matching diagnostic events and showing useful information like the **Thread**, **User** this command was executed by as well as the **duration** and **timestamp** when it occurred.

### Redis Profiling

Redis simpler commands are captured in a list of arguments:

<div class="block flex justify-center items-center">
    <img class="max-w-screen-md" src="/img/pages/admin-ui/profiling-redis-CommandAfter.png">
</div>

### Purchase API Events Example

Surfacing the high-level events of your service implementations provides a new observability perspective that's harder to infer from trying to follow the details in the code. 

For example our [Order Page](https://account.servicestack.net/buy/BUS) generated over **150+ events** capturing all the SQL commands to store order, subscription, customer, payment information and generated License and Order confirmation emails, HttpClient integration requests with Stripe and MQ requests for sending emails in a [Background MQ Worker thread](/background-mq).

![](/img/pages/admin-ui/profiling-servicestack-buy1.png)

### HttpClient Profiling

HttpClient profiling is implemented a little differently then other events in that it builds on the existing HttpClient diagnostic events so it's able to capture general usage of .NET's HttpClient, which is how it's able to capture our [integration with Stripe](/stripe):

<div class="block flex justify-center items-center">
    <img class="max-w-screen-md" src="/img/pages/admin-ui/profiling-servicestack-client-stripe.png">
</div>

### JsonApiClient Profiling

Although we're able to provide richer profiling for our .NET 6+ [JsonApiClient](/csharp-client#jsonapiclient) which has access to typed Request DTOs for submitting API Requests:

<div class="block flex justify-center items-center">
    <img class="max-w-screen-md" src="/img/pages/admin-ui/profiling-client-api-request.png">
</div>

As well as Response DTOs returned in API Responses:

<div class="block flex justify-center items-center">
    <img class="max-w-screen-md" src="/img/pages/admin-ui/profiling-client-api-response.png">
</div>

We also can examine API Error responses in richer detail, e.g:

<div class="block flex justify-center items-center">
    <img class="max-w-screen-md" src="/img/pages/admin-ui/profiling-client-api-error.png">
</div>

### MQ Profiling

Since they execute APIs on an entirely different endpoint and worker threads, MQ Requests are tracked independently from HTTP APIs starting their own diagnostic Activity which enables being able to trace all events generated from an MQ Request. Here's an example used to handle sending customer emails:

<div class="block flex justify-center items-center">
    <img class="max-w-screen-md" src="/img/pages/admin-ui/profiling-MqRequestBefore.png">
</div>

### Service Gateway Profiling

The [Service Gateway](/service-gateway) leverages ServiceStack's message-based design to enable loosely-coupled service integrations enabling systems to split into Microservices without needing to change any of the internal services consuming them. As they're not RPC invocations their messages are introspectable and can be observed in the Profiling UI:

<div class="block flex justify-center items-center">
    <img class="max-w-screen-md" src="/img/pages/admin-ui/profiling-gateway.png">
</div>

### Profile Custom Info

We've made it easy to add a custom tracking field with the same functionality as the primary fields where they can be sorted and filtered. This could be used to attach a **Tenant Id** to the profiling information by providing a Label and Resolver function to resolve it, e.g:

```csharp
new ProfilingFeature {
    TagLabel = "Tenant",
    TagResolver = req => MyResolveTenant(req),
}
```

Where it will be displayed in all profiling results, e.g:

![](/img/pages/admin-ui/profiling-tenant-summary.png)

::: tip
The number and order of fields can be customized in `SummaryFields` collection in `ProfilingFeature`
:::

This custom info also appears in the detail page as a link which can be used to filter events with the same tenant id:

<div class="block flex justify-center items-center">
    <img class="max-w-screen-md" src="/img/pages/admin-ui/profiling-tenant-detail.png">
</div>

### Profile Custom Metadata

You're also able to capture custom information for different events and have them appear in the detail page, e.g:

```csharp
new ProfilingFeature {
    DiagnosticEntryFilter = (entry, evt) => {
        if (evt is RequestDiagnosticEvent requestEvent)
        {
            var req = requestEvent.Request;
            entry.Meta = new() {
                ["RemoteIp"] = req.RemoteIp,
                ["Referrer"] = req.UrlReferrer?.ToString(),
                ["Language"] = req.GetHeader(HttpHeaders.AcceptLanguage),
            };
        }
    },
}
```

Where it will be populated in the **Meta** section arguments:

<div class="block flex justify-center items-center">
    <img class="max-w-screen-md" src="/img/pages/admin-ui/profiling-custom-meta.png">
</div>

### Access Diagnostic Events in Code

In addition to powering the profiling UI, the diagnostic events added throughout ServiceStack can be observed in code to tap in and inspect when these diagnostic events occur. It follows the standard Diagnostic Source model where you specify which listeners you want observed in `OnNext(DiagnosticListener)` that you can then access in `OnNext(KeyValuePair<string,object>)`.

Microsoft's Diagnostic Events like HttpClient uses anonymous classes making them unnecessarily difficult to access, which can be made easier by using our [Reflection Utils ToObjectDictionary()](/reflection-utils#converting-instances-from-an-object-dictionary).

As they offer better utility, we've opted to use idiomatic strong types and string constants instead where they're better accessible from C#. 

You can use this skeleton class for a quick way to get started showing how to subscribe to all ServiceStack Diagnostic Sources and the event names and types to handle all profiling events:

```csharp
// Register your Diagnostic Observer
var observer = new MyDiagnosticObserver();
var subscription = DiagnosticListener.AllListeners.Subscribe(observer);

public sealed class MyDiagnosticObserver : 
    IObserver<DiagnosticListener>, 
    IObserver<KeyValuePair<string, object>>
{
    private readonly List<IDisposable> subscriptions = new();

    /* Specify which Profiling Events you want to observe */
    void IObserver<DiagnosticListener>.OnNext(DiagnosticListener diagnosticListener)
    {
        if (diagnosticListener.Name is Diagnostics.Listeners.ServiceStack         
         || diagnosticListener.Name is Diagnostics.Listeners.OrmLite
         || diagnosticListener.Name is Diagnostics.Listeners.Redis
         || diagnosticListener.Name is Diagnostics.Listeners.Client
         || diagnosticListener.Name is Diagnostics.Listeners.HttpClient)
        {
            var subscription = diagnosticListener.Subscribe(this);
            subscriptions.Add(subscription);
        }
    }

    /* Handle Profiling Events */
    public void OnNext(KeyValuePair<string, object> kvp)
    {
        /** ServiceStack */
        /*** Request */
        if (kvp.Key == Diagnostics.Events.ServiceStack.WriteRequestBefore && kvp.Value is RequestDiagnosticEvent reqBefore) { /*...*/ }
        if (kvp.Key == Diagnostics.Events.ServiceStack.WriteRequestAfter && kvp.Value is RequestDiagnosticEvent reqAfter) { /*...*/ }
        if (kvp.Key == Diagnostics.Events.ServiceStack.WriteRequestError && kvp.Value is RequestDiagnosticEvent reqError) { /*...*/ }
        
        /*** Gateway */
        if (kvp.Key == Diagnostics.Events.ServiceStack.WriteGatewayBefore && kvp.Value is RequestDiagnosticEvent gatewayBefore) { /*...*/ }
        if (kvp.Key == Diagnostics.Events.ServiceStack.WriteGatewayAfter && kvp.Value is RequestDiagnosticEvent gatewayAfter) { /*...*/ }
        if (kvp.Key == Diagnostics.Events.ServiceStack.WriteGatewayError && kvp.Value is RequestDiagnosticEvent gatewayError) { /*...*/ }
        
        /*** MQ */
        if (kvp.Key == Diagnostics.Events.ServiceStack.WriteMqRequestBefore && kvp.Value is MqRequestDiagnosticEvent mqReqBefore) { /*...*/ }
        if (kvp.Key == Diagnostics.Events.ServiceStack.WriteMqRequestAfter && kvp.Value is MqRequestDiagnosticEvent mqReqAfter) { /*...*/ }
        if (kvp.Key == Diagnostics.Events.ServiceStack.WriteMqRequestError && kvp.Value is MqRequestDiagnosticEvent mqReqError) { /*...*/ }
        if (kvp.Key == Diagnostics.Events.ServiceStack.WriteMqRequestPublish && kvp.Value is MqRequestDiagnosticEvent mqReqPublish) { /*...*/ }
        
        /** Client */    
        if (kvp.Key == Diagnostics.Events.Client.WriteRequestBefore && kvp.Value is HttpClientDiagnosticEvent clientBefore) { /*...*/ }
        if (kvp.Key == Diagnostics.Events.Client.WriteRequestAfter && kvp.Value is HttpClientDiagnosticEvent clientAfter) { /*...*/ }
        if (kvp.Key == Diagnostics.Events.Client.WriteRequestError && kvp.Value is HttpClientDiagnosticEvent clientError) { /*...*/ }
        
        /** HttpClient */
        if (kvp.Key == Diagnostics.Events.HttpClient.OutStart)
        {
            var obj = kvp.Value.ToObjectDictionary();
        }
        if (kvp.Key == Diagnostics.Events.HttpClient.Request)
        {
            var obj = kvp.Value.ToObjectDictionary();
        }
        if (kvp.Key == Diagnostics.Events.HttpClient.OutStop)
        {
             var obj = kvp.Value.ToObjectDictionary();
        }
        if (kvp.Key == Diagnostics.Events.HttpClient.Response)
        {
            var obj = kvp.Value.ToObjectDictionary();
        }

        /** OrmLite */
        if (kvp.Key == Diagnostics.Events.OrmLite.WriteCommandBefore && kvp.Value is OrmLiteDiagnosticEvent dbBefore) { /*...*/ }
        if (kvp.Key == Diagnostics.Events.OrmLite.WriteCommandAfter && kvp.Value is OrmLiteDiagnosticEvent dbAfter) { /*...*/ }
        if (kvp.Key == Diagnostics.Events.OrmLite.WriteCommandError && kvp.Value is OrmLiteDiagnosticEvent dbError) { /*...*/ }
        
        /*** OrmLite Connections */
        if (kvp.Key == Diagnostics.Events.OrmLite.WriteConnectionOpenBefore && kvp.Value is OrmLiteDiagnosticEvent dbOpenBefore) { /*...*/ }
        if (kvp.Key == Diagnostics.Events.OrmLite.WriteConnectionOpenAfter && kvp.Value is OrmLiteDiagnosticEvent dbOpenAfter) { /*...*/ }
        if (kvp.Key == Diagnostics.Events.OrmLite.WriteConnectionOpenError && kvp.Value is OrmLiteDiagnosticEvent dbOpenError) { /*...*/ }        
        if (kvp.Key == Diagnostics.Events.OrmLite.WriteConnectionCloseBefore && kvp.Value is OrmLiteDiagnosticEvent dbCloseBefore) { /*...*/ }
        if (kvp.Key == Diagnostics.Events.OrmLite.WriteConnectionCloseAfter && kvp.Value is OrmLiteDiagnosticEvent dbCloseAfter) { /*...*/ }
        if (kvp.Key == Diagnostics.Events.OrmLite.WriteConnectionCloseError && kvp.Value is OrmLiteDiagnosticEvent dbCloseError) { /*...*/ }        
        
        /*** OrmLite Transactions */
        if (kvp.Key == Diagnostics.Events.OrmLite.WriteTransactionOpen && kvp.Value is OrmLiteDiagnosticEvent commitOpen) { /*...*/ }
        if (kvp.Key == Diagnostics.Events.OrmLite.WriteTransactionCommitBefore && kvp.Value is OrmLiteDiagnosticEvent commitBefore) { /*...*/ }
        if (kvp.Key == Diagnostics.Events.OrmLite.WriteTransactionCommitAfter && kvp.Value is OrmLiteDiagnosticEvent commitAfter) { /*...*/ }
        if (kvp.Key == Diagnostics.Events.OrmLite.WriteTransactionCommitError && kvp.Value is OrmLiteDiagnosticEvent commitError) { /*...*/ }
        if (kvp.Key == Diagnostics.Events.OrmLite.WriteTransactionRollbackBefore && kvp.Value is OrmLiteDiagnosticEvent rollbackBefore) { /*...*/ }
        if (kvp.Key == Diagnostics.Events.OrmLite.WriteTransactionRollbackAfter && kvp.Value is OrmLiteDiagnosticEvent rollbackAfter) { /*...*/ }
        if (kvp.Key == Diagnostics.Events.OrmLite.WriteTransactionRollbackError && kvp.Value is OrmLiteDiagnosticEvent rollbackError) { /*...*/ }

        /** Redis */
        if (kvp.Key == Diagnostics.Events.Redis.WriteCommandBefore && kvp.Value is RedisDiagnosticEvent redisBefore) { /*...*/ }
        if (kvp.Key == Diagnostics.Events.Redis.WriteCommandRetry && kvp.Value is RedisDiagnosticEvent redisRetry) { /*...*/ }
        if (kvp.Key == Diagnostics.Events.Redis.WriteCommandAfter && kvp.Value is RedisDiagnosticEvent redisAfter) { /*...*/ }
        if (kvp.Key == Diagnostics.Events.Redis.WriteCommandError && kvp.Value is RedisDiagnosticEvent redisError) { /*...*/ }        
        
        /*** Redis Connections */
        if (kvp.Key == Diagnostics.Events.Redis.WriteConnectionOpenBefore && kvp.Value is RedisDiagnosticEvent redisOpenBefore) { /*...*/ }
        if (kvp.Key == Diagnostics.Events.Redis.WriteConnectionOpenAfter && kvp.Value is RedisDiagnosticEvent redisOpenAfter) { /*...*/ }
        if (kvp.Key == Diagnostics.Events.Redis.WriteConnectionOpenError && kvp.Value is RedisDiagnosticEvent redisOpenError) { /*...*/ }        
        if (kvp.Key == Diagnostics.Events.Redis.WriteConnectionCloseBefore && kvp.Value is RedisDiagnosticEvent redisCloseBefore) { /*...*/ }
        if (kvp.Key == Diagnostics.Events.Redis.WriteConnectionCloseAfter && kvp.Value is RedisDiagnosticEvent redisCloseAfter) { /*...*/ }
        if (kvp.Key == Diagnostics.Events.Redis.WriteConnectionCloseError && kvp.Value is RedisDiagnosticEvent redisCloseError) { /*...*/ }        
        
        /*** Redis Pools */
        if (kvp.Key == Diagnostics.Events.Redis.WritePoolRent && kvp.Value is RedisDiagnosticEvent redisPoolBefore) { /*...*/ }
        if (kvp.Key == Diagnostics.Events.Redis.WritePoolReturn && kvp.Value is RedisDiagnosticEvent redisPoolAfter) { /*...*/ }
    }

    void IObserver<DiagnosticListener>.OnCompleted()
    {
        subscriptions.ForEach(x => x.Dispose());
        subscriptions.Clear();
    }
    public void OnCompleted() {}
    void IObserver<DiagnosticListener>.OnError(Exception error) {}
    public void OnError(Exception error) {}
}
```

### Request Logs Configuration

The [Request Logs](/request-logger) feature has a number of configuration options controlling which requests are logged and the level of logging captured about them.

```csharp
class RequestLogsFeature 
{
    // Limit API access to users in role
    string AccessRole = RoleNames.Admin;

    // RequestLogs service Route, default is /requestlogs
    string AtRestPath = "/requestlogs";

    // Size of memory logger circular buffer
    int? Capacity;

    // Turn On/Off Session Tracking
    bool EnableSessionTracking;

    // Turn On/Off Logging of Raw Request Body, default is Off
    bool EnableRequestBodyTracking;

    // Turn On/Off Raw Request Body Tracking per-request
    Func<IRequest, bool> RequestBodyTrackingFilter;

    // Turn On/Off Tracking of Responses
    bool EnableResponseTracking = false;

    // Turn On/Off Tracking of Responses per-request
    Func<IRequest, bool> ResponseTrackingFilter;
    
    // Turn On/Off Tracking of Exceptions
    bool EnableErrorTracking = true;

    // Don't log matching requests
    Func<IRequest, bool> SkipLogging;

    // Change the RequestLogger provider. Default is InMemoryRollingRequestLogger
    IRequestLogger RequestLogger;

    // Don't log requests of these types. By default RequestLog's are excluded
    Type[] ExcludeRequestDtoTypes;

    // Don't log request body's for services with sensitive information.
    // By default Auth and Registration requests are hidden.
    Type[] HideRequestBodyForRequestDtoTypes;
    
    // Don't log Response DTO Types
    Type[] ExcludeResponseTypes;

    // Limit logging to only Service Requests
    bool LimitToServiceRequests = true;
    
    // Customize Request Log Entry
    Action<IRequest, RequestLogEntry> RequestLogFilter;

    // Ignore logging and serializing these Request DTOs
    List<Type> IgnoreTypes; = new();
    
    // Use custom Ignore Request DTO predicate
    Func<object,bool> IgnoreFilter = DefaultIgnoreFilter;

    // Default take, if none is specified
    int DefaultLimit = 100;

    // Change what DateTime to use for the current Date (defaults to UtcNow)
    Func<DateTime> CurrentDateFn = () => DateTime.UtcNow;
}
```

### Profiling Configuration

The `ProfilingFeature` offers similar functionality in specifying which sources to observe and profiling events to capture as well as options for customizing the Profiling UI, e.g you can limit generating & capturing diagnostic events to just [OrmLite](/ormlite/) and [Redis](/redis/) with:

```csharp
Plugins.Add(new ProfilingFeature {
    Profile = ProfileSource.OrmLite | ProfileSource.Redis
});
```

For further configuration options see the documented plugin below:

```csharp
[Flags]
enum ProfileSource
{
    None         = 0,
    ServiceStack = 1 << 0,
    Client       = 1 << 1,
    Redis        = 1 << 2,
    OrmLite      = 1 << 3,
    All          = ServiceStack | Client | OrmLite | Redis,
}

class ProfilingFeature
{
    // Limit API access to users in role
    string AccessRole = RoleNames.Admin;

    // Which features to Profile, default all
    ProfileSource Profile = ProfileSource.All;

    // Size of circular buffer of profiled events
    int Capacity = 10000;

    // Don't log requests of these types. By default Profiling/Metadata requests are excluded
    List<Type> ExcludeRequestDtoTypes = new();

    // Don't log requests from these path infos prefixes
    List<string> ExcludeRequestPathInfoStartingWith = new();
    
    // Turn On/Off Tracking of Responses per-request
    Func<IRequest, bool>? ExcludeRequestsFilter;

    // Don't log request body's for services with sensitive information.
    // By default Auth and Registration requests are hidden.
    List<Type> HideRequestBodyForRequestDtoTypes = new();

    // Don't log Response DTO Types
    List<Type> ExcludeResponseTypes = new();
    
    // Turn On/Off Tracking of Responses per-request
    Func<IRequest, bool>? ResponseTrackingFilter;
    
    // Whether to include CallStack StackTrace 
    bool? IncludeStackTrace;

    // Attach custom data to request profiling summary fields
    Func<IRequest,string?>? TagResolver;
    
    // Label to show for custom tag
    string? TagLabel;
    
    // The properties displayed in Profiling UI results grid
    List<string> SummaryFields;
    
    // Default take, if none is specified
    int DefaultLimit = 50;
    
    // Customize DiagnosticEntry that gets captured
    Action<DiagnosticEntry, DiagnosticEvent>? DiagnosticEntryFilter;

    // Maximum char/byte length of string response body
    int MaxBodyLength = 10 * 10 * 1024;
}
```


# Admin UI Features
Source: https://docs.servicestack.net/admin-ui-features

Built into ServiceStack v6+ Apps is the [Admin UI](/admin-ui) providing **Admin** Users a UX Friendly UI to access App features & summary insights from:

<div class="not-prose">
    <h3 class="text-center font-medium text-4xl text-indigo-800 m-0 py-3">/admin-ui</h3>
</div>

Which after authenticating will take you to the Admin UI dashboard showing the authenticated Admin User details and general API stats:

<div class="block p-4 rounded shadow">
    <img src="/img/pages/admin-ui/dashboard.png">
</div>

Further Admin UI functionality can be enabled by adding the necessary dependencies and Admin APIs necessary to implement the Admin UI Features.

### Disabling the Admin UI

If desired, the **/admin-ui** features can be selectively or entirely disabled using the `AdminUi` Enum flags:

```csharp
ConfigurePlugin<UiFeature>(feature => feature.AdminUi = AdminUi.None);
```

## Admin Users

User management functionality for creating & modifying users, assigning Roles & Permissions, locking users or updating their passwords can be enabled by registering `AdminUsersFeature` plugin:

```csharp
Plugins.Add(new AdminUsersFeature());
```

Which enables a familiar UI for searching & managing users:

<div class="block p-4 rounded shadow">
    <a href="/admin-ui-users"><img src="/img/pages/admin-ui/users.png"></a>
</div>

::: info
See [Admin UI User Docs](/admin-ui-users) to learn about Admin User features and available customization options
:::

## Redis Admin

The [Redis Admin UI](/admin-ui-redis) lets you manage your App's configured Redis Server with a user-friendly UX for managing core Redis data types, simple search functionality to quickly find Redis values, quick navigation between related values, first class support for JSON values and a flexible command interface and command history to inspect all previously run redis commands.

<lite-youtube class="w-full mx-4 my-4" width="560" height="315" videoid="AACZtTOcQbg" style="background-image: url('https://img.youtube.com/vi/AACZtTOcQbg/maxresdefault.jpg')"></lite-youtube>

It can be enabled by registering the `AdminRedisFeature` plugin:

```csharp
Plugins.Add(new AdminRedisFeature());
```

Which will enable the **Redis** Admin UI:

[![](/img/pages/admin-ui/admin-ui-redis.png)](/admin-ui-redis)

::: info
See [Redis Admin docs](/admin-ui-redis) for more info.
:::

## Database Admin

The [Database Admin UI](/admin-ui-database) lets you quickly browse and navigate your App's configured RDBMS schemas and tables:

<lite-youtube class="w-full mx-4 my-4" width="560" height="315" videoid="NZkeyuc_prg" style="background-image: url('https://img.youtube.com/vi/NZkeyuc_prg/maxresdefault.jpg')"></lite-youtube>

It can be enabled by registering the `AdminDatabaseFeature` plugin from [ServiceStack.Server](https://nuget.org/packages/ServiceStack.Server):

```csharp
Plugins.Add(new AdminDatabaseFeature());
```

Which will enable the **Database** Admin UI:

[![](/img/pages/admin-ui/admin-ui-database.png)](/admin-ui-database)

::: info
See [Database Admin docs](/admin-ui-database) for more info.
:::

## Request Logging & Profiling

Enables invaluable observability into your App, from being able to quickly inspect and browse incoming requests, to tracing their behavior:

:::sh
x mix profiling
:::

Which will add the [Modular Startup](/modular-startup) configuration to your Host project that registers both Request Logging & Profiling features when running your App in [DebugMode](/debugging#debugmode) (i.e. Development):

```csharp
[assembly: HostingStartup(typeof(MyApp.ConfigureProfiling))]

namespace MyApp;

public class ConfigureProfiling : IHostingStartup
{
    public void Configure(IWebHostBuilder builder) => builder
        .ConfigureServices((context, services) => {
            if (context.HostingEnvironment.IsDevelopment())
            {
                services.AddPlugin(new ProfilingFeature
                {
                    IncludeStackTrace = true,
                });
            }
        });
}
```

Which will enable the Request Logging & Profiling UIs:

<div class="block p-4 rounded shadow">
    <a href="/admin-ui-profiling"><img src="/img/pages/admin-ui/admin-ui-logging.png"></a>
</div>

<lite-youtube class="w-full mx-4 my-4" width="560" height="315" videoid="LgQHTSHSk1g" style="background-image: url('https://img.youtube.com/vi/LgQHTSHSk1g/maxresdefault.jpg')"></lite-youtube>

::: info
See [Admin Logging & Profiling UI docs](/admin-ui-profiling) to learn about Admin Profiling feature and available customization options.
:::

## Validation

The Admin Validation feature enables adding dynamically sourced validation rules that can be applied & modified at runtime.

The most popular `IValidationSource` for maintaining dynamic validation rules is `OrmLiteValidationSource` for maintaining them
in the App's registered database's `ValidationRule` RDBMS Table:

```csharp
[assembly: HostingStartup(typeof(MyApp.ConfigureValidation))]

namespace MyApp;

public class ConfigureValidation : IHostingStartup
{
    // Add support for dynamically generated db rules
    public void Configure(IWebHostBuilder builder) => builder
        .ConfigureServices(services => services.AddSingleton<IValidationSource>(c =>
            new OrmLiteValidationSource(c.Resolve<IDbConnectionFactory>(), HostContext.LocalCache)))
        .ConfigureAppHost(appHost => {
            // Create `ValidationRule` table if it doesn't exist in AppHost.Configure() or Modular Startup
            appHost.Resolve<IValidationSource>().InitSchema();
        });
}
```

Which can be quickly added to your project with the [x mix script](/mix-tool) below:

:::sh
x mix validation-source
:::

Which the built-in [Validation Feature](/validation.html#validation-feature) detects to register the `GetValidationRules` and `ModifyValidationRules` APIs used by the Admin Validation Feature:

<div class="block p-4 rounded shadow">
    <a href="/admin-ui-validation"><img src="/img/pages/admin-ui/validation.png"></a>
</div>

<lite-youtube class="w-full mx-4 my-4" width="560" height="315" videoid="W5OJAlOxH98" style="background-image: url('https://img.youtube.com/vi/W5OJAlOxH98/maxresdefault.jpg')"></lite-youtube>

::: info
See [Admin UI Validation Docs](/admin-ui-validation) to learn about dynamic DB Validation Rules
:::

## Recommend Admin UI Features

The Admin UI was designed with room to grow. You can let us know what features you would find most valuable on our [GitHub Discussions](https://github.com/ServiceStack/Discuss/discussions/2).


# AppHost Configuration
Source: https://docs.servicestack.net/host-configuration

<lite-youtube class="w-full mx-4 my-4" width="560" height="315" videoid="mOpx5mUGoqI" style="background-image: url('https://img.youtube.com/vi/mOpx5mUGoqI/maxresdefault.jpg')"></lite-youtube>

::: info YouTube
[youtu.be/mOpx5mUGoqI](https://youtu.be/mOpx5mUGoqI)
:::

### Anatomy of a ServiceStack AppHost

All ServiceStack App's are configured within an AppHost which typically consists of the following elements:

```csharp
public class AppHost 
  : AppHostBase                       // Type of AppHost used, normally AppHostBase
{
    public AppHost() : base(
      "MyApp",                        // Service Name in Metadata Pages
      typeof(MyServices).Assembly) {} // The ServiceInterfaces Assemblies where all Services are located

    // Configure your AppHost with the necessary configuration and dependencies your App needs
    public override void Configure(Container container)
    {
        // Set Global AppHost Configuration
        base.SetConfig(new HostConfig
        {
            DebugMode = AppSettings.Get(nameof(HostConfig.DebugMode), false)
        });

        //Register IOC Dependencies
        container.Register<IRedisClientsManager>(c => new RedisManagerPool());

        // Add Plugins to extend your App with additional functionality
        Plugins.Add(new AutoQueryFeature { 
            MaxLimit = 100  // Feature specific configuration
        });
    }
}
```

::: info
[DebugMode](/debugging#debugmode) should be not be `true` when deployed to production.
:::

### Physical Project Structure

See [Physical Project Structure](/physical-project-structure) docs to learn about ServiceStack's Solution layout.

### Register AppHost in .NET Core

In ASP.NET Core, ServiceStack's AppHost is registered as middleware:

```csharp
// This method gets called by the runtime. Use this method to configure the HTTP request pipeline.
public void Configure(IApplicationBuilder app)
{
    //Register your ServiceStack AppHost as a .NET Core module
    app.UseServiceStack(new AppHost { 
        // Use ASP.NET Core configuration sources, e.g. **appsettings.json**
        AppSettings = new NetCoreAppSettings(Configuration) 
    }); 
}
```

See [.NET Core docs](/netcore) for more info on using ServiceStack on .NET Core.

### ConfigureAppHost

The same functionality used to configure your AppHost in [Modular Startup configurations](/modular-startup), also exists in the stand-alone `HostContext.ConfigureAppHost()` API which also lets you lazily configure your ServiceStack AppHost at any point before it's initialized:

```csharp
HostContext.ConfigureAppHost(
    beforeConfigure: appHost => ...,
    afterConfigure: appHost => ...,
    afterPluginsLoaded: appHost => ...,
    afterAppHostInit: appHost => ...);
```

### ConfigureOperation

The `ConfigureOperation` method has the same benefits for configuring an APIs metadata which is especially useful for [AutoQuery AutoGen](/autoquery/autogen) services since its operation metadata only exists after its default implementation is generated by AutoGen:

```csharp
appHost.ConfigureOperation<Register>(op => op.FormLayout = new()
{
    Input.For<Register>(x => x.DisplayName,     x => x.Help = "Your first and last name"),
    Input.For<Register>(x => x.Email,           x => x.Type = Input.Types.Email),
    Input.For<Register>(x => x.Password,        x => x.Type = Input.Types.Password),
    Input.For<Register>(x => x.ConfirmPassword, x => x.Type = Input.Types.Password),
});
```

Which overrides the default Auto UI Form to use its custom layout:

<div class="flex justify-center py-8">
    <a href="https://vue-vite-api.jamstacks.net/ui/Register">
        <img src="/img/pages/apiexplorer/api-form-Register.png" style="max-width:850px;">
    </a>
</div>

### Run AppHost in .NET Framework

```csharp
new AppHost().Init();
```

### IOC Registration

See [IOC docs](/ioc) for an overview of the APIs and behavior of ServiceStack's built-in Funq IOC.

### Modularizing Services

See [Modularizing Services](/modularizing-services) for info on Modularizing functionality in your AppHost.

### Default HostConfig

The default configuration for ServiceStack's `HostConfig`, for the most up to date version see 
[HostConfig.cs](https://github.com/ServiceStack/ServiceStack/blob/master/src/ServiceStack/HostConfig.cs):

```csharp
SetConfig(new HostConfig {
    WsdlServiceNamespace = "http://schemas.servicestack.net/types",
    ApiVersion = "1.0",
    EmbeddedResourceSources = new List<Assembly>(),
    EmbeddedResourceBaseTypes = new[] { HostContext.AppHost.GetType(), typeof(Service) }.ToList(),
    EmbeddedResourceTreatAsFiles = new HashSet<string>(),
    EnableAccessRestrictions = true,
    EnableAutoHtmlResponses = true,
    WebHostPhysicalPath = "~".MapServerPath(),
    HandlerFactoryPath = ServiceStackPath,
    MetadataRedirectPath = null,
    DefaultContentType = null,
    PreferredContentTypes = new List<string> {
        MimeTypes.Html, MimeTypes.Json, MimeTypes.Xml, MimeTypes.Jsv
    },
    AllowJsonpRequests = true,
    AllowRouteContentTypeExtensions = true,
    UseHttpOnlyCookies = true,  //default ;HttpOnly
    UseSecureCookies = true,    //default ;Secure (https)
    UseSameSiteCookies = false, //default ;SameSite=Lax
    DebugMode = false,
    StrictMode = Env.StrictMode,
    DefaultDocuments = new List<string> {
        "default.htm",
        "default.html",
        "default.cshtml",
        "default.md",
        "index.htm",
        "index.html",
        "default.aspx",
        "default.ashx",
    },
    GlobalResponseHeaders = new Dictionary<string, string> {
        { "Vary", "Accept" },
        { "X-Powered-By", Env.ServerUserAgent },
    },
    IsMobileRegex = new Regex("Mobile|iP(hone|od|ad)|Android|BlackBerry|IEMobile|Kindle|(hpw|web)OS|Fennec|" 
                     + "Minimo|Opera M(obi|ini)|Blazer|Dolfin|Dolphin|Skyfire|Zune", RegexOptions.Compiled),
    RequestRules = new Dictionary<string, Func<IHttpRequest, bool>> {
        {"AcceptsHtml", req => req.Accept?.IndexOf(MimeTypes.Html, StringComparison.Ordinal) >= 0 },
        {"AcceptsJson", req => req.Accept?.IndexOf(MimeTypes.Json, StringComparison.Ordinal) >= 0 },
        {"AcceptsXml", req => req.Accept?.IndexOf(MimeTypes.Xml, StringComparison.Ordinal) >= 0 },
        {"AcceptsJsv", req => req.Accept?.IndexOf(MimeTypes.Jsv, StringComparison.Ordinal) >= 0 },
        {"AcceptsCsv", req => req.Accept?.IndexOf(MimeTypes.Csv, StringComparison.Ordinal) >= 0 },
        {"IsAuthenticated", req => req.IsAuthenticated() },
        {"IsMobile", req => Instance.IsMobileRegex.IsMatch(req.UserAgent) },
        {"{int}/**", req => int.TryParse(req.PathInfo.Substring(1).LeftPart('/'), out _) },
        {"path/{int}/**", req => {
            var afterFirst = req.PathInfo.Substring(1).RightPart('/');
            return !string.IsNullOrEmpty(afterFirst) && int.TryParse(afterFirst.LeftPart('/'), out _);
        }},
        {"**/{int}", req => int.TryParse(req.PathInfo.LastRightPart('/'), out _) },
        {"**/{int}/path", req => {
            var beforeLast = req.PathInfo.LastLeftPart('/');
            return !string.IsNullOrEmpty(beforeLast) && int.TryParse(beforeLast.LastRightPart('/'), out _);
        }},
    },
    IgnoreFormatsInMetadata = new HashSet<string>(StringComparer.OrdinalIgnoreCase) {},
    AllowFileExtensions = new HashSet<string>(StringComparer.OrdinalIgnoreCase)
    {
        "js", "ts", "tsx", "jsx", "css", "htm", "html", "shtm", "txt", "xml", "rss", "csv", "pdf",
        "jpg", "jpeg", "gif", "png", "bmp", "ico", "tif", "tiff", "svg",
        "avi", "divx", "m3u", "mov", "mp3", "mpeg", "mpg", "qt", "vob", "wav", "wma", "wmv",
        "flv", "swf", "xap", "xaml", "ogg", "ogv", "mp4", "webm", "eot", "ttf", "woff", "woff2", "map",
        "xls", "xla", "xlsx", "xltx", "doc", "dot", "docx", "dotx", "ppt", "pps", "ppa", "pptx", "potx", 
        "wasm"
    },
    CompressFilesWithExtensions = new HashSet<string>(),
    AllowFilePaths = new List<string>
    {
        "jspm_packages/**/*.json", //JSPM
        ".well-known/**/*",        //LetsEncrypt
    },
    ForbiddenPaths = new List<string>(),
    DebugAspNetHostEnvironment = Env.IsMono ? "FastCGI" : "IIS7",
    DebugHttpListenerHostEnvironment = Env.IsMono ? "XSP" : "WebServer20",
    EnableFeatures = Feature.All,
    WriteErrorsToResponse = true,
    ReturnsInnerException = true,
    DisposeDependenciesAfterUse = true,
    LogUnobservedTaskExceptions = true,
    HtmlReplaceTokens = new Dictionary<string, string>(),
    AddMaxAgeForStaticMimeTypes = new Dictionary<string, TimeSpan> {
        { "image/gif", TimeSpan.FromHours(1) },
        { "image/png", TimeSpan.FromHours(1) },
        { "image/jpeg", TimeSpan.FromHours(1) },
    },
    AppendUtf8CharsetOnContentTypes = new HashSet<string> { MimeTypes.Json, },
    RouteNamingConventions = new List<RouteNamingConventionDelegate> {
        RouteNamingConvention.WithRequestDtoName,
        RouteNamingConvention.WithMatchingAttributes,
        RouteNamingConvention.WithMatchingPropertyNames
    },
    MapExceptionToStatusCode = new Dictionary<Type, int>(),
    UseSaltedHash = false,
    FallbackPasswordHashers = new List<IPasswordHasher>(),
    AllowSessionIdsInHttpParams = false,
    AllowSessionCookies = true,
    RestrictAllCookiesToDomain = null,
    DefaultJsonpCacheExpiration = new TimeSpan(0, 20, 0),
    MetadataVisibility = RequestAttributes.Any,
    Return204NoContentForEmptyResponse = true,
    AllowJsConfig = true,
    AllowPartialResponses = true,
    AllowAclUrlReservation = true,
    AddRedirectParamsToQueryString = false,
    RedirectToDefaultDocuments = false,
    RedirectDirectoriesToTrailingSlashes = true,
    StripApplicationVirtualPath = false,
    ScanSkipPaths = new List<string> {
        "obj/",
        "bin/",
        "node_modules/",
        "jspm_packages/",
        "bower_components/",
        "wwwroot_build/",
        "wwwroot/", // only in .NET Framework
    },
    RedirectPaths = new Dictionary<string, string>
    {
        { "/metadata/", "/metadata" },
    },
    IgnoreWarningsOnPropertyNames = new List<string> {
        Keywords.Format, Keywords.Callback, Keywords.Debug, Keywords.AuthSecret, Keywords.JsConfig,
        Keywords.IgnorePlaceHolder, Keywords.Version, Keywords.VersionAbbr, Keywords.Version.ToPascalCase(),
        Keywords.ApiKeyParam, Keywords.Code, Keywords.Redirect, Keywords.Continue, "s", "f"
    },
    XmlWriterSettings = new XmlWriterSettings
    {
        Encoding = new UTF8Encoding(encoderShouldEmitUTF8Identifier: false),
    },
    FallbackRestPath = null,
    UseHttpsLinks = false,
    UseJsObject = true,
    EnableOptimizations = true,
    UseCamelCase = true, // only in .NET Core; otherwise false
});
```

## Configure Logging

To ensure every ServiceStack service uses the same Global Logger it should be configured before ServiceStack's `AppHost` is initialized, e.g:

```csharp
LogManager.LogFactory = new ConsoleLogFactory(); 
new AppHost().Init();
```

See [Logging docs](/logging) for info on the various logging providers available.

## Testing

See [Unit and Integration Testing](/testing) docs for testing with ServiceStack.


# ServiceStack&#x27;s IOC
Source: https://docs.servicestack.net/ioc

::: info
When using ASP.NET Core **Endpoint Routing** refer to [ASP.NET Core IOC](/net-ioc) instead
:::


ServiceStack uses a slightly modified version of [Funq](http://funq.codeplex.com/) - which was adopted because 
of its excellent [performance and memory characteristics](http://www.servicestack.net/benchmarks/). 
ServiceStack's version of Funq has been enhanced with Expression-based Auto-wiring and lifetime Request Scope.

If you so wish, you can still elect to use your favorite IOC by creating an `IContainerAdapter` for them. 
See below for examples of adapters for popular IOC's. All ServiceStack's customizable hooks support 
Auto-wiring out-of-the-box, namely:

- [Services](/your-first-webservice-explained)
- [Request and Response Filter attributes](/filter-attributes) _(are executed before a service gets called)_
- [Validators](/validation) _(validates a Request DTO before the service gets called)_

For each of these features, dependencies are resolved for all parameters in the constructor that has the most arguments as well as all public properties.

## .NET Core Compatible Registration APIs

To retain compatibility with ASP .NET Core IOC we recommend using Funq's `IServiceCollection` and `IServiceProvider` interfaces
when registering dependencies, letting you use a single consistent API to register dependencies in both ServiceStack's and .NET Core's IOC 
making it easy to move registrations between the two, e.g:

```csharp
public void Configure(Container container)
{
    //Register Singleton instance using Factory function
    container.AddSingleton<IBar>(c => new Bar { Name = "bar" }); //Equivalent to:
    container.Register<IBar>(c => new Bar { Name = "bar" });

    //Register Auto-Wired Transient instance
    container.AddTransient<IFoo, Foo>(); //Equivalent to:
    container.RegisterAutoWiredAs<Foo,IFoo>().ReusedWithin(ReuseScope.None);
    
    //Register Auto-Wired Request Scope instance
    container.AddScoped<IScoped, Scoped>(); //Equivalent to:
    container.RegisterAutoWiredAs<Foo,IFoo>().ReusedWithin(ReuseScope.Request);    
}
```

## Autowire Registration

You can register dependencies so that all the dependencies are automatically auto-wired. Just like the hooks 
above, once resolved Funq will create a new instance resolving dependencies for the constructor that has the 
most arguments as well as all public properties.

```csharp
public override void Configure(Container container)
{
   container.AddSingleton<MyType>();
   container.AddSingleton<IMyType,MyType>();
}
```

There's also support for registration of run-time types with these APIs below:

```csharp
container.AddSingleton(typeof(MyType));
container.AddSingleton(typeof(IMyType),typeof(MyType));
```

## Custom Registration

Funq also supports custom creation of instances. When used no auto-wiring is performed and it's left up to you 
to explicitly resolve all your dependencies.

### Using Custom Factories

In addition to Auto-wiring Funq allows you to customize the creation of your instance with custom delegates. 
This is useful when your dependencies require custom configuration. E.g:

```csharp
container.AddSingleton(c => new MyType(c.GetRequiredService<IDependency>(), connectionString));
container.AddSingleton<IMyType>(c => new MyType(c.GetRequiredService<IDependency>(), connectionString));
container.AddSingleton(c => CreateAndInitializeMyType(
    c.GetRequiredService<IDependency1>(), c.GetRequiredService<IDependency2>));
```

### Register instances

Other than factories, you can also register custom instances where instead of returning a lambda above you 
can return an instance:

```csharp
container.AddSingleton(new MyType(c.GetRequiredService<IDependency>(), connectionString));
```

::: info
When using the methods above, the properties and the constructor of the registered type aren't 
auto-wired (ie **the properties and the constructor are not injected**)
:::

## Object lifetime

By default all dependencies registered in Funq have singleton scope, where the same instance is injected into all dependencies. This behaviour can be changed by defining the scope explicitly, which is supported with the following APIs:

```csharp
container.AddSingleton(c => new MyType()); 
container.AddSingleton<MyType>(); 
container.AddSingleton<IMyType,MyType>(); 
container.AddSingleton(typeof(MyType)); 
container.AddSingleton(typeof(IMyType), typeof(MyType)); 
```

### Supported Lifetime Scopes

- `AddSingleton`: Singleton scope (a instance is used per application lifetime)
- `AddScoped`: Request scope (a instance is used per request lifetime)
- `AddTransient`: Transient scope (a new instance is created every time)

#### Scoped Dependencies

In ASP.NET Core ServiceStack is pre-configured to use a `NetCoreContainerAdapter` where it will also resolve any 
dependencies declared in your .NET Core Startup using `app.ApplicationServices`. One side-effect of this is that 
when resolving **Scoped** dependencies it resolves them in a Singleton scope instead of the Request Scope had 
they instead been resolved from `context.RequestServices.GetService<T>()`.

One way to be able to inject scoped dependencies into your Services is to register the `IHttpContextAccessor`
where they'll be resolved from ASP.NET Core's RequestServices context:

```csharp
public void ConfigureServices(IServiceCollection services)
{
     services.AddHttpContextAccessor();
     services.AddScoped<IScoped, Scoped>();
}
```

Otherwise if you need to resolve Request Scoped .NET Core dependencies you can resolve them from `IRequest`, e.g:

```csharp
public object Any(MyRequest request)
{
    var requestScope = base.Request.GetService<IScoped>();
}
```

Alternatively you can register the dependencies in ServiceStack's IOC instead, e.g:

```csharp
public override void Configure(Container container)
{
    container.AddScoped<IScoped,Scoped>();
}
```

Where they'd be resolved within ServiceStack's Request Scope instead of via ASP.NET Core's RequestServices.

### ASP.NET Core IServiceProvider APIs

Registering dependencies in ServiceStack's IOC are only available within ServiceStack, you can access 
**scoped ASP.NET Core dependencies** and create Custom IOC Scopes using the `IRequest` APIs below:

 - `IRequest.CreateScope()`
 - `IRequest.GetService()`
 - `IRequest.GetService<T>()`
 - `IRequest.GetRequiredService()`
 - `IRequest.GetRequiredService<T>()`
 - `IRequest.GetServices()`
 - `IRequest.GetServices<T>()`

Which can be used to create custom scopes that utilizes ASP.NET Entity Framework Identity classes in your ServiceStack Services:

```csharp
using (var scope = Request.CreateScope())
{
    var RoleManager = scope.ServiceProvider.GetRequiredService<RoleManager<IdentityRole>>();
    var UserManager = scope.ServiceProvider.GetRequiredService<UserManager<ApplicationUser>>();

    var managerUser = await UserManager.FindByEmailAsync("manager@gmail.com");
    if (managerUser == null)
    {
        assertResult(await UserManager.CreateAsync(new ApplicationUser {
            DisplayName = "Test Manager",
            Email = "manager@gmail.com",
            UserName = "manager@gmail.com",
            FirstName = "Test",
            LastName = "Manager",
        }, "p@55wOrd"));
        
        managerUser = await UserManager.FindByEmailAsync("manager@gmail.com");
        await UserManager.AddToRoleAsync(managerUser, "Manager");
    }
}
```

## Advanced Usages

### Autowiring Generic Type Definitions

Whilst ServiceStack's IOC doesn't have a native support for registering types based on a generic type definition, it's easy to use the Runtime Type APIs and register them yourself. E.g the example below will register and autowire all types that implement `ICommand<T>` in the current assembly:

```csharp
GetType().Assembly.GetTypes()
    .Where(x => x.IsOrHasGenericInterfaceTypeOf(typeof(ICommand<>)))
    .Each(x => container.AddSingleton(x));
```

## Use another IoC container

```csharp
public interface IResolver {
    T TryResolve<T>();
}

public interface IContainerAdapter : IResolver {
    T Resolve<T>();
}
```

#### Example Usage

```csharp
IKernel kernel = new StandardKernel();
container.Adapter = new NinjectIocAdapter(kernel);
```

Adding a custom ContainerAdapter allows your services to resolve its dependencies from an alternative IOC, in this way they act like a **dependency repository** where the services are still registered in Funq but all their dependencies are resolved by the ContainerAdapter specified. Dependencies in constructors are resolved by calling `IContainerAdapter.Resolve<T>()` whilst public property dependencies are resolved with `IContainerAdapter.TryResolve<T>()`, the idea is you can have missing constructor dependencies throw an exception whilst you can be more lax about property dependencies, where your service can continue to execute without them (should you wish).

Here are some example how to use some popular IoC containers side-by-side with Funq. Of course you're not only limited to the these IoC containers here:

### Use Ninject

```csharp
public class NinjectIocAdapter : IContainerAdapter
{
    private readonly IKernel kernel;

    public NinjectIocAdapter(IKernel kernel)
    {
        this.kernel = kernel;
    }

    public T Resolve<T>()
    {
        return this.kernel.Get<T>();
    }

    public T TryResolve<T>()
    {
        return this.kernel.CanResolve<T>() ? this.kernel.Get<T>() : default(T);
    }
}
```

Then in the `AppHost` `Configure(Container container)` method you need to enable this adapter:

```csharp
//Create Ninject IoC container
IKernel kernel = new StandardKernel();
//Now register all depedencies to your custom IoC container
//...

//Register Ninject IoC container, so ServiceStack can use it
container.Adapter = new NinjectIocAdapter(kernel);
```

### Use StructureMap

```csharp
public class StructureMapContainerAdapter : IContainerAdapter
{
	public T TryResolve<T>()
	{
		return ObjectFactory.TryGetInstance<T>();
	}

	public T Resolve<T>()
	{
		return ObjectFactory.TryGetInstance<T>();
	}
}
```

In `AppHost` `Configure`:

```csharp
//Configure User Defined REST Paths
container.Adapter = new StructureMapContainerAdapter();

//Register your dependencies
ObjectFactory.Inject(typeof(IFoo), new Foo());
```

::: info
Due to a behavior of StructureMap, you need your `AppHost` declare as `internal`, eg: `internal class AppHost : AppHostBase`
:::

### Use Windsor

```csharp
// The "ApplicationAssemblyFilter" is a custom class that just helps to 
// automate registration to assemblies which match a particular pattern 
// in the app path
public class ApplicationAssemblyFilter : AssemblyFilter
{
    public ApplicationAssemblyFilter()
        : base(AppDomain.CurrentDomain.BaseDirectory, Assembly.GetExecutingAssembly().GetName().Name + ".*.dll"){}
}

public class WindsorContainerAdapter : IContainerAdapter, IDisposable 
{ 
    private readonly IWindsorContainer container; 

    public WindsorContainerAdapter() 
    { 
        container = new WindsorContainer().Install(FromAssembly.InThisApplication(), 
             FromAssembly.InDirectory(new ApplicationAssemblyFilter())); 
    } 

    public T TryResolve<T>() 
    { 
       if (container.Kernel.HasComponent(typeof(T)))
       {
          return (T)container.Resolve(typeof(T));
       }

       return default(T); 
    } 

    public T Resolve<T>() 
    { 
        return container.Resolve<T>(); 
    } 

    public void Dispose() 
    { 
        container.Dispose(); 
    } 
} 
```

### Use Autofac

```csharp
public class AutofacIocAdapter : IContainerAdapter
{
    private readonly Autofac.IContainer container;

    public AutofacIocAdapter(Autofac.IContainer container) => 
        this.container = container;

    public T TryResolve<T>()
    {
        if (container.TryResolve<Autofac.ILifetimeScope>(out var scope) &&
            scope.TryResolve(typeof(T), out var scopeComponent))
            return (T)scopeComponent;

        if (container.TryResolve(typeof(T), out var component))
            return (T)component;

        return default;
    }

    public T Resolve<T>()
    {
        var ret = TryResolve<T>();
        return !ret.Equals(default)
            ? ret
            : throw new Exception($"Error trying to resolve '{typeof(T).Name}'");
    }
}
```

Then in the `AppHost` `Configure(Container container)` method you need to enable this adapter:

```csharp
//Create Autofac builder
var builder = new ContainerBuilder();
//Now register all depedencies to your custom IoC container
//...

//Register Autofac IoC container adapter, so ServiceStack can use it
IContainerAdapter adapter = new AutofacIocAdapter(builder.Build());
container.Adapter = adapter;
```

### Use SimpleInjector

```csharp
public class SimpleInjectorIocAdapter : IContainerAdapter
{
    private readonly Container container;

    public SimpleInjectorIocAdapter(Container container)
    {
        this.container = container;
    }

    public T Resolve<T>() 
    {
        return (T)this.container.GetInstance(typeof(T));
    }

    public T TryResolve<T>()
    {
        var registration = this.container.GetRegistration(typeof(T));
        return registration == null ? default(T) : (T)registration.GetInstance();
    }
}
```

Then in the `AppHost` `Configure(Container container)` method you need to enable this adapter:

```csharp
//Create SimpleInjector IoC container
Container container = new Container();
//Now register all depedencies to your custom IoC container
//...

//Register SimpleInjector IoC container, so ServiceStack can use it
container.Adapter = new SimpleInjectorIocAdapter (container);
```

### Use Unity

```csharp
public class UnityIocAdapter : IContainerAdapter
{
    private readonly IUnityContainer container;

    public UnityIocAdapter(IUnityContainer container)
    {
        this.container = container;
    }

    public T Resolve<T>()
    {
        return container.Resolve<T>();
    }

    public T TryResolve<T>()
    {
        if(container.IsRegistered<T>())
        {
            return container.Resolve<T>();
        }

        return default(T);
    }
}
```

Then in the `AppHost` `Configure(Container container)` method you need to enable this adapter:

```csharp
//Create Unity IoC container
var unityContainer = new UnityContainer();
//Now register all depedencies to your custom IoC container
//...

//Register SimpleInjector IoC container, so ServiceStack can use it
container.Adapter = new UnityIocAdapter(unityContainer);
```

### Disposing of your services

The `AppHost.Release(instance)` method gets called for every resolved service right after it's used. 
This is the [default implementation](https://github.com/ServiceStack/ServiceStack/blob/f2d8eadaf5f4eecf1eadae918243472b039e5dfe/src/ServiceStack/ServiceStackHost.cs#L787-L805) (which can be overridden):

```csharp
var iocAdapterReleases = Container.Adapter as IRelease;
if (iocAdapterReleases != null)
{
    iocAdapterReleases.Release(instance);
}
else 
{
    var disposable = instance as IDisposable;
    if (disposable != null)
        disposable.Dispose();
}
```

Which will first try to call your ContainerAdapter if it implements `IRelease` otherwise if the service is `IDisposable` it will just dispose of it itself.

So to have resolved services released back into your IOC, implement the `IRelease` interface on your IContainerAdapter, e.g:

```csharp
public class WindsorContainerAdapter : IContainerAdapter, IRelease
{ 
    private readonly IWindsorContainer _container; 

    public void Release(object instance)
    { 
        _container.Release(instance);
    }
}
```
 
Otherwise you can override default implementation in your `AppHost.Release(instance)` if you want to do something other than the default implementation.

# Community Resources

  - [ServiceStack: IoC with Microsoft Unity](http://www.agile-code.com/blog/servicestack-ioc-with-microsoft-unity/) by [@zoranmax](https://twitter.com/zoranmax)
  - [ServiceStack extensibility using MEF](http://bhameyie.com/2013/09/03/servicestack-extensibility-using-mef/) by [@bhameyie](https://twitter.com/bhameyie)


# ASP.NET Core IOC
Source: https://docs.servicestack.net/net-ioc

From [ServiceStack v8.1](/releases/v8_01) all new .NET 8+ [Project Templates](https://servicestack.net/start) have switched to use
[Endpoint Routing](/endpoint-routing) and ASP.NET Core IOC where all Dependencies, Services and Plugins should now be registered
in `IServiceCollection`, commonly done in `IHostingStartup` [Modular Startup](/modular-startup) classes, e.g:

```csharp
public class AppHost() : AppHostBase("MyApp"), IHostingStartup
{
    public void Configure(IWebHostBuilder builder) => builder
        .ConfigureServices(services => {
            // Register Singleton Instance
            services.AddSingleton<IBar>(new Bar { Name = "bar" });

            //Register Singleton instance using Factory function
            services.AddSingleton<IBar>(c => new Bar { Name = "bar" });

            //Register Auto-Wired Transient instance
            services.AddTransient<IFoo, Foo>();
            
            //Register Auto-Wired Request Scope instance
            services.AddScoped<IScoped, Scoped>();

            //Register Request Scope instance using Factory function
            services.AddScoped<IScoped>(c => new Scoped(c.GetRequiredService<IBar>()) {
                Foo = c.GetService<IFoo>() // Optional Service
            });
        });
}
```

Use `context` when needing access to configuration or `HostingEnvironment`, e.g:

```csharp
public class ConfigureDb : IHostingStartup
{
    public void Configure(IWebHostBuilder builder) => builder
        .ConfigureServices((context, services) => {

            services.AddSingleton<IDbConnectionFactory>(new OrmLiteConnectionFactory(
                context.Configuration.GetConnectionString("DefaultConnection"),
                SqliteDialect.Provider));

            if (context.HostingEnvironment.IsDevelopment())
            {
                //...
            }
        });
}
```

## Switch to use ASP.NET Core IOC

To enable ServiceStack to switch to use ASP .NET Core's IOC, all dependency, Plugins and Service registrations need to be moved
to before the `WebApplication` is built by calling `AddServiceStack()` with the Assemblies where your ServiceStack Service 
Implementations are located, e.g:

```csharp
builder.Services.AddServiceStack(typeof(MyServices).Assembly);

var app = builder.Build();

//...
app.UseServiceStack(new AppHost());

app.Run();
```

This change registers all ServiceStack dependencies in ASP.NET Core's IOC, including all ServiceStack Services prior to
the AppHost being initialized.

### Registering Dependencies and Plugins

Additionally ASP.NET Core's IOC requirement for all dependencies needing to be registered before the WebApplication is 
built means you'll no longer be able to register any dependencies or plugins in ServiceStack's `AppHost.Configure()`:

```csharp
public class AppHost() : AppHostBase("MyApp"), IHostingStartup
{
    public void Configure(IWebHostBuilder builder) => builder
        .ConfigureServices(services => {
            // Register IOC Dependencies and ServiceStack Plugins
        });

    public override void Configure()
    {
        // DO NOT REGISTER ANY PLUGINS OR DEPENDENCIES HERE
    }
}
```

Instead anything that needs to register dependencies in ASP.NET Core IOC should now use the `IServiceCollection` extension methods:

 - `IServiceCollection.Add*` APIs to register dependencies
 - `IServiceCollection.AddPlugin` API to register ServiceStack Plugins
 - `IServiceCollection.RegisterService*` APIs to dynamically register ServiceStack Services in external Assemblies

This can be done whenever you have access to `IServiceCollection`, either in `Program.cs`:

```csharp
builder.Services.AddPlugin(new AdminDatabaseFeature());
```

Or in any Modular Startup `IHostingStartup` configuration class, e.g:

```csharp
public class ConfigureDb : IHostingStartup
{
    public void Configure(IWebHostBuilder builder) => builder
        .ConfigureServices((context, services) => {
            services.AddSingleton<IDbConnectionFactory>(new OrmLiteConnectionFactory(
                context.Configuration.GetConnectionString("DefaultConnection"),
                SqliteDialect.Provider));
            
            // Enable Audit History
            services.AddSingleton<ICrudEvents>(c =>
                new OrmLiteCrudEvents(c.GetRequiredService<IDbConnectionFactory>()));
            
            // Enable AutoQuery RDBMS APIs
            services.AddPlugin(new AutoQueryFeature {
                 MaxLimit = 1000,
            });

            // Enable AutoQuery Data APIs
            services.AddPlugin(new AutoQueryDataFeature());
            
            // Enable built-in Database Admin UI at /admin-ui/database
            services.AddPlugin(new AdminDatabaseFeature());
        })
        .ConfigureAppHost(appHost => {
            appHost.Resolve<ICrudEvents>().InitSchema();
        });
}
```

The `ConfigureAppHost()` extension method can continue to be used to execute any logic that requires access to 
registered dependencies on StartUp.


## Dependency Injection

The primary difference between the IOC's is that ASP.NET Core's IOC does not support property injection by default, 
which require ServiceStack Services to use constructor injection of dependencies which is pleasant to define
with C# 12's [Primary Constructors](https://learn.microsoft.com/en-us/dotnet/csharp/whats-new/tutorials/primary-constructors)
which requires a lot less boilerplate to define, assign and access dependencies, e.g:

```csharp
public class TechStackServices(IAutoQueryDb autoQuery) : Service
{
    public async Task<object> Any(QueryTechStacks request)
    {
        using var db = autoQuery.GetDb(request, base.Request);
        var q = autoQuery.CreateQuery(request, Request, db);
        return await autoQuery.ExecuteAsync(request, q, db);
    }
}
```

### [FromServices] Property Injection

For added flexibility **ServiceStack Services** also support property injection convention by using the `[FromServices]` attribute 
to any **public** properties you want injected, e.g:

```csharp
public class TechStackServices : Service
{
    [FromServices]
    public required IAutoQueryDb AutoQuery { get; set; }

    [FromServices]
    public MyDependency? OptionalDependency { get; set; }
}
```

This feature is useful for Services needing optional access to dependencies that may or may not be registered. 

:::info NOTE
`[FromServices]` is only supported in ServiceStack Services (i.e. not other dependencies)
:::

### Authoring ServiceStack Plugins

To enable ServiceStack Plugins to support both Funq and ASP .NET Core IOC, any dependencies and Services a plugin needs
should be registered in the `IConfigureServices.Configure(IServiceCollection)` method as seen in the refactored
[ServerEventsFeature.cs](https://github.com/ServiceStack/ServiceStack/blob/main/ServiceStack/src/ServiceStack/ServerEventsFeature.cs)
plugin, e.g:

```csharp
public class ServerEventsFeature : IPlugin, IConfigureServices
{
    //...
    public void Configure(IServiceCollection services)
    {
        if (!services.Exists<IServerEvents>())
        {
            services.AddSingleton<IServerEvents>(new MemoryServerEvents
            {
                IdleTimeout = IdleTimeout,
                HouseKeepingInterval = HouseKeepingInterval,
                OnSubscribeAsync = OnSubscribeAsync,
                OnUnsubscribeAsync = OnUnsubscribeAsync,
                OnUpdateAsync = OnUpdateAsync,
                NotifyChannelOfSubscriptions = NotifyChannelOfSubscriptions,
                Serialize = Serialize,
                OnError = OnError,
            });
        }
        
        if (UnRegisterPath != null)
            services.RegisterService<ServerEventsUnRegisterService>(UnRegisterPath);

        if (SubscribersPath != null)
            services.RegisterService<ServerEventsSubscribersService>(SubscribersPath);
    }

    public void Register(IAppHost appHost)
    {
        //...
    }
}
```


# Routing
Source: https://docs.servicestack.net/routing

::: info
For docs on routing with ServiceStack's latest .NET 8 Templates see [Endpoint Routing](/endpoint-routing)
:::

## Pre-defined Routes

Without any configuration required, ServiceStack already includes [pre-defined routes](/routing#pre-defined-routes) for all services in the format:

    /api?/[xml|json|html|jsv|csv]/[reply|oneway]/[servicename]

> servicename is the name of the Request DTO

e.g. the pre-defined url to call a JSON 'Hello' Service is:

```
/json/reply/hello
```

#### [Auto Batched Requests](/auto-batched-requests)

```
/json/reply/Hello[]
```

### SOAP Web Service urls

```
/api?/[soap11|soap12]
```

## JSON /api pre-defined route

Over the last decade [JSON](https://www.json.org/json-en.html) has stood out and become more popular than all others combined, where it's the lingua franca for calling APIs in Web Apps and what our [Add ServiceStack Reference](/add-servicestack-reference) ecosystem of languages relies on. Due to its overwhelming dominance for usage in APIs we've decided to elevate its status and give it a pre-defined route of its very own at:

<div class="not-prose">
<h3 class="text-4xl text-center text-indigo-800 pb-3">/api/{Request}</h3>
</div>

This simple convention makes it easy to remember the route new APIs are immediately available on & pairs nicely with [API Explorer's](/api-explorer):

<div class="not-prose">
<h3 class="text-4xl text-center text-indigo-800 pb-3">/ui/{Request}</h3>
</div>

### Benefits in Jamstack Apps

The `/api` route is particularly useful in Jamstack Apps as the 2 ways to call back-end APIs from decoupled UIs hosted on CDNs is to make CORS requests which doesn't send pre-flight CORS requests for [Simple Browser requests](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS#simple_requests). As such, we can improve the latency of **GET** and **POST** API Requests by configuring our `JsonServiceClient` to use `/api` and to not send the `Content-Type: application/json` HTTP Header which isn't necessary for `/api` requests which always expects and returns JSON:

#### Configuring in .NET

No configuration is necessary for the new **.NET 6+** [JsonApiClient](#jsonapiclient) that's pre-configured to use `/api` fallback by default:

```csharp
var client = new JsonApiClient(baseUri);
```

All .NET Clients use any **matching user-defined routes** defined on the Request DTO with the existing Service Clients falling back to `/json/[reply|oneway]` if none exist who can be configured to use the `/api` fallback with:

```csharp
var client = new JsonServiceClient(baseUri) {
    UseBasePath = "/api"
};
var client = new JsonHttpClient(baseUri) {
    UseBasePath = "/api"
};
```

### Multiple Content Types

The JSON API Route also supports returning API responses in multiple [registered content types](/formats) by using its format extension, e.g:

<h3 class="text-4xl text-center text-indigo-800 pb-3">/api/{Request}.{ext}</h3>

 - `/api/{Request}.csv`
 - `/api/{Request}.xml`
 - `/api/{Request}.jsv`
 - `/api/{Request}.jsonl`
 - `/api/{Request}.html`
 

### ApiHandlers

Using the new [ApiHandlers](https://github.com/ServiceStack/ServiceStack/blob/master/src/ServiceStack/ApiHandlers.cs), the code to enable the new `/api` pre-defined route is just:

```csharp
RawHttpHandlers.Add(ApiHandlers.Json("/api/{Request}"));
```

`ApiHandlers` is a simpler wrapper that registers a Raw HttpHandler delegating all matching requests to a `GenericHandler` configured with that Mime Type and includes typed overloads for each built-in data format. 

So you could also define a new pre-defined route at `/excel/*` with:

```csharp
RawHttpHandlers.Add(ApiHandlers.Csv("/excel/{Request}"));
```

Where it can now be used to download any APIs response in a `*.csv` file.

### Disable API Route

To avoid potential conflicts `/api` isn't registered if your AppHost configures its own Custom BasePath, or can be explicitly disabled with:

```csharp
ConfigurePlugin<PredefinedRoutesFeature>(feature => feature.JsonApiRoute = null);
```

### Revert to Legacy Predefined Routes

You can unset the base path to revert back to using the older `/json/reply/{Request}` pre-defined route, e.g:

#### C# JsonApiClient

```csharp
client.UseBasePath = "/json/reply/";

// Globally for all JsonApiClient instances
JsonApiClient.DefaultBasePath = "/json/reply/";
```

#### JavaScript/TypeScript

```ts
client.basePath = null;
```

#### Java/Kotlin

```java
client.setBasePath();
```


## Custom Routes

In its most basic form, a Route is just any string literal attributed on your Request DTO:

```csharp
[Route("/hello")]
public class Hello { ... }
```

which matches: 

```
/hello
/hello?Name=XXX
```

### Variable place-holders

Routes can also have variable place-holders:

```csharp
[Route("/hello/{Name}")]
```

matches:

```
/hello/foo
```

And will populate the public property **Name** on the Request DTO with **foo**.

::: info
The QueryString, FormData and HTTP Request Body isn't apart of the Route (i.e. only the /path/info is) but they can all be used in addition to every web service call to further populate the Request DTO.
:::

### Wildcard paths

Using a route with a wild card path like:

```csharp
[Route("/hello/{**Name}")]
```

matches any number of variable paths:

```
/hello
/hello/name
/hello/my/name/is/ServiceStack    //Name = my/name/is/ServiceStack
```

[Another good use-case for when to use wildcard routes](http://stackoverflow.com/questions/7780157/multiple-optional-parameters-with-servicestack-net).

### Fallback Route

Use the `FallbackRoute` attribute to specify a fallback route starting from the root path, e.g:

```csharp
[FallbackRoute("/{Path}")]
public class Fallback
{
    public string Path { get; set; }
}
```

This will match any unmatched route from the root path (e.g. `/foo` but not `/foo/bar`) that's not handled by CatchAll Handler or matches a static file. You can also specify a wildcard path e.g. `[FallbackRoute("/{Path*}")]` which will handle every unmatched route (inc. `/foo/bar`). Only 1 fallback route is allowed.

The Fallback route is useful for HTML5 Single Page App websites handling server requests of HTML5 pushState pretty urls, e.g. All
[Single Page Apps Templates](/templates/single-page-apps) use the `[FallbackRoute]` to return the home page for all HTML Requests that
do not have Server Routes, e.g [MyServices.cs](https://github.com/NetCoreTemplates/vue-spa/blob/master/MyApp.ServiceInterface/MyServices.cs):

```csharp
[FallbackRoute("/{**PathInfo}", Matches="AcceptsHtml")]
public class FallbackForClientRoutes
{
    public string PathInfo { get; set; }
}

public class MyServices : Service
{
    //Return index.html for unmatched requests so routing is handled on client
    public object Any(FallbackForClientRoutes request) => Request.GetPageResult("/");
}
```

Which will returns the the default `index.html` page using [#Script Pages](https://sharpscript.net/docs/script-pages).

#### SPA Fallback

This popular behavior is also available using the more convenient configuration (used in all [SPA Project Templates](/dotnet-new)) with:

```csharp
Plugins.Add(new SharpPagesFeature {
    EnableSpaFallback = true
}); 
```

#### Other Fallback Examples

Examples of other HTML Fallback Response:

```csharp
//Return static HTML file
return new HttpResult(VirtualFileSources.GetFile("index.html"));

//Return HTML String
return new HttpResult(VirtualFileSources.GetFile("index.html").ReadAllText());

//Return ServiceStack.Razor View
return new HttpResult(request)
{
    View = "/default.cshtml"
};
```

### Limiting to HTTP Verbs

If not specified Routes will match **All** HTTP Verbs. You can also limit Routes to individual Verbs, this lets you route the same path to different services, e.g:

```csharp
[Route("/contacts", "GET")]
[Route("/contacts/{Id}", "GET")]
public class GetContacts { ... }

[Route("/contacts", "POST PUT")]
[Route("/contacts/{Id}", "POST PUT")]
public class UpdateContact { ... }

[Route("/contacts/{Id}", "DELETE")]
public class DeleteContact { ... }
```

### Matching ignored paths

You can use the `{ignore}` variable placeholder to match a Route definition that doesn't map to a Request DTO property, e.g:

```csharp
[Route("/contacts/{Id}/{ignore}", "GET")]
public class GetContacts { ... }
```

Will match on `/contacts/1/john-doe` request and not require your Request DTO to have an **ignore** property

### Fluent API

You can also use a Fluent API to register ServiceStack Routes by adding them in your `AppHost.Configure()`:

```csharp
Routes
    .Add<Hello>("/hello")
    .Add<Hello>("/hello/{Name}");
```

and to match only **GET** request for `/Customers?Key=Value` and `/Customers/{Id}`:

```csharp
Routes
    .Add<GetContact>("/Contacts", "GET")
    .Add<GetContact>("/Contacts/{ContactId}", "GET");
```

### ServiceStack Routing Compatibility

To improve compatibility with ServiceStack [Endpoint Routing](/endpoint-routing), Routes supports parsing ASP.NET Core's 
Route Constraints but as they're inert you would need to continue to use
[Custom Route Rules](/routing#custom-rules) to distinguish between different routes matching 
the same path at different specificity:

```csharp
[Route("/users/{Id:int}", Matches = "**/{int}")]
[Route("/users/{UserName:string}")]
public class GetUser : IGet, IReturn<User>
{
    public int? Id { get; set; }
    public int? UserName { get; set; }
}
```

## Content Negotiation

In addition to using the standard `Accept` HTTP Header to retrieve the response a different format, you can also request an alternative Content-Type by appending **?format=ext** to the query string, e.g:

  - [/rockstars?format=xml](https://razor.netcore.io/rockstars?format=xml)
  - [/rockstars/1?format=json](https://razor.netcore.io/rockstars/1?format=json)

Or by appending the format **.ext** to the end of the route, e.g:

  - [/rockstars.xml](https://razor.netcore.io/rockstars.xml)
  - [/rockstars/1.json](https://razor.netcore.io/rockstars/1.json)
  - [/rockstars.html?id=1](https://razor.netcore.io/rockstars.html?id=1)

This is enabled on all custom routes and works for all built-in and user-registered formats. 
It can be disabled by setting: 

```cs
Config.AllowRouteContentTypeExtensions = false
```

### Simulate alternative HTTP Methods

Some environments prohibit or inhibit sending alternative HTTP Methods like HTML Forms which only allow **GET** or **POST**
but you can simulate an alternative HTTP Method with the `X-Http-Method-Override`, e.g. we can simulate a **PATCH** request with:

```
X-Http-Method-Override: PATCH
```

Or in a HTML Form with a hidden input, e.g:

```html
<form method="POST">
    <input type="hidden" name="X-Http-Method-Override" value="PATCH">
    ...
</form>
```

This header is also available in the `HttpHeaders.XHttpMethodOverride` constant if needing to use it in C#/.NET Clients, e.g:

```csharp
var client = new JsonServiceClient(baseUrl) {
    RequestFilter = req => req.Headers[HttpHeaders.XHttpMethodOverride] = HttpMethods.Patch
};
```

### Custom Rules

The `Matches` property on `[Route]` and `[FallbackRoute]` attributes lets you specify an additional custom Rule that requests need to match. This feature is used in all [SPA project templates](/templates/single-page-apps) to specify that the `[FallbackRoute]` should only return the SPA `index.html` for unmatched requests which explicitly requests HTML, i.e:

```csharp
[FallbackRoute("/{PathInfo*}", Matches="AcceptsHtml")]
public class FallbackForClientRoutes
{
    public string PathInfo { get; set; }
}
```

This works by matching the `AcceptsHtml` built-in `RequestRules` below where the Route will only match the Request if it includes the explicit `text/html` MimeType in the HTTP Request `Accept` Header. The `AcceptsHtml` rule prevents the home page from being returned for missing resource requests like **favicon** which returns a `404` instead.

The implementation of all built-in Request Rules:

```csharp
SetConfig(new HostConfig {
  RequestRules = {
    {"AcceptsHtml", req => req.Accept?.IndexOf(MimeTypes.Html, StringComparison.Ordinal) >= 0 },
    {"AcceptsJson", req => req.Accept?.IndexOf(MimeTypes.Json, StringComparison.Ordinal) >= 0 },
    {"AcceptsXml", req => req.Accept?.IndexOf(MimeTypes.Xml, StringComparison.Ordinal) >= 0 },
    {"AcceptsJsv", req => req.Accept?.IndexOf(MimeTypes.Jsv, StringComparison.Ordinal) >= 0 },
    {"AcceptsCsv", req => req.Accept?.IndexOf(MimeTypes.Csv, StringComparison.Ordinal) >= 0 },
    {"IsAuthenticated", req => req.IsAuthenticated() },
    {"IsMobile", req => Instance.IsMobileRegex.IsMatch(req.UserAgent) },
    {"{int}/**", req => int.TryParse(req.PathInfo.Substring(1).LeftPart('/'), out _) },
    {"path/{int}/**", req => {
        var afterFirst = req.PathInfo.Substring(1).RightPart('/');
        return !string.IsNullOrEmpty(afterFirst) && int.TryParse(afterFirst.LeftPart('/'), out _);
    }},
    {"**/{int}", req => int.TryParse(req.PathInfo.LastRightPart('/'), out _) },
    {"**/{int}/path", req => {
        var beforeLast = req.PathInfo.LastLeftPart('/');
        return beforeLast != null && int.TryParse(beforeLast.LastRightPart('/'), out _);
    }},
 }
})
```

Routes that contain a `Matches` rule have a higher precedence then Routes without. We can use this to define multiple idential matching routes to call different Service depending on whether the Path Segment is an integer or not, e.g:

```csharp
// matches /users/1
[Route("/users/{Id}", Matches = "**/{int}")]
public class GetUser
{
    public int Id { get; set; }
}

// matches /users/username
[Route("/users/{Slug}")]
public class GetUserBySlug
{
    public string Slug { get; set; }
}
```

Other examples utilizing `{int}` Request Rules:

```csharp
// matches /1/profile
[Route("/{UserId}/profile", Matches = @"{int}/**")]
public class GetProfile { ... }

// matches /username/profile
[Route("/{Slug}/profile")]
public class GetProfileBySlug { ... }

// matches /users/1/profile/avatar
[Route("/users/{UserId}/profile/avatar", Matches = @"path/{int}/**")]
public class GetProfileAvatar { ... }

// matches /users/username/profile/avatar
[Route("/users/{Slug}/profile/avatar")]
public class GetProfileAvatarBySlug { ... }
```

Another popular use-case is to call different services depending on whether a Request is from an Authenticated User or not:

```csharp
[Route("/feed", Matches = "IsAuthenticated")]
public class ViewCustomizedUserFeed { ... }

[Route("/feed")]
public class ViewPublicFeed { ... }
```

This can also be used to call different Services depending if the Request is from a Mobile browser or not:

```csharp
[Route("/search", Matches = "IsMobile")]
public class MobileSearch { ... }

[Route("/search")]
public class DesktopSearch { ... }
```

Instead of matching on a pre-configured RequestRule you can instead specify a Regular Expression using the format:

```
{Property} =~ {RegEx}
```

Where `{Property}` is an `IHttpRequest` property, e.g:

```csharp
[Route("/users/{Id}", Matches = @"PathInfo =~ \/[0-9]+$")]
public class GetUser { ... }
```

An exact match takes the format:

```
{Property} = {Value}
```

Which you could use to provide a tailored feed for specific clients:

```csharp
[Route("/feed", Matches = @"UserAgent = specific-client")]
public class CustomFeedView { ... }
```

### HTTP Verb Interface Markers

You can decorate your Request DTO's using the `IGet`, `IPost`, `IPut`, `IDelete` and `IPatch` interface markers and the `Send` and  `SendAsync` API's will use it to automatically send the Request using the selected HTTP Method. E.g:

```csharp
public class HelloByGet : IGet, IReturn<HelloResponse>
{
    public string Name { get; set; }
}
public class HelloByPut : IPut, IReturn<HelloResponse> 
{
    public string Name { get; set; }
}

var response = client.Send(new HelloByGet { Name = "World" }); // GET

await client.SendAsync(new HelloByPut { Name = "World" });     // PUT
```

Interface markers is supported in all .NET Service Clients, they're also included in the generated [Add ServiceStack Reference](/add-servicestack-reference) DTO's.

## Auto Route Generation Strategies

Also related to this is registering Auto routes via the [Routes.AddFromAssembly](https://github.com/ServiceStack/ServiceStack/blob/master/src/ServiceStack/ServiceRoutesExtensions.cs#L23) extension method, where this single call:

```cs
Routes.AddFromAssembly(typeof(FooService).Assembly)
```

Goes through and scans all your services (in the Assemblies specified) and registers convention-based routes based on all the HTTP methods you have implemented. 

The default convention registers routes based on the Request DTO Name, whether it has an **Id** property and what actions were implemented. These conventions are configurable where you can now adjust/remove the existing rules or add your own to the **pre-defined** rules in `Config.RouteNamingConventions`:

```csharp
RouteNamingConventions = new List<RouteNamingConventionDelegate> {
    RouteNamingConvention.WithRequestDtoName,
    RouteNamingConvention.WithMatchingAttributes,     // defaults: PrimaryKeyAttrubute
    RouteNamingConvention.WithMatchingPropertyNames,  // defaults: Id, IDs
}
```

The existing rules can be further customized by modifying the related static properties, e.g:

```csharp
RouteNamingConvention.PropertyNamesToMatch.Add("UniqueId");
RouteNamingConvention.AttributeNamesToMatch.Add("DefaultIdAttribute");
```

Which will make these request DTOs:

```csharp
class MyRequest1
{
    public UniqueId { get; set;}
}

class MyRequest2
{
    [DefaultId]
    public CustomId { get; set;}
}
```

Generate the following routes:

```
/myrequest1
/myrequest1/{UniqueId}
/myrequest2
/myrequest2/{CustomId}
```

See the implementation of [RouteNamingConvention](https://github.com/ServiceStack/ServiceStack/blob/master/src/ServiceStack/Host/RouteNamingConvention.cs) for examples of how to add your own auto-generated route conventions.

### Dynamically adding Route Attributes

Routes attributes can also be added dynamically but as Services are auto-registered before `AppHost.Configure()` runs, Route attributes need to be added before this happens like in the AppHost Constructor or before `new AppHost().Init()`, i.e:

```csharp
public class AppHost : AppHostBase {
    public AppHost() {
        typeof(MyRequest)
           .AddAttributes(new RouteAttribute("/myrequest"))
           .AddAttributes(new RouteAttribute("/myrequest/{UniqueId}"));
    }
}
```

### Customizing Defined Routes

You can customize existing routes by overriding `GetRouteAttributes()` in your AppHost, the example below adds a `/api` prefix to all existing routes:

```csharp
public class AppHost : AppHostBase
{
    //...
    public override RouteAttribute[] GetRouteAttributes(Type requestType)
    {
        var routes = base.GetRouteAttributes(requestType);
        routes.Each(x => x.Path = "/api" + x.Path);
        return routes;
    }
}
```

### Uploading Files

You can access uploaded files independently of the Request DTO using `Request.Files`. e.g:

```csharp
public object Post(MyFileUpload request)
{
    if (this.Request.Files.Length > 0)
    {
        var uploadedFile = base.Request.Files[0];
        uploadedFile.SaveTo(MyUploadsDirPath.CombineWith(file.FileName));
    }
    return HttpResult.Redirect("/");
}
```

ServiceStack's [imgur.netcore.io](https://imgur.netcore.io) example shows how to access the [byte stream of multiple uploaded files](https://github.com/ServiceStackApps/Imgur/blob/master/src/Imgur/Global.asax.cs#L62), e.g:

```csharp
public object Post(Upload request)
{
    foreach (var uploadedFile in base.Request.Files
       .Where(uploadedFile => uploadedFile.ContentLength > 0))
    {
        using (var ms = new MemoryStream())
        {
            uploadedFile.WriteTo(ms);
            WriteImage(ms);
        }
    }
    return HttpResult.Redirect("/");
}
```

### Reading directly from the Request Stream

Instead of registering a custom binder you can skip the serialization of the Request DTO, you can add the [IRequiresRequestStream](https://github.com/ServiceStack/ServiceStack/blob/master/src/ServiceStack.Interfaces/Web/IRequiresRequestStream.cs) interface to directly retrieve the stream without populating the Request DTO.

```csharp
//Request DTO
public class RawBytes : IRequiresRequestStream
{
    /// <summary>
    /// The raw Http Request Input Stream
    /// </summary>
    Stream RequestStream { get; set; }
}
```

Which tells ServiceStack to skip trying to deserialize the request so you can read in the raw HTTP Request body yourself, e.g:

```csharp
public async Task<object> PostAsync(RawBytes request)
{
    byte[] bytes = await request.RequestStream.ReadFullyAsync();
    string text = bytes.FromUtf8Bytes(); //if text was sent
}
```

### Pluralize and Singularize

In order to use optimal user-friendly routes in [AutoGen AutoQuery Services](/autoquery/autogen), an interned version of 
[Andrew Peters port of Rails Inflector](http://andrewpeters.net/inflectornet/) is available under the `Words` static class
that you can use to `Pluralize` or `Singularize` routes:

```csharp
var plural = Words.Pluralize("customer");      //= customers
var singular = Words.Singularize("customers"); //= customer
```

## Routing Resolution Order

This is described in more detail on the [New API Design wiki](/api-design) but the weighting used to select a route is based on:

  1. Any exact Literal Matches are used first
  2. Exact Verb match is preferred over All Verbs
  3. The more variables in your route the less weighting it has
  4. Routes with wildcard variables have the lowest precedence
  5. When Routes have the same weight, the order is determined by the position of the Action in the service or Order of Registration (FIFO)

### Route weighting example

The following HTTP Request:

```
GET /content/v1/literal/slug
```

Will match the following Route definitions in order from highest precedence to lowest:

```csharp
[Route("/content/v1/literal/slug", "GET")]
[Route("/content/v1/literal/slug")]
[Route("/content/v1/literal/{ignore}", "GET")]
[Route("/content/{ignore}/literal/{ignore}", "GET")]
[Route("/content/{Version*}/literal/{Slug*}", "GET")]
[Route("/content/{Version*}/literal/{Slug*}")]
[Route("/content/{Slug*}", "GET")]
[Route("/content/{Slug*}")]
```

See the [RestPathTests.cs](https://github.com/ServiceStack/ServiceStack/blob/master/tests/ServiceStack.ServiceHost.Tests/RestPathTests.cs) and [Smart Routing](/api-design) section on the wiki for more examples.

### Content-Type Specific Service Implementations

Service implementations can use `Verb{Format}` method names to provide a different implementation for handling a specific Content-Type, e.g. 
the Service below defines several different implementation for handling the same Request:

```csharp
[Route("/my-request")]
public class MyRequest 
{
    public string Name { get; set; }
}

public class ContentTypeServices : Service
{
    // Handles all other unspecified Verbs/Formats to /my-request
    public object Any(MyRequest request) => ...;

    // Handles GET /my-request for JSON responses
    public object GetJson(MyRequest request) => ..; 

    // Handles POST/PUT/DELETE/etc /my-request for HTML Responses
    public object AnyHtml(MyRequest request) =>  
        $@"<html>
            <body>
                <h1>AnyHtml {request.Name}</h1>
            </body>
        </html>";

    // Handles GET /my-request for HTML Responses
    public object GetHtml(MyRequest request) =>   
        $@"<html>
            <body>
                <h1>GetHtml {request.Name}</h1>
            </body>
        </html>";
}
```

This convention can be used for any of the formats listed in `ContentTypes.KnownFormats`, which by default includes:

 - json
 - xml
 - jsv
 - csv
 - html
 - protobuf
 - msgpack
 - wire

### Reverse Routing

If you use `[Route]` metadata attributes (as opposed to the Fluent API) you will be able to generate strong-typed URI's using just the DTOs, letting you create urls outside of ServiceStack web framework as done with [.NET Service Clients](/csharp-client) using the `ToUrl(HttpMethod)` and `ToAbsoluteUri(HttpMethod)`, e.g:

```csharp
[Route("/reqstars/search", "GET")]
[Route("/reqstars/aged/{Age}")]
public class SearchReqstars : IReturn<ReqstarsResponse>
{
    public int? Age { get; set; }
}

var relativeUrl = new SearchReqstars { Age = 20 }.ToGetUrl();
var absoluteUrl = new SearchReqstars { Age = 20 }.ToAbsoluteUri();

relativeUrl.Print(); //=  /reqstars/aged/20
absoluteUrl.Print(); //=  http://www.myhost.com/reqstars/aged/20
```

The [Email Contacts demo](https://github.com/ServiceStack/EmailContacts/) shows an example of using the above Reverse Routing extension methods to [populate routes for HTML Forms and Links in Razor Views](https://github.com/ServiceStack/EmailContacts/#bootstrap-forms). 

#### Other Reverse Routing Extension methods

```csharp
new RequestDto().ToPostUrl();
new RequestDto().ToPutUrl();
new RequestDto().ToDeleteUrl();
new RequestDto().ToOneWayUrl();
new RequestDto().ToReplyUrl();
```

### Populating Complex Type Properties on QueryString

ServiceStack uses the [JSV-Format](/jsv-format) (JSON without quotes) to parse QueryStrings.

JSV lets you embed deep object graphs in QueryString as seen [this example url](https://test.servicestack.net/json/reply/StoreLogs?Loggers=%5B%7BId:786,Devices:%5B%7BId:5955,Type:Panel,TimeStamp:1199303309,Channels:%5B%7BName:Temperature,Value:58%7D,%7BName:Status,Value:On%7D%5D%7D,%7BId:5956,Type:Tank,TimeStamp:1199303309,Channels:%5B%7BName:Volume,Value:10035%7D,%7BName:Status,Value:Full%7D%5D%7D%5D%7D%5D):

```
https://test.servicestack.net/json/reply/StoreLogs?Loggers=[{Id:786,Devices:[{Id:5955,Type:Panel,
Channels:[{Name:Temperature,Value:58},{Name:Status,Value:On}]},
{Id:5956,Type:Tank,TimeStamp:1199303309,
Channels:[{Name:Volume,Value:10035},{Name:Status,Value:Full}]}]}]
```

### Customize urls used with `IUrlFilter`

Request DTO's can customize urls used in Service Clients or any libraries using ServiceStack's typed 
[Reverse Routing](/routing#reverse-routing) by having 
Request DTO's implement 
[IUrlFilter](https://github.com/ServiceStack/ServiceStack/blob/master/src/ServiceStack.Interfaces/IUrlFilter.cs).

ServiceStack's [Stripe Gateway](https://github.com/ServiceStack/Stripe) takes advantage of ServiceStack's
typed Routing feature to implement its 
[Open-Ended, Declarative Message-based APIs](https://github.com/ServiceStack/Stripe#open-ended-declarative-message-based-apis)
with minimal effort.

In order to match Stripe's unconventional syntax for specifying arrays on the QueryString of their 3rd party
REST API we use `IUrlFilter` to customize the url that's used. E.g. we need to specify `include[]` in order
for the Stripe API to return any optional fields like **total_count**.

```csharp
[Route("/customers")]
public class GetStripeCustomers : IGet, IReturn<StripeCollection<Customer>>, IUrlFilter
{
    public GetStripeCustomers() 
    {
        Include = new[] { "total_count" };
    }

    [IgnoreDataMember]
    public string[] Include { get; set; }

    public string ToUrl(string absoluteUrl) => Include != null 
        ? absoluteUrl.AddQueryParam("include[]", string.Join(",", Include)) 
        : absoluteUrl;
}
```

> `[IgnoreDataMember]` is used to hide the property being emitted using the default convention

Which when sending the Request DTO:

```csharp
var response = client.Get(new GetStripeCustomers());
```

Generates and sends the relative url:

```
/customers?include[]=total_count
```

Which has the effect of populating the `TotalCount` property in the typed `StripeCollection<StripeCustomer>` response.

## Routing Metadata

Most of the metadata ServiceStack knows about your services are accessible internally via `HostContext.Config.Metadata` from within ServiceStack and externally via the `/operations/metadata` route. A link to the **Operations Metadata** page is displayed at the bottom of the /metadata when in ServiceStack is in `DebugMode`.

### Great Performance

Since [Routing in ASP.NET MVC can be slow](http://samsaffron.com/archive/2011/10/13/optimising-asp-net-mvc3-routing) when you have a large number of Routes, it's worthwhile pointing out ServiceStack's Routing implementation is implemented with hash lookups so doesn't suffer the linear performance regression issues you might have had with MVC. So you don't have to worry about degraded performance when registering a large number of Routes.

### Consider "pretty-urls" for public pages

A constant eyesore that hurts my aesthetic eye when surfing the web is how you can immediately tell that a Website is written in ASP.NET
by its `/{Controller}/{Action}` routing convention or `.aspx` suffix. This forces URL abnormalities where instead of choosing
the ideal identifier for your public resource, the path tends to adopt internal method and class names that typically makes more sense
to its developers than to external users. These dictated conventions also results in the `?queryString` becoming a data bag of params
that should otherwise be hidden or included as part of its public URI identifier.

#### Permalinks important for SEO, usability and refactorability

In general it's not a good idea to let a technology to dictate what your public routes end up being. Ideally your external routes 
should be regarded as permalinks and decoupled from their internal implementations as you don't want internal refactors to cause
link rot, break existing inbound navigation or lose any SEO weight they've accumulated. 

If you adopt the ideal URL from the start, you'll never have a reason to change it and the decoupling frees you from being able
to refactor it's mapped implementation or even replacing the underlying technology completely as the ideal routes are already at what 
they should be that's free from any technology bias.

Pretty URLs or [Clean URLs](https://en.wikipedia.org/wiki/Clean_URL) also provide important usability and accessibility benefits to 
non technical users where their prominent location in browsers is a valuable opportunity to add meaningful context on where they are in your Website. 

#### Pre-defined Routes are optimal for machines

In ServiceStack all Services are automatically available using the [pre-defined routes](/routing#pre-defined-routes) which is optimal 
for automated tooling and machinery as they can be predicted without requiring any server meta information.

#### Optimize Custom Routes for humans

Use [Custom Routes](/routing#custom-routes) to also make your **Services** available at the optimal Clean URLs for humans. For **Content Pages** 
you can take advantage of **Page Based Routing** in both **Sharp Pages** and now in **Razor** to specify the ideal route for your page which 
in addition to requiring less effort to define (as they're implicitly defined) they're also less effort to implement as **no Controller or Service**
are needed. They also benefit from being immediately inferrible by looking at the intuitively mapped directory and file names alone which works 
equally well in reverse where the page for a route will be exactly where you think it will be.

#### Designing Clean URLs

Some great references on designing RESTful Pretty URLs are the [Clean URL examples in Wikipedia](https://en.wikipedia.org/wiki/Clean_URL#Structure):

<CleanUrlsMd></CleanUrlsMd>

#### Get Inspired by GitHub

For some real-world inspiration look to [github.com](https://github.com) who are masters at it. You can tell a lot of thought went into 
meticulously choosing the ideal routes they want for all of their sites functionality. This has added tremendous value to GitHub's usability 
whose intuitive routes have made deep navigation possible where you can jump directly to the page you want without always having to navigate 
from their home page as needed in most websites with framework-generated routes who are more susceptible to negatively impacting user engagement
in home page redesigns that move around existing links and navigation. GitHub's logically grouped routes also gets a natural assist
from Autocomplete in browsers who are better able to complete previously visited GitHub URLs.

# Community Resources

  - [Use routes to customize service endpoints](http://dilanperera.wordpress.com/2014/02/23/servicestack-use-routes-to-customise-service-endpoints/)
    - [More on Routes](http://dilanperera.wordpress.com/2014/02/24/servicestack-more-on-routes/)
  - [Using PostSharp to Add ServiceStack Route Attributes](http://jokecamp.wordpress.com/2013/06/11/using-postsharp-to-add-servicestack-route-attributes/) by [@jokecamp](https://twitter.com/jokecamp)


# Endpoint Routing
Source: https://docs.servicestack.net/endpoint-routing

::: info
For docs on routing with ServiceStack prior to .NET 8 and v8.1 [ServiceStack Routing](/routing)
:::


## /api pre-defined route

Over the last decade [JSON](https://www.json.org/json-en.html) has stood out and become more popular than all others combined, where it's the lingua franca for calling APIs in Web Apps and what our [Add ServiceStack Reference](/add-servicestack-reference) ecosystem of languages relies on. Due to its overwhelming dominance for usage in APIs it's configured as the default format for the pre-defined route at:

<div class="not-prose">
<h3 class="text-4xl text-center text-indigo-800 pb-3">/api/{Request}</h3>
</div>

This simple convention makes it easy to remember what route APIs are available on & pairs nicely with [API Explorer's](/api-explorer):

<div class="not-prose">
<h3 class="text-4xl text-center text-indigo-800 pb-3">/ui/{Request}</h3>
</div>

#### Configuring in .NET

No configuration is necessary for the new **.NET 6+** [JsonApiClient](#jsonapiclient) that's pre-configured to use `/api` fallback by default:

```csharp
var client = new JsonApiClient(baseUri);
```

All .NET Clients use any **matching user-defined routes** defined on the Request DTO with the existing Service Clients falling back to `/json/[reply|oneway]` if none exist who can be configured to use the `/api` fallback with:

```csharp
var client = new JsonServiceClient(baseUri) {
    UseBasePath = "/api"
};
var client = new JsonHttpClient(baseUri) {
    UseBasePath = "/api"
};
```

### Other Service Clients

The latest versions of generic Service Clients in other languages are pre-configured to use `/api` by default:

#### JavaScript/TypeScript

```ts
const client = new JsonServiceClient(baseUrl)
```

#### Java/Kotlin

```java
JsonServiceClient client = new JsonServiceClient(baseUrl);
```

#### Python

```python
client = JsonServiceClient(baseUrl)
```

#### PHP

```php
$client = new JsonServiceClient(baseUrl);
```

#### Dart

```dart
var client = ClientFactory.api(baseUrl);
```

### Content Negotiation

The JSON API Route also supports returning API responses in multiple [registered content types](/formats) by using its extension, e.g:

<h3 class="text-4xl text-center text-indigo-800 pb-3">/api/{Request}.{ext}</h3>

- [/api/QueryBookings](https://blazor-vue.web-templates.io/api/QueryBookings)
- [/api/QueryBookings.jsonl](https://blazor-vue.web-templates.io/api/QueryBookings.jsonl)
- [/api/QueryBookings.csv](https://blazor-vue.web-templates.io/api/QueryBookings.csv)
- [/api/QueryBookings.xml](https://blazor-vue.web-templates.io/api/QueryBookings.xml)
- [/api/QueryBookings.html](https://blazor-vue.web-templates.io/api/QueryBookings.html)

#### Query String Format

That continues to support specifying the Mime Type via the `?format` query string, e.g:
 
- [/api/QueryBookings?format=jsonl](https://blazor-vue.web-templates.io/api/QueryBookings?format=jsonl)
- [/api/QueryBookings?format=csv](https://blazor-vue.web-templates.io/api/QueryBookings?format=csv)

### Endpoint Routing

From [ServiceStack v8.1](/releases/v8_01) ServiceStack **.NET 8** Apps support an integrated way to run all of ServiceStack 
requests including all APIs, metadata and built-in UIs with support for 
[ASP.NET Core Endpoint Routing](https://learn.microsoft.com/en-us/aspnet/core/fundamentals/routing) -
enabled by calling `MapEndpoints()` when configuring ServiceStack:

```csharp
services.AddServiceStack(typeof(MyServices).Assembly);

var app = builder.Build();
//...

app.UseServiceStack(new AppHost(), options => {
    options.MapEndpoints();
});

app.Run();
```

Which configures ServiceStack APIs to be registered and executed along-side Minimal APIs, Razor Pages, SignalR, MVC 
and Web API Controllers, etc, utilizing the same routing, metadata and execution pipeline.

### Migrating to ASP.NET Core Endpoints

To assist ServiceStack users in upgrading their existing projects we've created a migration guide walking through 
the steps required to adopt these new defaults:

<lite-youtube class="w-full mx-4 my-4" width="560" height="315" videoid="RaDHkk4tfdU" style="background-image: url('https://img.youtube.com/vi/RaDHkk4tfdU/maxresdefault.jpg')"></lite-youtube>

#### View ServiceStack APIs along-side ASP.NET Core APIs

Amongst other benefits, this integration is evident in endpoint metadata explorers like the `Swashbuckle` library 
which can now show ServiceStack APIs in its Swagger UI along-side other ASP.NET Core APIs in ServiceStack's
[Open API v3](/openapi) support.

### Routing Syntax

Using Endpoint Routing also means using ASP.NET Core's Routing System which now lets you use ASP.NET Core's
[Route constraints](https://learn.microsoft.com/en-us/aspnet/core/fundamentals/routing#route-constraints)
for defining user-defined routes for your ServiceStack APIs, e.g:

```csharp
[Route("/users/{Id:int}")]
[Route("/users/{UserName:string}")]
public class GetUser : IGet, IReturn<User>
{
    public int? Id { get; set; }
    public int? UserName { get; set; }
}
```

For the most part ServiceStack Routing implements a subset of ASP.NET Core's Routing features so your existing user-defined 
routes should continue to work as expected. 

### Wildcard Routes

[Wildcard or catch-all parameters](https://learn.microsoft.com/en-us/aspnet/core/fundamentals/routing#route-templates) 
can be used as a prefix to a route parameter to bind to the rest of the URI by using a `*` or `**` prefix, e.g:

```csharp
[Route("/wildcard/{*Path}")]  //escape path
[Route("/wildcard/{**Path}")] //leave unescaped
public class GetFile : IGet, IReturn<byte[]>
{
    public string Path { get; set; }
}
```

### Route Constraints

The Route Constraints built into ASP.NET Core Routing include:

:::{.table}
| constraint          | Example                                     | Example Matches                        | Notes                                                                                     |
|---------------------|---------------------------------------------|----------------------------------------|-------------------------------------------------------------------------------------------|
| `int`               | `{id:int}`                                  | `123456789`, `-123456789`              | Matches any integer                                                                       |
| `bool`              | `{active:bool}`                             | `true`, `FALSE`                        | Matches `true` or `false`. Case-insensitive                                               |
| `datetime`          | `{dob:datetime}`                            | `2016-12-31`, `2016-12-31 7:32pm`      | Matches a valid `DateTime` value in the invariant culture. See preceding warning.         |
| `decimal`           | `{price:decimal}`                           | `49.99`, `-1,000.01`                   | Matches a valid `decimal` value in the invariant culture. See preceding warning.          |
| `double`            | `{weight:double}`                           | `1.234`, `-1,001.01e8`                 | Matches a valid `double` value in the invariant culture. See preceding warning.           |
| `float`             | `{weight:float}`                            | `1.234`, `-1,001.01e8`                 | Matches a valid `float` value in the invariant culture. See preceding warning.            |
| `guid`              | `{id:guid}`                                 | `CD2C1638-1638-72D5-1638-DEADBEEF1638` | Matches a valid `Guid` value                                                              |
| `long`              | `{ticks:long}`                              | `123456789`, `-123456789`              | Matches a valid `long` value                                                              |
| `minlength(value)`  | `{username:minlength(4)}`                   | `Rick`                                 | String must be at least 4 characters                                                      |
| `maxlength(value)`  | `{filename:maxlength(8)}`                   | `MyFile`                               | String must be no more than 8 characters                                                  |
| `length(length)`    | `{filename:length(12)}`                     | `somefile.txt`                         | String must be exactly 12 characters long                                                 |
| `length(min,max)`   | `{filename:length(8,16)}`                   | `somefile.txt`                         | String must be at least 8 and no more than 16 characters long                             |
| `min(value)`        | `{age:min(18)}`                             | `19`                                   | Integer value must be at least 18                                                         |
| `max(value)`        | `{age:max(120)}`                            | `91`                                   | Integer value must be no more than 120                                                    |
| `range(min,max)`    | `{age:range(18,120)}`                       | `91`                                   | Integer value must be at least 18 but no more than 120                                    |
| `alpha`             | `{name:alpha}`                              | `Rick`                                 | String must consist of one or more alphabetical characters, `a`-`z` and case-insensitive. |
| `regex(expression)` | `{ssn:regex(^\\d{{3}}-\\d{{2}}-\\d{{4}}$)}` | `123-45-6789`                          | String must match the regular expression. See tips about defining a regular expression.   |
| `required`          | `{name:required}`                           | `Rick`                                 | Used to enforce that a non-parameter value is present during URL generation               |
:::

### Primary HTTP Method

An API will only register its Endpoint Route for its [primary HTTP Method](/api-design#all-apis-have-a-preferred-default-method), 
if you want an API to be registered for multiple HTTP Methods you can specify them in the `Route` attribute, e.g:

```csharp
[Route("/users/{Id:int}", "GET,POST")]
public class GetUser : IGet, IReturn<User>
{
    public required int Id { get; set; }
}
```

As such we recommend using the IVerb `IGet`, `IPost`, `IPut`, `IPatch`, `IDelete` interface markers to specify the primary HTTP Method
for an API. This isn't needed for [AutoQuery Services](/autoquery/) which are implicitly configured
to use their optimal HTTP Method.

If no HTTP Method is specified, the Primary HTTP Method defaults to HTTP **POST**.

### Authorization

Using Endpoint Routing also means ServiceStack's APIs are authorized the same way, where ServiceStack's 
[Declarative Validation attributes](/auth/#declarative-validation-attributes) are converted
into ASP.NET Core's `[Authorize]` attribute to secure the endpoint:

```csharp
[ValidateIsAuthenticated]
[ValidateIsAdmin]
[ValidateHasRole(role)]
[ValidateHasClaim(type,value)]
[ValidateHasScope(scope)]
public class Secured {}
```

#### Authorize Attribute on ServiceStack APIs

Alternatively you can use ASP.NET Core's `[Authorize]` attribute directly to secure ServiceStack APIs should
you need more fine-grained Authorization:

```csharp
[Authorize(Roles = "RequiredRole")]
[Authorize(Policy = "RequiredPolicy")]
[Authorize(AuthenticationSchemes = "Identity.Application,Bearer")]
public class Secured {}
```

#### Configuring Authentication Schemes

ServiceStack will default to using the major Authentication Schemes configured for your App to secure the APIs endpoint with, 
this can be overridden to specify which Authentication Schemes to use to restrict ServiceStack APIs by default, e.g:

```csharp
app.UseServiceStack(new AppHost(), options => {
    options.AuthenticationSchemes = "Identity.Application,Bearer";
    options.MapEndpoints();
});
```

### Hidden ServiceStack Endpoints

Whilst ServiceStack Requests are registered and executed as endpoints, most of them are marked with
`builder.ExcludeFromDescription()` to hide them from polluting metadata and API Explorers like Swagger UI and 
[API Explorer](/api-explorer).

To also hide your ServiceStack APIs you can use `[ExcludeMetadata]` attribute to hide them from all metadata services
or use `[Exclude(Feature.ApiExplorer)]` to just hide them from API Explorer UIs:

```csharp
[ExcludeMetadata]
[Exclude(Feature.ApiExplorer)]
public class HiddenRequest {}
```

### Customize Endpoint Mapping

You can register a RouteHandlerBuilders to customize how ServiceStack APIs endpoints are registered which is also
what ServiceStack uses to annotate its API endpoints to enable its new [Open API v3](/openapi) support:

```csharp
options.RouteHandlerBuilders.Add((builder, operation, method, route) =>
{
    builder.WithOpenApi(op => { ... });
});
```

### Endpoint Routing Compatibility Levels

The default behavior of `MapEndpoints()` is the strictest and recommended configuration that we want future ServiceStack Apps to use,
however if you're migrating existing App's you may want to relax these defaults to improve compatibility with existing behavior.
The configurable defaults for mapping endpoints are:

```csharp
app.UseServiceStack(new AppHost(), options => {
    options.MapEndpoints(use:true, force:true, useSystemJson:UseSystemJson.Always);
});
```

- `use` - Whether to use registered endpoints for executing ServiceStack APIs
- `force` - Whether to only allow APIs to be executed through endpoints
- `useSystemJson` - Whether to use **System.Text.Json** for JSON API Serialization

So you could for instance register endpoints and not `use` them, where they'll be visible in endpoint API explorers like
[Swagger UI](/openapi) but continue to execute in ServiceStack's Request Pipeline.

`force` disables fallback execution of ServiceStack Requests through ServiceStack's Request Pipeline for requests that
don't match registered endpoints. You may need to disable this if you have existing clients calling ServiceStack APIs through
multiple HTTP Methods, as only the primary HTTP Method is registered as an endpoint.

When enabled `force` ensures the only ServiceStack Requests that are not executed through registered endpoints are
`IAppHost.CatchAllHandlers` and `IAppHost.FallbackHandler` handlers.

`useSystemJson` lets you specify when to use [System.Text.Json for JSON API Serialization](/system-text-json), which
enables your App to standardize on using ASP.NET Core's fast async UTF8 JSON Serializer.


# Rate Limiting
Source: https://docs.servicestack.net/rate-limiting

Rate limiting is an important technique for protecting web APIs and applications from excessive traffic and abuse. 
By throttling the number of requests a client can make in a given time period, rate limiting helps ensure fair usage, 
maintains performance and availability, and defends against denial-of-service attacks.

ASP.NET Core provides built-in middleware for rate limiting based on client IP address or client ID. And now with [ServiceStack v8.1](/releases/v8_01), 
ServiceStack has added support for ASP.NET Core endpoints, making it possible to leverage the same rate limiting middleware 
across all ASP.NET Core endpoints, including ServiceStack APIs.

In this post, we'll look at how to enable rate limiting in an ASP.NET Core app using the standard middleware. 
Then we'll explore some more advanced options to fine-tune the rate limiting behavior. Finally, we'll see how to implement 
per-user rate limiting for multi-tenant SaaS applications using ASP.NET Core Identity and ServiceStack Mapped Endpoints.

Setting Up Rate Limiting To get started, let's enable the basic rate limiting middleware in an ASP.NET Core application:

1. Install the `Microsoft.AspNetCore.RateLimiting` NuGet package
2. In the `Program.cs`, add `AddRateLimiter` to register the rate limiting services:

```csharp
builder.Services.AddRateLimiter(options =>
{
    options.GlobalLimiter = PartitionedRateLimiter.Create<HttpContext, string>(httpContext =>
        RateLimitPartition.GetFixedWindowLimiter(
            partitionKey: httpContext.User.Identity?.Name ?? httpContext.Request.Headers.Host.ToString(), 
            factory: partition => new FixedWindowRateLimiterOptions
            {
                AutoReplenishment = true,
                PermitLimit = 100,
                QueueLimit = 0,
                Window = TimeSpan.FromMinutes(1)
            }));
    
    options.OnRejected = (context, cancellationToken) =>
    {
        if (context.Lease.TryGetMetadata(MetadataName.RetryAfter, out var retryAfter))
        {
            context.HttpContext.Response.Headers.RetryAfter = retryAfter.TotalSeconds.ToString();
        }

        context.HttpContext.Response.StatusCode = StatusCodes.Status429TooManyRequests;
        context.HttpContext.Response.WriteAsync("Too many requests. Please try again later.");

        return new ValueTask();
    };
});
```

This sets up a fixed window rate limiter with a limit of 100 requests per minute, partitioned by either authenticated username or client host name.

1. Add the `UseRateLimiter` middleware to the pipeline:

```csharp
app.UseRateLimiter();
```

With this basic setup, the API is now protected from excessive requests from individual clients. 
If a client exceeds the limit of 100 requests/minute, subsequent requests will receive a `HTTP 429 Too Many Requests` response.

Advanced Options The rate limiting middleware provides several options to customize the behavior:

- `PermitLimit` - The maximum number of requests allowed in the time window
- `QueueLimit` - The maximum number of requests that can be queued when the limit is exceeded. Set to 0 to disable queueing.
- `Window` - The time window for the limit, e.g. 1 minute, 1 hour, etc.
- `AutoReplenishment` - Whether the rate limit should reset automatically at the end of each window

For example, to allow short bursts but constrain average rate, we could implement a sliding window algorithm:

```csharp
options.GlobalLimiter = PartitionedRateLimiter.Create<HttpContext, string>(httpContext =>
    RateLimitPartition.GetSlidingWindowLimiter(
        partitionKey: httpContext.User.Identity?.Name ?? httpContext.Request.Headers.Host.ToString(),
        factory: partition => new SlidingWindowRateLimiterOptions
        {
            AutoReplenishment = true,
            PermitLimit = 100,
            QueueLimit = 25,
            Window = TimeSpan.FromMinutes(1),
            SegmentsPerWindow = 4
        }));

options.OnRejected = (context, cancellationToken) =>
{
    if (context.Lease.TryGetMetadata(MetadataName.RetryAfter, out var retryAfter))
    {
        context.HttpContext.Response.Headers.RetryAfter = retryAfter.TotalSeconds.ToString();
    }

    context.HttpContext.Response.StatusCode = StatusCodes.Status429TooManyRequests;
    context.HttpContext.Response.WriteAsync("Too many requests. Please try again later.");

    return new ValueTask();
};
```

This allows up to 100 requests per minute on average, with the ability to burst up to 25 additional requests which are queued.

## Per-User Rate Limiting for SaaS Applications

In a typical SaaS application, each user or tenant may have a different subscription plan that entitles them to a certain level of API usage. 
We can implement this per-user rate limiting by leveraging ASP.NET Core Identity to authenticate users and retrieve their plan details, 
and then configuring the rate limiter accordingly.

First, ensure you have ASP.NET Core Identity set up in your application to handle user authentication. Then, add a property to your 
user class to store the rate limit for each user based on their plan:

```csharp
public class ApplicationUser : IdentityUser
{
    public int RateLimit { get; set; }
}
```

Next, update the rate limiter configuration to partition by user and read the rate limit from the user's plan:

```csharp
builder.Services.AddRateLimiter(options =>
{
    options.AddPolicy("per-user", context =>
    {
        var user = context.User.Identity?.Name;
        if (string.IsNullOrEmpty(user))
        {
            // Fallback to host name for unauthenticated requests
            return RateLimitPartition.GetFixedWindowLimiter(
                partitionKey: context.Request.Headers.Host.ToString(),
                factory: partition => new FixedWindowRateLimiterOptions
                {
                    AutoReplenishment = true,
                    PermitLimit = 100,
                    QueueLimit = 0,
                    Window = TimeSpan.FromMinutes(1)
                });
        }
        // User exists
        // Get the user's rate limit from their plan
        var userId = context.User.FindFirstValue(ClaimTypes.NameIdentifier);
        var userManager = context.RequestServices.GetService<UserManager<ApplicationUser>>();
        var appUser = userManager.FindByIdAsync(userId).Result;
        var rateLimit = appUser?.RateLimit ?? 0;

        // Create a user-specific rate limiter
        return RateLimitPartition.GetFixedWindowLimiter(
            partitionKey: user,
            factory: partition => new FixedWindowRateLimiterOptions
            {
                AutoReplenishment = true,
                PermitLimit = rateLimit,
                QueueLimit = 0,
                Window = TimeSpan.FromMinutes(1)
            });
    });
});
```

This configuration first checks if the request is authenticated. If not, it falls back to the default host-based rate limiting.

For authenticated requests, it retrieves the user ID from the authentication claims and looks up the user in the ASP.NET Core Identity `UserManager`. 
It then reads the `RateLimit` property from the user object, which should be set based on the user's subscription plan.

Finally, it creates a user-specific rate limiter using the `PartitionedRateLimiter` with the user's ID as the partition key and 
their personal rate limit as the `PermitLimit`.

With this setup, each user will be rate limited independently based on their plan allowance. If a user exceeds their personal limit, 
they will receive a `429 Too Many Requests` response, while other users can continue making requests up to their own limits.

Not only that, our rate handling is consistent across ASP.NET Core Endpoints regardless of how they are implemented, be it ServiceStack APIs, 
MVC Controllers, Minimal APIs etc. If you do need to target ServiceStack APIs with a specific policy name, you can create one with a 
policy name and use it when calling `UseServiceStack`.

```csharp
services.AddRateLimiter(options =>
{
    // Policy name "per-user" is used by ServiceStack Mapped Endpoints
    options.AddPolicy("per-user", context =>
    {
        var user = context.User.Identity?.Name;
        if (string.IsNullOrEmpty(user))
        {
            // Fallback to host name for unauthenticated requests
            return RateLimitPartition.GetFixedWindowLimiter(
                partitionKey: context.Request.Headers.Host.ToString(),
                factory: partition => new FixedWindowRateLimiterOptions
                {
                    AutoReplenishment = true,
                    PermitLimit = 100,
                    QueueLimit = 0,
                    Window = TimeSpan.FromMinutes(1)
                });
        }
        // User exists
        // Get the user's rate limit from their plan
        var userId = context.User.FindFirstValue(ClaimTypes.NameIdentifier);
        var userManager = context.RequestServices.GetService<UserManager<ApplicationUser>>();
        var appUser = userManager.FindByIdAsync(userId).Result;
        var rateLimit = appUser?.RateLimit ?? 0;

        // Create a user-specific rate limiter
        return RateLimitPartition.GetFixedWindowLimiter(
            partitionKey: user,
            factory: partition => new FixedWindowRateLimiterOptions
            {
                AutoReplenishment = true,
                PermitLimit = rateLimit,
                QueueLimit = 0,
                Window = TimeSpan.FromMinutes(1)
            });
    });
    
    // ...
});

//...

// Make sure to call UseRateLimiter
app.UseRateLimiter();

// Specify which policy is used by ServiceStack Mapped Endpoints
app.UseServiceStack(new AppHost(), options => {
    options.MapEndpoints();
    options.RouteHandlerBuilders.Add((routeBuilder, operation, method, route) =>
    {
        routeBuilder.RequireRateLimiting(policyName: "per-user");
    });
});
```

By combining ASP.NET Core rate limiting with ASP.NET Core Identity in this way, you can implement flexible, per-user rate limiting 
suitable for multi-tenant SaaS applications. The same approach can be extended to handle different rate limits for different API endpoints 
or user roles as needed. By upgrading ServiceStack to use ASP.NET Core Endpoints, you can now leverage the same rate limiting middleware 
across all ASP.NET Core Endpoints, including ServiceStack APIs.


# Order of Operations
Source: https://docs.servicestack.net/order-of-operations

## HTTP Custom hooks

This list shows the order in which any user-defined custom hooks are executed.

The first set of filters is used to return the matching `IHttpHandler` for the request:

  1. `HostContext.RawHttpHandlers` are executed before anything else, i.e. returning any ASP.NET `IHttpHandler` by-passes ServiceStack completely and processes your custom `IHttpHandler` instead.
  2. Request is checked if matches any registered routes or static files and directories
  3. If the Request doesn't match it will search `IAppHost.CatchAllHandlers` for a match
  4. `IAppHost.FallbackHandlers` is the last handler executed for finding a handler to handle the request

Any unmatched requests will not be handled by ServiceStack and either returns a 404 NotFound Response in **ASP.NET** or **HttpListener** AppHosts or 
executes the next middleware in-line in **.NET Core** Apps.

Requests handled by ServiceStack execute the custom hooks and filters in the following order:

  1. The `IAppHost.PreRequestFilters` gets executed before the Request DTO is deserialized
  2. Default Request DTO Binding or [Custom Request Binding](/serialization-deserialization#create-a-custom-request-dto-binder) _(if registered)_
  3. Any [Request Converters](/customize-http-responses#request-converters) are executed
  4. [Request Filter Attributes][3] with **Priority < 0** gets executed
  5. Then any [Global Request Filters][1] get executed
  6. Followed by [Request Filter Attributes][3] with **Priority >= 0**
  7. Action Request Filters
  8. Then your **Service is executed** with the configured [Service Filters](/customize-http-responses#intercept-service-requests) and [Service Runner](/customize-http-responses#using-a-custom-servicerunner) **OnBeforeExecute**, **OnAfterExecute** and **HandleException** custom hooks are fired
  9. Action Response Filters
  10. Any [Response Converters](/customize-http-responses#response-converters) are executed
  11. Followed by [Response Filter Attributes][3] with **Priority < 0** 
  12. Then [Global Response Filters][1] 
  13. Followed by [Response Filter Attributes][3] with **Priority >= 0** 
  14. Finally at the end of the Request `IAppHost.OnEndRequest` and any `IAppHost.OnEndRequestCallbacks` are fired

Any time you close the Response in any of your filters, i.e. `httpRes.EndRequest()` the processing of the response is short-circuited and no further processing is done on that request.

## Internal Service Gateway Requests

Internal [Service Gateway](/service-gateway) Requests are executed using `ServiceController.GatewayExecuteAsync` API for invoking **internal/trusted** Services:

  1. Any `Gateway` [Global Request Filters](/request-and-response-filters#global-request-and-response-filters) get executed
  2. Any Validation Filters
  3. Action Request Filters
  4. Then your **Service is executed** with the configured [IServiceRunner](https://github.com/ServiceStack/ServiceStack/blob/master/src/ServiceStack.Interfaces/Web/IServiceRunner.cs) and its **OnBeforeExecute**, **OnAfterExecute** and **HandleException** custom hooks are fired
  5. Action Response Filters
  6. Then `Gateway` [Global Response Filters](/request-and-response-filters#global-request-and-response-filters) 

## MQ (non-HTTP) Custom hooks

MQ Requests are executed using `ServiceController.ExecuteMessage` for invoking **internal/trusted** Services such as [ServiceStack MQ](/messaging):

  1. Any `Message` [Global Request Filters](/request-and-response-filters#message-queue-endpoints) get executed
  2. Action Request Filters
  3. Then your **Service is executed** with the configured [IServiceRunner](https://github.com/ServiceStack/ServiceStack/blob/master/src/ServiceStack.Interfaces/Web/IServiceRunner.cs) and its **OnBeforeExecute**, **OnAfterExecute** and **HandleException** custom hooks are fired
  4. Action Response Filters
  5. Then `Message` [Global Response Filters](/request-and-response-filters#message-queue-endpoints) 
  6. Finally at the end of the Request `IAppHost.OnEndRequest` is fired

## RpcGateway

The `RpcGateway` provides a pure object model API for executing requests through the full HTTP Request pipeline including converting all Errors 
inc. short-circuited Request Pipeline requests into an Error ResponseStatus that's populated into the Response DTO's `ResponseStatus`.

The `RpcGateway` is available via the single `AppHost.RpcGateway` API:

```csharp
Task<TResponse> ExecuteAsync<TResponse>(object requestDto, IRequest req)
```

Unlike MQ Requests which uses `ServiceController.ExecuteMessage` to execute **internal/trusted** Services, the `RpcGateway` executes the full 
**HTTP Request Pipeline** below: 

  1. The `IAppHost.PreRequestFilters` gets executed before the Request DTO is deserialized
  2. Any [Request Converters](/customize-http-responses#request-converters) are executed
  3. [Request Filter Attributes][3] with **Priority < 0** gets executed
  4. Then any [Global Request Filters][1] get executed
  5. Followed by [Request Filter Attributes][3] with **Priority >= 0**
  6. Action Request Filters
  7. Then your **Service is executed** with the configured [Service Filters](/customize-http-responses#intercept-service-requests) and [Service Runner](/customize-http-responses#using-a-custom-servicerunner) **OnBeforeExecute**, **OnAfterExecute** and **HandleException** custom hooks are fired
  8. Action Response Filters
  9. Any [Response Converters](/customize-http-responses#response-converters) are executed
  10. Followed by [Response Filter Attributes][3] with **Priority < 0** 
  11. Then [Global Response Filters][1] 
  12. Followed by [Response Filter Attributes][3] with **Priority >= 0** 
  13. Finally at the end of the Request `IAppHost.OnEndRequest` and any `IAppHost.OnEndRequestCallbacks` are fired

Where requests are executed through the same global Request/Response filters that normal HTTP ServiceStack Services execute
making them suitable for executing external **untrusted** requests.

## Implementation architecture diagram

The [Implementation architecture diagram][2] shows a visual cue of the internal order of operations that happens in ServiceStack:

![ServiceStack Overview](/img/pages/overview/servicestack-overview-01.png)

After the IHttpHandler is returned, it gets executed with the current ASP.NET or HttpListener request wrapped in a common [IHttpRequest](https://github.com/ServiceStack/ServiceStack/blob/master/src/ServiceStack.Interfaces/ServiceHost/IHttpRequest.cs) instance. 

The implementation of [RestHandler](https://github.com/ServiceStack/ServiceStack/blob/master/src/ServiceStack/WebHost.Endpoints/RestHandler.cs) shows what happens during a typical ServiceStack request:

![ServiceStack Request Pipeline](/img/pages/overview/servicestack-overview-02.png)

  [1]: /request-and-response-filters
  [2]: /architecture-overview
  [3]: /filter-attributes


# Customize HTTP Responses
Source: https://docs.servicestack.net/customize-http-responses

ServiceStack provides multiple ways to customize your services HTTP response. Each option gives you complete control of the final HTTP Response that's returned by your service: 

  1. Decorating it inside a `HttpResult` object
  2. Throwing a `HttpError` 
  3. Returning a `HttpError`
  4. Using a Request or Response [Filter Attribute](/filter-attributes) like the built-in `[AddHeader]` (or your own) or using a [Global Request or Response Filter](/request-and-response-filters).
  5. Modifying output by accessing your services `base.Response` [IHttpResponse API](https://github.com/ServiceStack/ServiceStack/blob/master/src/ServiceStack.Interfaces/Web/IHttpResponse.cs)
  6. Returning responses in a decorated `HttpResult`

Here are some code examples below using these different approaches:

```csharp
public class HelloService : Service
{ 
    public object Get(Hello request) 
    { 
        //1. Returning a custom Status and Description with Response DTO body:
        var responseDto = ...;
        return new HttpResult(responseDto, HttpStatusCode.Conflict) {
            StatusDescription = "Computer says no",
        };

        //2. Throw a HttpError:
        throw new HttpError(HttpStatusCode.Conflict, "Some Error Message");

        //3. Return a HttpError:
        return new HttpError(HttpStatusCode.Conflict, "Some Error Message");

        //4. Modify the Request's IHttpResponse
        base.Response.StatusCode = (int)HttpStatusCode.Redirect;
        base.Response.AddHeader("Location", "http://path/to/new/uri");
        base.Response.EndRequest(); //Short-circuits Request Pipeline
    }

    //5. Using a Request or Response Filter 
    [AddHeader(ContentType = "text/plain")]
    [AddHeader(ContentDisposition = "attachment; filename=hello.txt")]
    public string Get(Hello request)
    {
        return $"Hello, {request.Name}!";
    }

    //6. Returning responses in a decorated HttpResult
    public object Get(Hello request)
    {
        return new HttpResult($"Hello, {request.Name}!") {
            ContentType = MimeTypes.PlainText,
            Headers = {
                [HttpHeaders.ContentDisposition] = "attachment; filename=\"hello.txt\""
            }
        };
    }
}
```

### Short-circuiting the Request Pipeline

At anytime you can short-circuit the Request Pipeline and end the response by calling `IResponse.EndRequest()`, e.g:

```csharp
res.EndRequest();
```

If you only have access to the `IRequest` you can access the `IResponse` via the Response property, e.g:

```csharp
req.Response.EndRequest();
```

### Using a [Global Request or Response Filter](/request-and-response-filters)

You can use a Global Request Filter to set Custom HTTP Headers and then short-circuit the request:

```csharp
public override void Configure(Container container) 
{ 
    GlobalRequestFilters.Add((req, res, requestDto) => 
    {
        if (req.Verb == HttpMethods.Head && requestDto is DownloadTrack track)
        {
            var dep = req.TryResolve<IDependency>();

            res.ContentType = "audio/mpeg";
            res.AddHeader("X-Genre", dep.GetGenre(track));
            res.SetContentLength(dep.CalculateLength(track));
            res.EndRequest();
        }
    });
}
```

### Using a [Request or Response Filter Attribute](/filter-attributes)

Example 4). uses the in-built [AddHeaderAttribute](https://github.com/ServiceStack/ServiceStack/blob/master/src/ServiceStack/AddHeaderAttribute.cs) to modify the HTTP Response using a [Request Filter attribute](/filter-attributes). You can also modify all HTTP Service Responses by using a [Global Request or Response Filter](/request-and-response-filters): 

```csharp
public class AddHeaderAttribute : RequestFilterAttribute
{
    public string Name { get; set; }
    public string Value { get; set; }
    
    public AddHeaderAttribute() { }

    public AddHeaderAttribute(string name, string value)
    {
        Name = name;
        Value = value;
    }

    public override void Execute(IRequest req, IResponse res, object requestDto)
    {
        if (string.IsNullOrEmpty(Name) || string.IsNullOrEmpty(Value)) 
            return;

        if (Name.EqualsIgnoreCase(HttpHeaders.ContentType))
        {
            res.ContentType = Value;
        }
        else
        {
            res.AddHeader(Name, Value);
        }
    }
...
}
```

## Custom Serialized Responses

The new `IHttpResult.ResultScope` API provides an opportunity to execute serialization within a custom scope, e.g. this can
be used to customize the serialized response of adhoc services that's different from the default global configuration with:

```csharp
return new HttpResult(dto) {
    ResultScope = () => JsConfig.With(new Config { IncludeNullValues =  true })
};
```

Which enables custom serialization behavior by performing the serialization within the custom scope, equivalent to:

```csharp
using (JsConfig.With(new Config { IncludeNullValues =  true }))
{
    var customSerializedResponse = Serialize(dto);
}
```

## Request and Response Converters

The [Encrypted Messaging Feature](/auth/encrypted-messaging) takes advantage of Request and Response Converters that let you change the Request DTO and Response DTO's that get used in ServiceStack's Request Pipeline where:

### Request Converters

Request Converters are executed directly after any [Custom Request Binders](/serialization-deserialization#create-a-custom-request-dto-binder):

```csharp
appHost.RequestConverters.Add(async (req, requestDto) => {
    //Return alternative Request DTO or null to retain existing DTO
});
```

### Response Converters

Response Converters are executed directly after the Service:

```csharp
appHost.ResponseConverters.Add(async (req, response) =>
    //Return alternative Response or null to retain existing Service response
});
```

### Intercept Service Requests

As an alternative to creating a [Custom Service Runner](#using-a-custom-servicerunner) to intercept
different events when processing ServiceStack Requests, you can instead override the `OnBeforeExecute()`, `OnAfterExecute()` and `OnExceptionAsync()`
callbacks in your `Service` class (or base class) to intercept and modify Request DTOs, Responses or Error Responses, e.g:

```csharp
class MyServices : Service
{
    // Log all Request DTOs that implement IHasSessionId
    public override void OnBeforeExecute(object requestDto)
    {
        if (requestDto is IHasSessionId dtoSession)
        {
            Log.Debug($"{nameof(OnBeforeExecute)}: {dtoSession.SessionId}");
        }
    }

    //Return Response DTO Name in HTTP Header with Response
    public override object OnAfterExecute(object response)
    {
        return new HttpResult(response) {
            Headers = {
                ["X-Response"] = response.GetType().Name
            }
        };
    }

    //Return custom error with additional metadata
    public override Task<object> OnExceptionAsync(object requestDto, Exception ex)
    {
        var error = DtoUtils.CreateErrorResponse(requestDto, ex);
        if (error is IHttpError httpError)
        {                
            var errorStatus = httpError.Response.GetResponseStatus();
            errorStatus.Meta = new Dictionary<string,string> {
                ["InnerType"] = ex.InnerException?.GetType().Name
            };
        }
        return Task.FromResult(error);
    }
}
```

#### Async Callbacks

For async callbacks your Services can implement `IServiceBeforeFilterAsync` and `IServiceAfterFilterAsync`, e.g:

```csharp
public class MyServices : Service, IServiceBeforeFilterAsync, IServiceAfterFilterAsync
{
    public async Task OnBeforeExecuteAsync(object requestDto)
    {
        //...
    }

    public async Task<object> OnAfterExecuteAsync(object response)
    {
        //...
        return response;
    }
}
```

If you're implementing `IService` instead of inheriting the concrete `Service` class, you can implement the interfaces directly:

```csharp
// Handle all callbacks
public class MyServices : IService, IServiceFilters
{
    //..
}

// Or individually, just the callbacks you want
public class MyServices : IService, IServiceBeforeFilter, IServiceAfterFilter, IServiceErrorFilter
{
    //..
}
```

### Using a Custom ServiceRunner

The ability to extend ServiceStack's service execution pipeline with Custom Hooks is an advanced customization feature that for most times is not needed as the preferred way to add composable functionality to your services is to use [Request / Response Filter attributes](/filter-attributes) or apply them globally with [Global Request/Response Filters](/request-and-response-filters).

To be able to add custom hooks without needing to subclass any service, we've introduced a [IServiceRunner](https://github.com/ServiceStack/ServiceStack/blob/master/src/ServiceStack.Interfaces/Web/IServiceRunner.cs) that decouples the execution of your service from the implementation of it.

To add your own Service Hooks you just need to override the default Service Runner in your AppHost from its default implementation:

```csharp
public virtual IServiceRunner<TRequest> CreateServiceRunner<TRequest>(
    ActionContext actionContext)
{
    //Cached per Service Action
    return new ServiceRunner<TRequest>(this, actionContext); 
}
```

With your own:

```csharp
public override IServiceRunner<TRequest> CreateServiceRunner<TRequest>(
    ActionContext actionContext)
{           
    //Cached per Service Action
    return new MyServiceRunner<TRequest>(this, actionContext); 
}
```

Where `MyServiceRunner<T>` is just a custom class implementing the custom hooks you're interested in, e.g:

```csharp
public class MyServiceRunner<T> : ServiceRunner<T> 
{
    public override OnBeforeExecute(IRequest req, TRequest request, object service) {
      // Called just before any Action is executed
    }

    public override Task<object> ExecuteAsync(IRequest req, object instance, TRequest requestDto) {
        // Called to execute the Service instance with the requestDto
        return base.ExecuteAsync(req, serviceInstance, requestDto);
    }

    public override object OnAfterExecute(IRequest req, object response, object service) {
      // Called just after any Action is executed, you can modify the response returned here as well
    }

    public override Task<object> HandleExceptionAsync(IRequest req, TRequest requestDto, Exception ex, object instance) {
      // Called whenever an exception is thrown in your Services Action
    }
}
```


# Customize JSON Responses
Source: https://docs.servicestack.net/customize-json-responses

The JSON Responses for all ServiceStack Services can be configured Globally, individually per-Service or customized per-request by the client using the `?jsconfig` QueryString modifier.

## Global Default JSON Configuration

ServiceStack uses the [ServiceStack.Text Serializers](/formats) for its built-in JSON/JSV and CSV serialization. The serialization can be customized globally by configuring the `JsConfig` or type-specific `JsConfig<T>` static classes with your preferred defaults, e.g:

```csharp
public override void Configure(Container container)
{
    JsConfig.Init(new ServiceStack.Text.Config {
        TextCase = TextCase.SnakeCase,
        ExcludeDefaultValues = true,
    });

    JsConfig<Guid>.SerializeFn = guid => guid.ToString("D");
    JsConfig<TimeSpan>.SerializeFn = time => 
        (time.Ticks < 0 ? "-" : "") + time.ToString("hh':'mm':'ss'.'fffffff");
}
```

## Customize JSON Responses in Service

The Global Defaults can be overridden on a adhoc basis by returning your Response DTO in a custom `HttpResult` configured with a custom JS Config Scope, e.g:

```csharp
return new HttpResult(responseDto) {
    ResultScope = () => 
        JsConfig.With(new Config { IncludeNullValues = true, ExcludeDefaultValues = true })
};
```

This has the same behavior for your Service Responses as creating a Custom Config Scope for adhoc Serialization that overrides Global Configuration, e.g:

```csharp
using (JsConfig.With(new Config { IncludeNullValues = true, ExcludeDefaultValues = true }))
{
    var json = dto.ToJson();
}
```

## Customize JSON Responses from Client

The JSON and JSV Responses for all Services (inc. [Auto Query](/autoquery/) Services) can also be further customized with the 
new `?jsconfig` QueryString param which lets your Service consumers customize the returned JSON Response to 
their preference. This works similar to having wrapped your Service response in a `HttpResult` with a Custom 
`ResultScope` in the Service implementation to enable non-default customization of a Services response, e.g:

```
/service?jsconfig=EmitLowercaseUnderscoreNames,ExcludeDefaultValues
```

Works similarly to:

```csharp
return new HttpResult(new { TheKey = "value", Foo=0 }) {
    ResultScope = () => 
        JsConfig.With(new Config { TextCase = TextCase.SnakeCase, ExcludeDefaultValues = true })
};
```

Which results in **lowercase_underscore** key names with any properties with **default values removed**:

```json
{"the_key":"value"}
```

It also supports cascading server and client ResultScopes, with the client `?jsconfig` taking precedence.

Nearly all `JsConfig` scope options are supported other than delegates and complex type configuration properties.

### Camel Humps Notation

JsConfig also supports Camel Humps notation letting you target a configuration by just using the 
**Uppercase Letters** in the property name which is also case-insensitive so an equivalent shorter version 
of the above config can be:

```
?jsconfig=ELUN,edv
```

Camel Humps also works with Enum Values so both these two configurations are the same:

```
?jsconfig=DateHandler:UnixTime
?jsconfig=dh:ut
```

### Custom JSON Live Example

[AutoQuery Viewer](https://github.com/ServiceStack/Admin) makes use of this feature in order to return human readable dates using the new 
`ISO8601DateOnly` DateHandler Enum Value as well as appending `ExcludeDefaultValues` when specifying custom 
fields so that any unpopulated value type properties with default values are excluded from the JSON Response. 

### Custom JSON Settings

The presence of a **bool** configuration property will be set to `true` unless they have a `false` or `0` 
value in which case they will be set to `false`, e.g:

```
?jsconfig=ExcludeDefaultValues:false
```

For a quick reference the following **bool** customizations are supported:

<table class="table">
    <thead>
        <tr><th>Name</th><th>Alias</th></tr>
    </thead>
    <tr><td>EmitCamelCaseNames</td><td>eccn</td></tr>
    <tr><td>EmitPascalCaseNames</td><td>epcn</td></tr>
    <tr><td>EmitLowercaseUnderscoreNames</td><td>elun</td></tr>
    <tr><td>ExcludeDefaultValues</td><td>edv</td></tr>
    <tr><td>IncludeNullValues</td><td>inv</td></tr>
    <tr><td>IncludeNullValuesInDictionaries</td><td>invid</td></tr>
    <tr><td>IncludeDefaultEnums</td><td>ide</td></tr>
    <tr><td>IncludePublicFields</td><td>ipf</td></tr>
    <tr><td>IncludeTypeInfo</td><td>iti</td></tr>
    <tr><td>ExcludeTypeInfo</td><td>eti</td></tr>
    <tr><td>ConvertObjectTypesIntoStringDictionary</td><td>cotisd</td></tr>
    <tr><td>TreatEnumAsInteger</td><td>teai</td></tr>
    <tr><td>TryToParsePrimitiveTypeValues</td><td>ttpptv</td></tr>
    <tr><td>TryToParseNumericType</td><td>ttpnt</td></tr>
    <tr><td>ThrowOnDeserializationError</td><td>tode</td></tr>
    <tr><td>PreferInterfaces</td><td>pi</td></tr>
    <tr><td>SkipDateTimeConversion</td><td>sdtc</td></tr>
    <tr><td>AlwaysUseUtc</td><td>auu</td></tr>
    <tr><td>AssumeUtc</td><td>au</td></tr>
    <tr><td>AppendUtcOffset</td><td>auo</td></tr>
    <tr><td>EscapeHtmlChars</td><td>ehc</td></tr>
    <tr><td>EscapeUnicode</td><td>eu</td></tr>
</table>

### DateHandler (dh)

<table class="table">
    <tr><td>TimestampOffset</td><td>to</td></tr>
    <tr><td>DCJSCompatible</td><td>dcjsc</td></tr>
    <tr><td>ISO8601</td><td>iso8601</td></tr>
    <tr><td>ISO8601DateOnly</td><td>iso8601do</td></tr>
    <tr><td>ISO8601DateTime</td><td>iso8601dt</td></tr>
    <tr><td>RFC1123</td><td>rfc1123</td></tr>
    <tr><td>UnixTime</td><td>ut</td></tr>
    <tr><td>UnixTimeMs</td><td>utm</td></tr>
</table>

### TimeSpanHandler (tsh)

<table class="table">
    <tr><td>DurationFormat</td><td>df</td></tr>
    <tr><td>StandardFormat</td><td>sf</td></tr>
</table>

### PropertyConvention (pc)

<table class="table">
    <tr><td>Strict</td><td>s</td></tr>
    <tr><td>Lenient</td><td>l</td></tr>
</table>

#### Create Custom Scopes using String config

You can also create a scope from a string manually using `JsConfig.CreateScope()`, e.g:

```csharp
using (JsConfig.CreateScope("EmitLowercaseUnderscoreNames,ExcludeDefaultValues,dh:ut")) 
{
    var json = dto.ToJson();
}
```

If you don't wish for consumers to be able to customize JSON responses this feature can be disabled with 
`Config.AllowJsConfig=false`.

### Accept arbitrary JavaScript or JSON Objects

Whilst we recommend creating well-defined, Typed Service Contracts for your Services, there are rare situations where you'd want to be able to accept an arbitrary JSON payload, an example of this is with integration hooks with a 3rd party provider that calls back into your Service with a custom JSON payload, e.g:

```csharp
[Route("/callback")]
public class Callback : IReturn<CallbackResponse>
{
    public object Payload { get; set; }
}
```

ServiceStack `object` properties are now deserialized using `#Script` [JS Utils](/js-utils) which can parse any JavaScript or JSON data structure. So if a POST callback was sent to the above service containing: 

```
POST /callback

{"payload": {"id":1,"name":"foo", "List": [{"id":2,"name":"bar"}], "Dictionary": {"key":{"id":3,"name":"bax"}} }}
```

It will parsed into the appropriate .NET Types and generic collections which can be accessed with:

```csharp
public object Any(Callback request)
{
    var payload = request.Object as Dictionary<string,object>;
    var id = payload["id"];                             //= 1
    var name = payload["name"];                         //= foo
    var list = payload["List"] as List<object>;
    var firstListItem = list[0] as Dictionary<string, object>;
    var firstListName = firstListItem["name"];          //= bar
    var dictionary = payload["Dictionary"] as Dictionary<string, object>;
    var dictionaryValue = dictionary["Key"] as Dictionary<string, object>;
    var dictionaryValueName = dictionaryValue["name"];  //= baz
}
```

As it's using [JS Utils](/js-utils) it can also accept JavaScript object literal syntax, e.g: `{ payload: { id: 1 } }`.

#### Avoid unknown Types in ServiceContracts

Whilst this feature enables some flexibility by effectively poking a hole in your Service Contract as a placeholder for any arbitrary JS data structure, we still recommend only using `object` properties sparingly when it's needed as it only works with JSON/JSV Services, is subject to 
[security restrictions](/json-format#late-bound-object-and-interface-runtime-types), 
can't be documented in Metadata Services and isn't supported in most [Add ServiceStack Reference](/add-servicestack-reference) languages.


# Configuration &amp; AppSettings
Source: https://docs.servicestack.net/appsettings

Instead of building verbose nested XML configSection classes our preference is to instead store structured configuration in Web.config's `<appSetting/>` which can still express rich config graphs but in a much more human-friendly and manageable way.

ServiceStack's pluggable `IAppSettings` API is a cleaner alternative for storing your Application structured configuration, providing a high-level API to read your Web.config's `<appSetting/>` values into a `List`, `Dictionary` or your own clean Custom POCO Types using the human friendly [JSV format](/jsv-format). 

```csharp
public interface IAppSettings
{
    Dictionary<string, string> GetAll();
         
    List<string> GetAllKeys();

    bool Exists(string key);

    void Set<T>(string key, T value);

    string GetString(string name);

    IList<string> GetList(string key);

    IDictionary<string, string> GetDictionary(string key);

    T Get<T>(string name);

    T Get<T>(string name, T defaultValue);
}
``` 

Benefits over existing Configuration API include the ability to store rich data structures in appSettings values, more succinct access to typed data and since its an interface it's decoupled from .NET Configuration classes and can easily be swapped to source your configuration from an different sources without a rewrite, e.g. from a text file or central DB.

### Example Usage

```xml
<appSettings>
    <add key="LastUpdated" value="01/01/2012 12:00:00" />
    <add key="AllowedUsers" value="Tom,Mick,Harry" />
    <add key="RedisConfig" 
         value="{Host:localhost,Port:6379,Database:1,Timeout:10000}" />
</appSettings>
```

Reading the above configuration in code:

```csharp
IAppSettings appSettings = new AppSettings();
DateTime lastUpdate = appSettings.Get<DateTime>("LastUpdated");
IList<string> allowedUsers = appSettings.GetList("AllowedUsers");
RedisConfig redisConf = appSettings.Get<RedisConfig>("RedisConf");

//use default value if no config exists
var searchUrl = appSettings.Get("SearchUrl", "http://www.google.com"); 
```

The last default value provides a convenient way to maintain workable default options in code (allowing re-use in Unit/Integration tests) whilst still being overridable in the **Web.config** when you need to.

## Multi AppSettings

The `MultiAppSettings` AppSettings provider enables reading configuration from multiple configuration sources.

### Example Usage 

The example below creates a cascading configuration that first checks Environment variables, then looks in a local `~/appsettings.txt` plain-text file before falling back to `Web.config`: 

```csharp
AppSettings = new MultiAppSettings(
    new EnvironmentVariableSettings(),
    new TextFileSettings("~/appsettings.txt".MapHostAbsolutePath()),
    new AppSettings());
```

### Multi AppSettings Builder

An alternative is to use `MultiAppSettingsBuilder` if you prefer to use a fluent discoverable API:

```csharp
AppSettings = new MultiAppSettingsBuilder()
    .AddAppSettings()
    .AddDictionarySettings(new Dictionary<string,string> { "override" : "setting" })
    .AddEnvironmentalVariables()
    .AddTextFile("~/path/to/settings.txt".MapProjectPath())
    .Build();
```

## OrmLite AppSettings

`OrmLiteAppSettings` provides an alternative read/write API that lets you maintain your applications configuration in any [RDBMS back-end OrmLite supports](https://github.com/ServiceStack/ServiceStack.OrmLite/#download). It works like a mini Key/Value database in which can store any serializable value against any key which is maintained into the simple Id/Value `ConfigSettings` table.

### Usage

Registration just uses an OrmLite DB Factory, e.g:

```csharp
container.Register(c => 
    new OrmLiteAppSettings(c.Resolve<IDbConnectionFactory>()));
//Create the ConfigSettings table if it doesn't exist
container.Resolve<OrmLiteAppSettings>().InitSchema(); 
```

It then can be accessed like any [AppSetting APIs](https://github.com/ServiceStack/ServiceStack/blob/master/tests/ServiceStack.Common.Tests/Configuration/AppSettingsTests.cs). The example below reads the `MyConfig` POCO stored at `config` otherwise use default value if it doesn't exist: 

```csharp
var config = appSettings.Get("config", 
    new MyConfig { Key = "DefaultValue" });
```

In addition to the AppSettings read-only API's, it also supports writing config values , e.g:

```csharp
var latestStats = appSettings.GetOrCreate("stats", 
    () => statsProvider.GetLatest());
```

## EnvironmentVariableSettings

The new `EnvironmentVariableSettings` AppSettings provider to source configuration from Environment variables:

```csharp
var appSettings = new EnvironmentVariableSettings();
```

## TextFileSettings

The `TextFileSettings` lets you read your Applications configuration in a plain-text file, which can easily be overridden with custom environment settings as part of the CI deployment process, providing a nice alternative to custom Web.config configurations.

### Example Usage

To use just provide the path to the plain-text file that contains the app-settings: 

```csharp
var appSettings = new TextFileSettings("~/app.settings".MapHostAbsolutePath());
```

### TextFile Format

Each appSetting is on a new line with the **Key** and **Value** separated by a space:

```
{Key} {Value}\n
```

> The delimiter can be changed in the constructor e.g. `new TextFileSettings(path,delimiter:": ");`

### Extract key / value settings from text file

Under the hood TextFileSettings uses the ParseKeyValueText extension method to extract key / value data from a string, e.g: 

```csharp
var configText = @"
# comments starting with '#' and blank lines are ignored

StringKey string value
IntKey 42
ListKey A,B,C,D,E
DictionaryKey A:1,B:2,C:3,D:4,E:5
PocoKey {Foo:Bar,Key:Value}";

Dictionary<string, string> configMap = 
    configText.ParseKeyValueText(delimiter:" ");
```

## DictionarySettings

When combined with the existing `DictionarySettings`, enables a rich, simple and clean alternative to .NET's App.config config section for reading structured configuration into clean data structures, e.g:

```csharp
IAppSettings settings = new DictionarySettings(configMap);

string value = settings.Get("StringKey");

int value = settings.Get("IntKey", defaultValue:1);

List<string> values = settings.GetList("ListKey");

Dictionary<string,string> valuesMap = settings.GetDictionary("key");

MyConfig config = settings.Get("key", new MyConfig { Key = "default"});
```

### SimpleAppSettings

`SimpleAppSettings` is an alternative Dictionary-based provider that only requires a dependency to `ServiceStack.Common`, e.g:

```csharp
AppSettings = new SimpleAppSettings(new Dictionary<string, string> {
    ["string"] = "value",
    ["EnableFeature.1"] = "true",
    ["AllowedUsers"] = "Tom,Mick,Harry",
}));

string value = AppSettings.GetString("string");
bool enableFeature1 = AppSettings.Get("EnableFeature.1", defaultValue:false);
bool enableFeature2 = AppSettings.Get("EnableFeature.2", defaultValue:false);
IList<string> allowedUsers = AppSettings.GetList("AllowedUsers");
```

## [DynamoDbAppSettings](https://github.com/ServiceStack/ServiceStack/blob/master/docs/2015/release-notes.md#dynamodbappsettings)

Storing production config in DynamoDB reduces the effort for maintaining production settings decoupled from source code. 
Here `DynamoDbAppSettings` is registered first in a `MultiAppSettings` collection it checks entries in the DynamoDB `ConfigSetting` Table first before falling back to local **Web.config** appSettings:

```csharp
#if !DEBUG
    AppSettings = new MultiAppSettings(
        new DynamoDbAppSettings(new PocoDynamo(awsDb), initSchema:true),
        new AppSettings()); // fallback to Web.confg
#endif
```

## First class AppSettings

After proving its value over the years we've decided to make it a first-class property on `IAppHost.AppSettings` which defaults to looking at .NET's App/Web.config's. 

The new [Chat.zip](https://github.com/ServiceStack/ServiceStack.Gap/raw/master/deploy/Chat.zip) App explores different ways AppSettings can be used: 

If there's an existing `appsettings.txt` file where the **.exe** is run it will use that, otherwise it falls back to **Web.config** appSettings:

```csharp
public AppHost() : base("Chat", typeof (ServerEventsServices).Assembly)
{
    var customSettings = new FileInfo("appsettings.txt");
    AppSettings = customSettings.Exists
        ? (IAppSettings)new TextFileSettings(customSettings.FullName)
        : new AppSettings();
}
```

As a normal property in your AppHost, AppSettings can be accessed directly in `AppHost.Configure()`:

```csharp
public void Configure(Container container)
{
    ...
    var redisHost = AppSettings.GetString("RedisHost");
    if (redisHost != null)
    {
        container.Register<IServerEvents>(c => 
            new RedisServerEvents(new PooledRedisClientManager(redisHost)));
        
        container.Resolve<IServerEvents>().Start();
    }
}
```

Inside your services or IOC dependencies, like any other auto-wired dependency:

```csharp
public class ServerEventsServices : Service
{
    public IAppSettings AppSettings { get; set; }

    public void Any(PostRawToChannel request)
    {
        if (!IsAuthenticated && AppSettings.Get("LimitRemoteControlToAuthenticatedUsers", false))
            throw new HttpError(HttpStatusCode.Forbidden, "You must be authenticated to use remote control.");
        ...
    }   
}
```

Directly within Razor views:

```html
<style>
body {
    background-image: url(@AppSettings.Get("background","/img/bg.jpg")) 
}
</style>
```

As well as outside ServiceStack, via the `HostContext` static class:

```csharp
var redisHost = HostContext.AppSettings.GetString("redis");
```

## AppSettings are Writable

A new `Set()` API was added to [IAppSettings](https://github.com/ServiceStack/ServiceStack/blob/master/src/ServiceStack.Interfaces/Configuration/IAppSettings.cs) letting you save any serializable property that works for all providers:

```csharp
public interface IAppSettings
{
    void Set<T>(string key, T value);
    ...
}

AppSettings.Set("Poco", new MyConfig { Foo = "Baz" });
```

In providers that support writable configuration natively like `OrmLiteAppSettings` and `DictionarySettings`, the settings get written through to the underlying provider. For read-only providers like Web.config's `AppSettings` or `TextFileSettings` a **shadowed** cache is kept that works similar to prototypal shadowing in JavaScript where if a property doesn't exist, setting a property will be stored on the top-level object instance which also takes precedence on subsequent property access.

# IConfiguration

To create AppSettings from IConfiguration object

```csharp
AppSettings = new NetCoreAppSettings(configuration);
```

# Community AppSettings

## [ServiceStack.Configuration.Consul](https://github.com/MacLeanElectrical/servicestack-configuration-consul)

An implementation of IAppSettings that uses Consul.io key/value store as backing storage


# Metadata Pages
Source: https://docs.servicestack.net/metadata-page

ServiceStack will automatically generate a metadata page about the webservice. The metadata can be found under the URL `/metadata`:

![](/img/pages/metadata/metadata-chat.webp)

The Metadata page contains:

  - List of all visible web services and the endpoints they're accessible on
  - Links to a detailed page of each format, with example request and responses
  - Links to SOAP 1.1/1.2 WSDLs
  - Links to all XSD types for all services
  - Links to internally available debug metadata info
  - Links to Client examples documentation

The metadata pages provide automatic generated documentation around your services, allowing consumers of your APIs to more easily introspect and provide greater visibility of your services. 

## Annotating Services

You can also optionally add custom annotations and documentation on services which will automatically appear on the metadata pages. Here is an example of a fully annotated Service:

```csharp
[Api("Service Description")]
[Route("/swagger/{Name}", "GET", Summary = "GET Summary", Notes="Notes")]
[Route("/swagger/{Name}", "POST", Summary ="POST Summary", Notes="Notes")]
public class SwaggerTest
{
    [ApiMember(Name="Name", Description = "Name Description", 
        ParameterType = "path", DataType = "string", IsRequired = true)]
    public string Name { get; set; }
}
```

If now the detail page of the specific service is inspected, the description configured above will be displayed on both the [Open API](/openapi) and Metadata Detail Page:

![](/img/pages/metadata/metadata-swagger-api.webp)

### Group Services by Tag

Services can also be [grouped by Tag](/api-design#group-services-by-tag) by annotating them with the `[Tag]` attribute:

```csharp
[Tag("web")]
public class WebApi : IReturn<MyResponse> {}

[Tag("mobile")]
public class MobileApi : IReturn<MyResponse> {}

[Tag("web"),Tag("mobile")]
public class WebAndMobileApi : IReturn<MyResponse> {}
```

Where they'll appear as a tab to additionally filter APIs in metadata pages:

![](/img/pages/metadata/tag-groups.webp)

## Adding Links to Metadata page

### Debug Links

A good place to provide better visibility of functionality in ServiceStack is with the **Plugin Links** and **Debug Info** links section to the `/metadata` page which add links to any Plugins with Web UI's, e.g:

![](/img/pages/metadata/debug-links.webp)

The Debug Links section is only available in **DebugMode** (recap: set by default in Debug builds or explicitly with `Config.DebugMode = true`). In addition, users with the **Admin** role (or if `Config.AdminAuthSecret` is enabled) can also view the debug Plugins UI's in production.

You can add links to your own [Plugins](/plugins) in the metadata pages with:

```csharp
appHost.GetPlugin<MetadataFeature>()
    .AddPluginLink("swagger-ui/", "Swagger UI");
appHost.GetPlugin<MetadataFeature>()
    .AddDebugLink("?debug=requestinfo", "Request Info");
```

`AddPluginLink` adds links under the **Plugin Links** section and should be used if your plugin is publicly visible, otherwise use `AddDebugLink` for plugins only available during debugging or development.

## Metadata Page Filters 

Use the `IndexPageFilter` and `DetailPageFilter` on the `MetadataFeature` plugin to customize the Master and detail metadata pages before they're rendered. E.g. you can reverse the order of operation names with:

```csharp
var metadata = appHost.GetPlugin<MetadataFeature>();
metadata.IndexPageFilter = page => {
    page.OperationNames.Sort((x,y) => y.CompareTo(x));
};
```

## Updating HTML and Metadata Page Templates

The HTML templates for the metadata pages are maintained as [embedded html template resources](https://github.com/ServiceStack/ServiceStack/tree/master/src/ServiceStack/Templates). 

The VFS lets you replace built-in ServiceStack templates with your own by simply copying the metadata or [HtmlFormat Template files](https://github.com/ServiceStack/ServiceStack/tree/master/src/ServiceStack/Templates) you want to customize and placing them in your Website Directory at:

```
/Templates/HtmlFormat.html        // The auto HtmlFormat template
/Templates/IndexOperations.html   // The /metadata template
/Templates/OperationControl.html  // Individual operation template
```

Which you can customize locally that ServiceStack will pick up and use instead.

## How to disable the metadata page?

The metadata page is a feature and can be removed by setting:
```csharp
SetConfig(new HostConfig { 
    EnableFeatures = Feature.All.Remove(Feature.Metadata)
});
```

***

This can be extended to disable as many selected features are required, e.g. to also disable SOAP support you can combine with:

```csharp
SetConfig(new HostConfig { 
    EnableFeatures = Feature.All.Remove(
        Feature.Metadata | Feature.Soap11 | Feature.Soap12)
});
```

## Matching Requests with their Response DTOs

There are a number of different ways to match Requests with their Response DTO's for use in metadata services:

### IReturn Marker Interface

The recommended way to associate Request with their Response DTO's is to annotate the Request DTO with an `IReturn<T>` marker, e.g:

```csharp
public class Hello : IReturn<GreetingResponse> { ... }

public class GreetingResponse { ... }
```

This also has the primary benefit of enabling a terse and typed generic Client API as the Response type is captured in the Request DTO:

```csharp
GreetingResponse = client.Get(new Hello { ... });
```

Without the `IReturn<T>` marker the Response DTO would need to be specified on all call-sites, e.g:

```csharp
GreetingResponse = client.Get<GreetingResponse>(new Hello { ... });
```

### Response Type Naming Convention

An alternative way to specify the Response Type is to use the built-in naming convention:

```
{Request DTO Name} + Response
```

Where the Response DTO adds a `Response` suffix to the Request DTO, e.g:

```csharp
public class Hello { ... }

public class HelloResponse { ... }
```

### Service Response Type

You can also specify the Response Type by specifying it on the Services method signature, e.g:

```csharp
public class MyServices : Service
{
    public GreetingResponse Get(Hello request} { ... }
}
``` 

## Auth Info in [Metadata Pages](/metadata-page)

The Metadata pages also label protected Services. On the metadata index page it displays a yellow key next to
each Service requiring Authentication:

![](https://raw.githubusercontent.com/ServiceStack/Assets/master/img/release-notes/metadata-auth-summary.png)

Hovering over the key will show which also permissions or roles the Service needs.

This information is also shown the metadata detail pages which will list which permissions/roles are required (if any), e.g:

![](https://raw.githubusercontent.com/ServiceStack/Assets/master/img/release-notes/metadata-auth.png)

## DTOs in multiple languages

Whilst [API Explorer](/api-explorer) will continue to receive most of our efforts for providing a built-in UI/UX around ServiceStack APIs, we've also added the ability to browse an API Contract in the viewers preferred language in the existing API **/metadata** pages, e.g:

[![](/img/pages/apiexplorer/metadata-languages.png)](https://vue-vite-api.jamstacks.net/json/metadata?op=CreateBooking&lang=csharp)

The difference between them is that API Explorer is an entirely client rendered SPA that only supports modern browsers, whilst the **/metadata** pages are server rendered and should be visible in all browsers.


# ServiceStack.AI
Source: https://docs.servicestack.net/servicestack-ai

<div class="not-prose hide-title flex flex-col items-center">
   <div class="flex">
      <svg class="w-28 h-28" xmlns="http://www.w3.org/2000/svg" width="48" height="48" viewBox="0 0 48 48"><path fill="none" stroke="currentColor" stroke-linejoin="round" d="M18.38 27.94v-14.4l11.19-6.46c6.2-3.58 17.3 5.25 12.64 13.33"/><path fill="none" stroke="currentColor" stroke-linejoin="round" d="m18.38 20.94l12.47-7.2l11.19 6.46c6.2 3.58 4.1 17.61-5.23 17.61"/><path fill="none" stroke="currentColor" stroke-linejoin="round" d="m24.44 17.44l12.47 7.2v12.93c0 7.16-13.2 12.36-17.86 4.28"/><path fill="none" stroke="currentColor" stroke-linejoin="round" d="M30.5 21.2v14.14L19.31 41.8c-6.2 3.58-17.3-5.25-12.64-13.33"/><path fill="none" stroke="currentColor" stroke-linejoin="round" d="m30.5 27.94l-12.47 7.2l-11.19-6.46c-6.21-3.59-4.11-17.61 5.22-17.61"/><path fill="none" stroke="currentColor" stroke-linejoin="round" d="m24.44 31.44l-12.47-7.2V11.31c0-7.16 13.2-12.36 17.86-4.28"/></svg>
   </div>
</div>
<div class="not-prose mt-4 px-4 sm:px-6">
<div class="text-center"><h3 id="razor-ssg" class="text-4xl sm:text-5xl md:text-6xl tracking-tight font-extrabold text-gray-900">
    ServiceStack.AI
</h3></div>
<p class="mx-auto mt-5 max-w-3xl text-xl text-gray-500">
    Speech-to-Text and ChatGPT providers to enable natural language features in .NET
</p>
<div class="py-8 max-w-7xl mx-auto px-4 sm:px-6">
    <lite-youtube class="w-full mx-4 my-4" width="560" height="315" videoid="OtgrIdkvw-4" style="background-image: url('https://img.youtube.com/vi/OtgrIdkvw-4/maxresdefault.jpg')"></lite-youtube>
</div>
</div>

## ServiceStack.AI Providers

As the AI landscape is actively changing we want our Apps to be able to easily switch to different **Speech-to-Text**
or ChatGPT and TypeChat providers so we're able to easily evaluate and use the best provider for our use-case.

To support this we're maintaining **FREE** implementation-agnostic abstractions for different AI and GPT Providers to enable
AI features in .NET Apps under the new [ServiceStack.AI](https://github.com/ServiceStack/ServiceStack/tree/main/ServiceStack/src/ServiceStack.Interfaces/AI)
namespace in the dep-free **ServiceStack.Interfaces** package.

The implementations for these abstractions are maintained across NuGet packages in accordance with their dependencies:

- `ServiceStack.Aws` - AI & GPT Providers for **Amazon Web Services**
- `ServiceStack.Azure` - AI & GPT Providers for **Microsoft Azure**
- `ServiceStack.GoogleCloud` - AI & GPT Providers for **Google Cloud**
- `ServiceStack.AI` - AI & GPT Providers for **OpenAI** APIs and local Whisper and Node TypeChat installs

These abstractions and their implementations enable .NET projects to add AI-powered **natural language features** to their Apps 
whilst decoupling their **Speech-to-text** and **ChatGPT** requirements from any single implementation where they can be 
easily substituted as needed.

### .NET TypeChat Examples

An easy way to evaluate the new ServiceStack.AI providers is by exploring the [TypeChat .NET Examples Project](https://github.com/NetCoreApps/TypeChatExamples)
which contains .NET implementations for each TypeChat Example that are already configured to work with all available
providers which has a Live Demo hosted at:

:::{.my-8 .text-indigo-600 .text-center .text-2xl}
[https://typechat.netcore.io](https://typechat.netcore.io)
:::

[![](/img/pages/ai/typechat.png)](https://typechat.netcore.io)

## ISpeechToText

The `ISpeechToText` interface abstracts Speech-to-Text providers behind a simple API:

```csharp
public interface ISpeechToText
{
    // Once only task to run out-of-band before using the SpeechToText provider
    Task InitAsync(List<string> phrases, CancellationToken token = default);
    
    // Transcribe the Audio at recordingPath and return a JSON API Result
    Task<TranscriptResult> TranscribeAsync(string request, CancellationToken token);
}
```

Which has 5 different Speech-to-Text implementations to choose from:

- `GoogleCloudSpeechToText` - to use Google Cloud's [Speech-to-Text v2](https://cloud.google.com/speech-to-text/v2/) API
- `AwsSpeechToText` - to use [Amazon Transcribe](https://aws.amazon.com/pm/transcribe/) API
- `AzureSpeechToText` - to use [Azure Speech to text](https://azure.microsoft.com/en-us/products/ai-services/speech-to-text) API
- `WhisperApiSpeechToText` - to use [OpenAI's Whisper](https://platform.openai.com/docs/api-reference/audio) API
- `WhisperLocalSpeechToText` - to use local install of [OpenAI Whisper](https://github.com/openai/whisper)

## Virtual File System Providers

Likewise file storage is also easily substitutable with [Virtual File System](/virtual-file-system)
providers allowing Audio Voice Recordings to be uploaded to your preferred provider:

- `FileSystemVirtualFiles` - stores uploads in local file system (default)
- `GoogleCloudVirtualFiles` - stores uploads in [Google Cloud Storage](https://cloud.google.com/storage)
- `S3VirtualFiles` - stores uploads in [AWS S3](https://aws.amazon.com/s3/)
- `AzureBlobVirtualFiles` - stores uploads in [Azure Blob Storage](https://learn.microsoft.com/en-us/azure/storage/blobs/storage-blobs-introduction)
- `R2VirtualFiles` - stores uploads in [Cloudflare R2](https://developers.cloudflare.com/r2/)

## OpenAI Solution

Since you'll likely be needing OpenAI's ChatGPT API for converting natural language requests into a machine readable request
your App can process, the easiest solution is to also use OpenAI's Whisper API for your App's Speech-to-Text requirements,
which you can configure your App to use in a [Modular Startup](/modular-startup) config:

```csharp
[assembly: HostingStartup(typeof(ConfigureOpenAi))]

public class ConfigureOpenAi : IHostingStartup
{
    const bool UseKernel = true;
    
    public void Configure(IWebHostBuilder builder) => builder
        .ConfigureServices((context, services) => {
            services.AddSingleton<ISpeechToText, WhisperApiSpeechToText>();
            
            // Call Open AI Chat API through node TypeChat
            services.AddSingleton<ITypeChat, NodeTypeChat>();
        })
        .ConfigureAppHost(afterConfigure:appHost => {
            
            if (appHost.TryResolve<ISpeechToText>() is IRequireVirtualFiles requireVirtualFiles)
                requireVirtualFiles.VirtualFiles = appHost.VirtualFiles;
        });
}
```

Open AI providers are maintained in the **ServiceStack.AI** NuGet Package:

```xml
<PackageReference Include="ServiceStack.AI" Version="8.*" />
```

### Using Node TypeChat

If you prefer to use Microsoft's node [TypeChat library](https://github.com/microsoft/TypeChat) to utilize its 
auto schema validation and corrective auto-retry features, your [Dockerfile](https://github.com/NetCoreApps/TypeChatExamples/blob/main/Dockerfile) will 
will need to have node installed:

```bash
# install node.js and ffmpeg
RUN apt-get clean && apt-get update && apt-get upgrade -y && apt-get install -y --no-install-recommends curl gnupg ffmpeg \
    && curl -sL https://deb.nodesource.com/setup_current.x | bash - \
    && apt-get install nodejs -yq 

RUN npm install
```

#### package.json

That installs TypeChat by listing it as a dependency in your App's `package.json`:

```json
{
  "dependencies": {
    "typechat": "^0.0.10"
  }  
}
```

You'll also need a copy of 
[typechat.mjs](https://github.com/NetCoreApps/TypeChatExamples/blob/main/TypeChatExamples/typechat.mjs) script that
the .NET process invokes to utilize TypeChat, located in the Content Directory root of your Application which you can add to your project with 
[x mix](/mix-tool):

:::sh
x mix typechat.mjs
:::

### Using Microsoft Semantic Kernel

Alternatively you can avoid using TypeChat and node altogether by invoking ChatGPT through Microsoft's Semantic Kernel
.NET Library:

```csharp
var kernel = Kernel.Builder.WithOpenAIChatCompletionService(
        Environment.GetEnvironmentVariable("OPENAI_MODEL") ?? "gpt-3.5-turbo", 
        Environment.GetEnvironmentVariable("OPENAI_API_KEY")!)
    .Build();
services.AddSingleton(kernel);
services.AddSingleton<ITypeChat>(c => new KernelTypeChat(c.Resolve<IKernel>()));
```

If you're not using TypeChat you'll likely want to implement your own [Custom Validation and Auto-correcting](https://servicestack.net/posts/voice-activated-typechat-coffeeshop#custom-validation-with-c-semantic-kernel)
solution which can be more effective that TypeChat's schema validation errors approach.

## Supporting Safari Web Audio

If you're not using OpenAI's Whisper for transcribing you'll likely need to use `ffmpeg` to convert 
[Convert Uploaded Files](https://servicestack.net/posts/voice-activated-typechat-coffeeshop#converting-uploaded-files) into a format your
Speech-to-Text provider accepts.

## Google Cloud Solution

To use any of the Google Cloud providers your pc needs to be configured with [GoogleCloud Credentials](https://cloud.google.com/speech-to-text/docs/before-you-begin) on a project with **Speech-to-Text** enabled.

You can then configure your App's **appsettings.json** with your Google Cloud Project and Storage where you would like
uploads to persist to:

```json
{
  "GoogleCloudConfig": {
    "Project": "servicestackdemo",
    "Location": "global",
    "Bucket": "servicestack-typechat"
  }
}
```

Which you'll be able to configure your App to use within a [Modular Startup](/modular-startup) config:

```csharp
[assembly: HostingStartup(typeof(ConfigureGoogleCloud))]

public class ConfigureGoogleCloud : IHostingStartup
{
    public void Configure(IWebHostBuilder builder) => builder
        .ConfigureServices((context, services) => {
            GoogleCloudConfig.AssertValidCredentials();

            var gcp = context.Configuration.GetSection(nameof(GoogleCloudConfig))
                .Get<GoogleCloudConfig>();
            services.AddSingleton(gcp);
            
            services.AddSingleton<ISpeechToText>(c => {
                return new GoogleCloudSpeechToText(SpeechClient.Create(),
                    gcp.ToSpeechToTextConfig(x => {
                        // x.PhraseSetId = PhraseSetId;
                    })
                ) {
                    VirtualFiles = HostContext.VirtualFiles
                };
            });
        })
        .ConfigureAppHost(afterConfigure:appHost => {
            appHost.VirtualFiles = new GoogleCloudVirtualFiles(
                StorageClient.Create(), appHost.Resolve<GoogleCloudConfig>().Bucket!);
        });
}
```

Google Cloud providers are maintained in the **ServiceStack.GoogleCloud** NuGet Package:

```xml
<PackageReference Include="ServiceStack.GoogleCloud" Version="8.*" />
```

### Multiple custom Speech-to-Text configurations

Google Cloud Speech-to-Text APIs supports the ability to improve transcription results by creating 
[Custom PhraseSets and Recognizers](https://cloud.google.com/speech-to-text/docs/adaptation-model) where you can specify
which phrases are likely to be used so you can boost their probability they'll be recognized correctly, they'll also
let you configure which optimized model and languages to use.

If your App uses multiple Phrasesets or Recognizers they'll need return a different configured `GoogleCloudSpeechToText`
provider dependent on the feature that's requested, which you can configure with a `SpeechToTextFactory`:

```csharp
services.AddSingleton<ISpeechToTextFactory>(c => new SpeechToTextFactory
{
    Resolve = feature =>
    {
        var config = c.Resolve<AppConfig>();
        var gcp = c.Resolve<GoogleCloudConfig>();
        var siteConfig = config.GetSiteConfig(feature);

        return new GoogleCloudSpeechToText(
            SpeechClient.Create(),
            gcp.ToSpeechToTextConfig(x => {
                x.RecognizerId = siteConfig.RecognizerId;
                x.PhraseSetId = siteConfig.PhraseSetId;
            }))
        {
            VirtualFiles = HostContext.VirtualFiles
        };
    }
});
```

### Creating Custom Recognizers

The `GoogleCloudSpeechToText` provider also supports recreating a custom recognizer with a vocabulary of boosted phrases
using the `InitAsync` API:

```csharp
ISpeechToTextFactory SpeechToTextFactory { get; set; }

//...
List<KeyValuePair<string, int>> phraseWeights = ...;
var speechProvider = SpeechToTextFactory.Get(feature);
await speechProvider.InitAsync(new() {
    PhraseWeights = phraseWeights
});
```

This will re-create the PhraseSet and Recognizer using the `PhraseSetId` and `RecognizerId` identifiers that provider
was configured with in its `GoogleCloudConfig`.

### GoogleCloud Credential Deployments

Google Cloud configures their Security credentials differently to other providers where instead of storing 
Bearer Tokens or connection strings in Environment Variables, their `GOOGLE_APPLICATION_CREDENTIALS` Environment Variable 
is used to instead specify the path where the actual JSON credentials are stored on disk.

Unfortunately passing the JSON configuration file as-is is incompatible with [Docker Secrets](https://docs.docker.com/engine/swarm/secrets/)
for when you want Production App's credentials maintained outside of the Source Code repository.

A simple workaround you can do in your GitHub Actions [release.yml](https://github.com/NetCoreApps/TypeChatExamples/blob/main/.github/workflows/release.yml)
instead is to **Base64 encode** the credentials which can then be passed as a Docker secret:

```yaml
# Build and push new docker image, skip for manual redeploy other than 'latest'
- name: Build and push Docker images
  uses: docker/build-push-action@v3
  with:
    file: Dockerfile
    context: .
    push: true
    tags: ghcr.io/${{ env.image_repository_name }}:${{ env.TAG_NAME }}
    secrets: |
      googlecloud_credentials_base64=${{secrets.GOOGLE_APPLICATION_CREDENTIALS}}
```

Which your [Dockerfile](https://github.com/NetCoreApps/TypeChatExamples/blob/main/Dockerfile) can then decode with 
Unix `base64` tool before saving the `credentials.json` inside your Docker Container:

```bash
RUN --mount=type=secret,id=googlecloud_credentials_base64 \
    cat /run/secrets/googlecloud_credentials_base64 | base64 -d > /out/googlecloud-credentials.json
```

### IDE Tooling

A nice feature from using Cloud Services is the built-in tooling in IDEs like JetBrains
[Big Data Tools](https://plugins.jetbrains.com/plugin/12494-big-data-tools) where you can inspect new Recordings and ChatGPT
JSON responses from within your IDE, instead of SSH'ing into remote servers to inspect local volumes:

:::{.max-w-sm .mx-auto}
[![](/img/pages/ai/googlcloud-plugin.png)](/img/pages/ai/googlcloud-plugin.png)
:::

## Azure Solution

You can configure your App to use [Azure AI Speech](https://azure.microsoft.com/en-us/products/ai-services/speech-to-text) API 
to transcribe Web Audio Recordings that are persisted in Azure Blob Storage with the configuration below:  

```csharp
[assembly: HostingStartup(typeof(ConfigureAzure))]

public class ConfigureAzure : IHostingStartup
{
    public void Configure(IWebHostBuilder builder) => builder
        .ConfigureServices((context, services) => {

            var config = context.Configuration.GetSection(nameof(AzureConfig))
                .Get<AzureConfig>();
            services.AddSingleton(config);
            
            services.AddSingleton<ISpeechToText>(c => 
                new AzureSpeechToText(config.ToSpeechConfig()) {
                    VirtualFiles = HostContext.VirtualFiles
                });
        })
        .ConfigureAppHost(afterConfigure:appHost => {

            var config = appHost.Resolve<AzureConfig>();
            appHost.VirtualFiles = new AzureBlobVirtualFiles(
                config.ConnectionString, config.ContainerName);
        });
}
```

Azure providers are maintained in the **ServiceStack.Azure** NuGet Package:

```xml
<PackageReference Include="ServiceStack.Azure" Version="8.*" />
```

### Enable Web Audio Support

As Azure AI Speech only supports limited [Audio formats](https://learn.microsoft.com/en-us/azure/ai-services/speech-service/how-to-use-codec-compressed-audio-input-streams),
it's recommended to have [GStreamer](https://gstreamer.freedesktop.org) installed along side your App to enable 
support for more popular compressed Web Audio formats.

Refer to the [GStreamer configuration](https://learn.microsoft.com/en-us/azure/ai-services/speech-service/how-to-use-codec-compressed-audio-input-streams#gstreamer-configuration)
docs for how install GStreamer in different Operating Systems.

## AWS Solution

Organizations hosting on AWS can configure their App to use [Amazon Transcribe](https://aws.amazon.com/transcribe/) for 
transcribing their Audio recordings to text that they can store in AWS S3 with the configuration below: 

```csharp
[assembly: HostingStartup(typeof(ConfigureAws))]

namespace GptProviders;

public class ConfigureAws : IHostingStartup
{
    public void Configure(IWebHostBuilder builder) => builder
        .ConfigureServices((context, services) => {

            var config = context.Configuration.GetSection(nameof(AwsConfig)).Get<AwsConfig>();
            services.AddSingleton(config);
            
            services.AddSingleton<ISpeechToText>(c => new AwsSpeechToText(
                new AmazonTranscribeServiceClient(
                    config.AccessKey, config.SecretKey, config.ToRegionEndpoint()),
                new AwsSpeechToTextConfig {
                    Bucket = config.Bucket,
                    VocabularyName = config.VocabularyName,
                }) {
                VirtualFiles = HostContext.VirtualFiles
            });
        })
        .ConfigureAppHost(afterConfigure:appHost => {

            var config = appHost.Resolve<AwsConfig>();
            appHost.VirtualFiles = new S3VirtualFiles(
                new AmazonS3Client(config.AccessKey, config.SecretKey, config.ToRegionEndpoint()), 
                config.Bucket);
        });
}
```

Amazon Web Services providers are maintained in the **ServiceStack.Aws** NuGet Package:

```xml
<PackageReference Include="ServiceStack.Aws" Version="8.*" />
```

### AWS Speech-to-Text Factory

If your App uses custom vocabularies for different features you'll instead want register factory instead so you can 
return the correct configured `AwsSpeechToText` for the request feature:

```csharp
services.AddSingleton<ISpeechToTextFactory>(c => new SpeechToTextFactory
{
    Resolve = feature =>
    {
        var config = c.Resolve<AppConfig>();
        var aws = c.Resolve<AwsConfig>();
        var site = config.GetSiteConfig(feature);
        
        return new AwsSpeechToText(new AmazonTranscribeServiceClient(
                aws.AccessKey, aws.SecretKey, aws.ToRegionEndpoint()),
            aws.ToSpeechToTextConfig(x => x.VocabularyName = site.VocabularyName))
        {
            VirtualFiles = HostContext.VirtualFiles
        };
    }
});
```

### Creating Custom Vocabulary

The `AwsSpeechToText` provider also supports recreating a custom recognizer with a vocabulary of boosted phrases
using the `InitAsync` API:

```csharp
ISpeechToTextFactory SpeechToTextFactory { get; set; }

//...
List<KeyValuePair<string, int>> phraseWeights = ...;
var speechProvider = SpeechToTextFactory.Get(feature);
await speechProvider.InitAsync(new() {
    PhraseWeights = phraseWeights
});
```

This will re-create the Vocabulary with the `VocabularyName` the `AwsSpeechToText` was configured with:

## Cloudflare Solution

[Cloudflare AI](https://ai.cloudflare.com) newly released [AI Gateway](https://blog.cloudflare.com/announcing-ai-gateway/) offers a
managed gateway over OpenAI's APIs to cache responses, limit and retry requests, and provide analytics to help you monitor and track usage
which you can utilize by changing the `OpenAiBaseUrl` used.

You may also soon be able to use Cloudflare's OpenAI's Whisper model independently that's currently on available through their 
[Workers AI](https://blog.cloudflare.com/workers-ai/) solution.

In the meantime their [Cloudflare R2](https://developers.cloudflare.com/r2/) product is one of the best value 
managed storage solutions available, it's an attractive option to use to store Web Audio recordings for usage with
other Speech-to-Text providers, which your App can be configured to use with:

```csharp
[assembly: HostingStartup(typeof(ConfigureCloudflare))]

public class ConfigureCloudflare : IHostingStartup
{
    public void Configure(IWebHostBuilder builder) => builder
        .ConfigureServices((context, services) =>
        {
            var config = context.Configuration.GetSection(nameof(CloudflareConfig))
                .Get<CloudflareConfig>();
            services.AddSingleton(config);
            
            services.AddSingleton<ISpeechToText>(c => new WhisperApiSpeechToText {
                BaseUri = config.OpenAiBaseUrl!,
            });
        })
        .ConfigureAppHost(afterConfigure:appHost => {

            var config = appHost.Resolve<CloudflareConfig>();
            appHost.VirtualFiles = new R2VirtualFiles(
                new AmazonS3Client(config.AccessKey, config.SecretKey,
                new AmazonS3Config {
                    ServiceURL = config.ToServiceUrl(),
                }), config.Bucket);
        });
}
```

Cloudflare's `R2VirtualFiles` provider is maintained in the **ServiceStack.Aws** NuGet Package:

```xml
<PackageReference Include="ServiceStack.Aws" Version="8.*" />
```

## Local OpenAI Whisper

If your App's requirements and hardware supports it, you can save an infrastructure dependency by using a local install of
[OpenAI's Whisper](https://github.com/openai/whisper), which after installing [ffmpeg](https://ffmpeg.org/download.html)
and Python, can be installed with:

:::sh
pip install -U openai-whisper
:::

This will enable you to transcribe Audio recordings by simply specifying the recording you want a transcription of:

:::sh
whisper recording.webm
:::

#### Usage Notes

- The `--language` flag helps speed up transcriptions by avoiding needing to run auto language detection
- By default whisper will generate its transcription results in all supported `.txt`, `.json`, `.tsv`, `.srt` and `.vtt` formats
  - you can limit to just the format you want it in with `--output_format`, e.g. use `txt` if you're just interested in the transcribed text
- The default install also had [FP16](https://github.com/openai/whisper/discussions/301) and
  [Numba Deprecation](https://github.com/openai/whisper/discussions/1344) warnings

We can resolve these issues by using the modified prompt:

```bash
export PYTHONWARNINGS="ignore"
whisper --language=en --fp16 False --output_format txt recording.webm
```

Which should now generate a clean output containing the recordings transcribed text, that's also written to `recording.txt`:

```
[00:00.000 --> 00:02.000]  A latte, please.
```

This **2s** recording took **9 seconds** to transcribe on an M2 Macbook Air, a fair bit longer than the **1-2 seconds** 
it takes to upload and transcribe recordings to Google Cloud, but still within acceptable response times for real-time transcriptions.

### Switch to local OpenAI Whisper

You can configure your App to use a local **whisper** install by registering `WhisperLocalSpeechToText`:

```csharp
services.AddSingleton<ISpeechToText>(c => new WhisperLocalSpeechToText {
   WhisperPath = ProcessUtils.FindExePath("whisper"),
   TimeoutMs = 120 * 1000,
});
```

### Example Usage

TypeChat Examples `CreateRecording` API implementation in 
[GptServices.cs](https://github.com/NetCoreApps/TypeChatExamples/blob/main/TypeChatExamples.ServiceInterface/GptServices.cs)
is used to transcribe the uploaded Web Audio recording for **all its examples** which it first creates an entry in the 
`Recording` RDBMS Table before invoking the Speech-to-Text API that is then updated after its successful or error response:

```csharp
public class MyServices(IAutoQueryDb autoQuery, ISpeechToTextFactory speechToTextFactory)
{
    public async Task<Recording> Any(CreateRecording request)
    {
        var feature = request.Feature.ToLower();
        var recording = (Recording)await autoQuery.CreateAsync(request, Request);
        var speechToText = speechToTextFactory.Get(request.Feature);

        var transcribeStart = DateTime.UtcNow;
        await Db.UpdateOnlyAsync(() => new Recording { TranscribeStart=transcribeStart },
            where: x => x.Id == recording.Id);

        ResponseStatus? responseStatus = null;
        try
        {
            var response = await speechToText.TranscribeAsync(request.Path);
            var transcribeEnd = DateTime.UtcNow;
            await Db.UpdateOnlyAsync(() => new Recording
            {
                Feature = feature,
                Provider = speechToText.GetType().Name,
                Transcript = response.Transcript,
                TranscriptConfidence = response.Confidence,
                TranscriptResponse = response.ApiResponse,
                TranscribeEnd = transcribeEnd,
                TranscribeDurationMs = (transcribeEnd-transcribeStart).TotalMilliseconds,
                Error = response.ResponseStatus.ToJson(),
            }, where: x => x.Id == recording.Id);
            responseStatus = response.ResponseStatus;
        }
        catch (Exception e)
        {
            await Db.UpdateOnlyAsync(() => new Recording { Error = e.ToString() },
                where: x => x.Id == recording.Id);
            responseStatus = e.ToResponseStatus();
        }

        recording = await Db.SingleByIdAsync<Recording>(recording.Id);

        if (responseStatus != null)
            throw new HttpError(responseStatus, HttpStatusCode.BadRequest);

        return recording;
    }
}
```

### Client Usage Example

Now that our Server supports it we can start using this API to upload Audio Recordings by running the pre-configured
npm script to update our App's [Typed JavaScript DTOs](/javascript-add-servicestack-reference):

:::sh
npm run dtos
:::

To simplify capturing Web Audio recordings we've the encapsulated reusable functionality within the [AudioRecorder.mjs](https://github.com/NetCoreApps/TypeChatExamples/blob/main/TypeChatExamples/wwwroot/mjs/AudioRecorder.mjs)
class whose `start()` method starts recording Audio from the Users microphone:

```js
import { AudioRecorder } from "/mjs/AudioRecorder.mjs"

let audioRecorder = new AudioRecorder()
await audioRecorder.start()
```

Where it captures audio chunks until `stop()` is called that are then stitched together into a `Blob` and converted into
a Blob DataURL that's returned within a populated [Audio](https://developer.mozilla.org/en-US/docs/Web/API/HTMLAudioElement)
Media element:

```js
const audio = await audioRecorder.stop()
```

That supports the [HTMLMediaElement](https://developer.mozilla.org/en-US/docs/Web/API/HTMLMediaElement#instance_methods) API
allowing pause and playback of recordings:

```js
audio.play()
audio.pause()
```

The `AudioRecorder` also maintains the `Blob` of its latest recording in its `audioBlob` field and the **MimeType** that it was
captured with in `audioExt` field, which we can use to upload it to the `CreateRecording` API, which if
successful will return a transcription of the Audio recording:

```js
import { JsonServiceClient } from "@servicestack/client"

const client = new JsonServiceClient()

const formData = new FormData()
formData.append('path', audioRecorder.audioBlob, `file.${audioRecorder.audioExt}`)
const api = await client.apiForm(new CreateRecording({feature:'coffeeshop'}),formData)
if (api.succeeded) {
   transcript.value = api.response.transcript
}
```

This is used by all TypeChat Examples that's encapsulated in their UI Razor Pages:

- [CoffeeShop.cshtml](https://github.com/NetCoreApps/TypeChatExamples/blob/main/TypeChatExamples/Pages/CoffeeShop.cshtml)
- [Sentiment.cshtml](https://github.com/NetCoreApps/TypeChatExamples/blob/main/TypeChatExamples/Pages/Sentiment.cshtml)
- [Calendar.cshtml](https://github.com/NetCoreApps/TypeChatExamples/blob/main/TypeChatExamples/Pages/Calendar.cshtml)
- [Restaurant.cshtml](https://github.com/NetCoreApps/TypeChatExamples/blob/main/TypeChatExamples/Pages/Restaurant.cshtml)
- [Math.cshtml](https://github.com/NetCoreApps/TypeChatExamples/blob/main/TypeChatExamples/Pages/Math.cshtml)
- [Music.cshtml](https://github.com/NetCoreApps/TypeChatExamples/blob/main/TypeChatExamples/Pages/Music.cshtml)

## Prompt Providers

Whilst not required for usage with other providers, the `IPromptProvider` interface can improve code reuse by
implementing a standard interface for generating their TypeScript `Schema` and Chat GPT `Prompt` texts.

```csharp
// The App Provider to use to generate TypeChat Schema and Prompts
public interface IPromptProvider
{
    // Create a TypeChat TypeScript Schema from a TypeChatRequest
    Task<string> CreateSchemaAsync(CancellationToken token);

    // Create a TypeChat TypeScript Prompt from a User request
    Task<string> CreatePromptAsync(string userMessage, CancellationToken token);
}
```

Implementations contain the App-specific functionality for creating its **TypeScript Schema** and **GPT Prompt**,
which each App in TypeChatExamples maintains in its `*PromptProvider.cs` classes in the
[TypeChatExamples.ServiceInterface](https://github.com/NetCoreApps/TypeChatExamples/tree/main/TypeChatExamples.ServiceInterface) project.

## TypeChat API

After receiving a text transcript of a Customer's natural language request you'll need to enlist the services of Chat GPT 
to convert it into an Order request that your App can understand.

### ITypeChat

Just as we've abstracted the substitutable Speech-to-text Services App binds to, we've also created an abstraction for 
the TypeChat provider App uses, which allows easily swap out and evaluate different solutions or Mocking in tests:

```csharp
public interface ITypeChat
{
    Task<TypeChatResponse> TranslateMessageAsync(TypeChatRequest request, 
        CancellationToken token = default);
}
```

Whilst a simple API on the surface, different execution and customizations options are available in the
`TypeChatRequest` which at a minimum requires the **Schema** & **Prompt** to use and the **UserMessage** to convert:

```csharp
// Request to process a TypeChat Request
public class TypeChatRequest
{
    public TypeChatRequest(string schema, string prompt, string userMessage)
    {
        Schema = schema;
        Prompt = prompt;
        UserMessage = userMessage;
    }

    /// TypeScript Schema
    public string Schema { get; set; }
    
    /// TypeChat Prompt
    public string Prompt { get; set; }
    
    /// Chat Request
    public string UserMessage { get; }
    
    /// Path to node exe (default node in $PATH)
    public string? NodePath { get; set; }

    /// Timeout to wait for node script to complete (default 120s)
    public int NodeProcessTimeoutMs { get; set; } = 120 * 1000;

    /// Path to node TypeChat script (default typechat.mjs)
    public string? ScriptPath { get; set; }
    
    /// TypeChat Behavior we want to use (Json | Program)
    public TypeChatTranslator TypeChatTranslator { get; set; }

    /// Path to write TypeScript Schema to (default Temp File)
    public string? SchemaPath { get; set; }
    
    /// Which directory to execute the ScriptPath (default CurrentDirectory) 
    public string? WorkingDirectory { get; set; }
}
```

There are currently 2 different Chat GPT `ITypeChat` implementations registered in TypeChat Examples
[Configure.Gpt.cs](https://github.com/NetCoreApps/TypeChatExamples/blob/main/TypeChatExamples/Configure.Gpt.cs).

### Semantic Kernel TypeChat Provider

The natural approach for interfacing with OpenAI's ChatGPT API in .NET is to use [Microsoft's Semantic Kernel](https://github.com/microsoft/semantic-kernel)
to call it directly, which can be registered with: 

```csharp
var kernel = Kernel.Builder.WithOpenAIChatCompletionService(
        Environment.GetEnvironmentVariable("OPENAI_MODEL") ?? "gpt-3.5-turbo", 
        Environment.GetEnvironmentVariable("OPENAI_API_KEY")!)
    .Build();
services.AddSingleton(kernel);
services.AddSingleton<ITypeChat>(c => new KernelTypeChat(c.Resolve<IKernel>()));
```

## Node TypeChat Provider

As the [TypeChat library](https://github.com/microsoft/TypeChat) uses **typescript** it requires calling out to the 
**node** executable in order to be able to use it from .NET Apps, which can be configured withL

```csharp
services.AddSingleton<ITypeChat>(c => new NodeTypeChat());
```

It works by executing an **external process** that invokes a [typechat.mjs](https://github.com/NetCoreApps/TypeChatExamples/blob/main/TypeChatExamples/typechat.mjs) 
script wrapper around TypeChat's functionality to invoke it and return any error responses in a structured `ResponseStatus` 
format that our .NET App can understand, which can also be invoked manually from the command line with:

:::sh
node typechat.mjs json gpt\coffeeshop\schema.ts "i wanna latte macchiato with vanilla"
:::

TypeChat uses the OpenAI Environment Variables below to access ChatGPT APIs:

- `OPENAI_MODEL` - The OpenAI model name (e.g. **gpt-3.5-turbo** or **gpt-4**)
- `OPENAI_API_KEY` - Your OpenAI API key


## Using Chat GPT to process Natural Language Orders

We now have everything we need to start leveraging Chat GPT to convert our Customers **Natural Language** requests
into Machine readable instructions that our App can understand, guided by the App's TypeChat TypeScript Schema.

TypeChat Examples does this for all its apps in [GptServices.cs](https://github.com/NetCoreApps/TypeChatExamples/blob/main/TypeChatExamples.ServiceInterface/GptServices.cs)
that just like `CreateRecording` is a custom AutoQuery CRUD Service that uses AutoQuery to create the
initial `Chat` record, that's later updated with the GPT Chat API Response:

```csharp
public class GptServices(
    IAutoQueryDb autoQuery,
    IPromptProviderFactory promptFactory,
    ITypeChat typeChat,
    IPromptProvider promptProvider) : Service
{
    //...
    public async Task<object> Any(CreateChat request)
    {
        var feature = request.Feature.ToLower();
        var promptProvider = promptFactory.Get(feature);
        var chat = (Chat)await autoQuery.CreateAsync(request, Request);

        var chatStart = DateTime.UtcNow;
        await Db.UpdateOnlyAsync(() => new Chat { ChatStart = chatStart },
            where: x => x.Id == chat.Id);

        ResponseStatus? responseStatus = null;
        try
        {
            var schema = await promptProvider.CreateSchemaAsync();
            var prompt = await promptProvider.CreatePromptAsync(request.UserMessage);
            var typeChatRequest = CreateTypeChatRequest(feature, schema, prompt, request.UserMessage);
            
            var response = await typeChat.TranslateMessageAsync(typeChatRequest);
            var chatEnd = DateTime.UtcNow;
            await Db.UpdateOnlyAsync(() => new Chat
            {
                Request = request.UserMessage,
                Feature = feature,
                Provider = TypeChat.GetType().Name,
                Schema = schema,
                Prompt = prompt,
                ChatResponse = response.Result,
                ChatEnd = chatEnd,
                ChatDurationMs = (int)(chatEnd - chatStart).TotalMilliseconds,
                Error = response.ResponseStatus.ToJson(),
            }, where: x => x.Id == chat.Id);
            responseStatus = response.ResponseStatus;
        }
        catch (Exception e)
        {
            await Db.UpdateOnlyAsync(() => new Chat { Error = e.ToString() },
                where: x => x.Id == chat.Id);
            responseStatus = e.ToResponseStatus();
        }

        chat = await Db.SingleByIdAsync<Chat>(chat.Id);

        if (responseStatus != null)
            throw new HttpError(responseStatus, HttpStatusCode.BadRequest);
        
        return chat;
    }
}
```

### Client Usage

Just like the [CreateRecording client usage](https://servicestack.net/posts/servicestack-ai#client-usage-example) example we can invoke the
APIs using the typed JavaScript DTOs to invoke the `CreateChat` API to returns Chat GPTs JSON Response directly to the client:

```js
apiChat.value = await client.api(new CreateChat({
    feature: 'coffeeshop',
    userMessage: request.toLowerCase()
}))

if (apiChat.value.response) {
    processChatItems(JSON.parse(apiChat.value.response.chatResponse).items)
} else if (apiChat.value.error) {
    apiProcessed.value = apiChat.value
}
```

Which for the CoffeeShop example is in the structure of the TypeScript Schema's array of `Cart` LineItem's which are matched 
against the products and available customizations from the App's database before being added to the user's cart in the
[processChatItems(items)](https://github.com/NetCoreApps/TypeChatExamples/blob/main/TypeChatExamples/Pages/CoffeeShop.cshtml#L530) function.


# SVG Support
Source: https://docs.servicestack.net/svg

ServiceStack lets you register use built-in and register custom SVG icons from the `Svg` static API class.

A common performance drain in Web Apps is serving images whose large binary blobs can have a significant impact on your App's 
Request throughput, and why they're often hosted behind CDN's which can complicate the deployment process and introduce subtle caching issues.

A popular image format that's seen its popularity rise on the Web is SVG - a text vector image format that scales beautifully to support
different resolutions. SVG's are typically small in size and have great support in browsers where they can be optimally cached in `.css` 
style sheets to reduce the number of required image requests.

Unless you're using an npm based build system there hasn't been great support for managing SVG images in .NET beyond treating them
as individual images, that is until now with the new `SvgFeature` plugin (pre-registered by default) and the `Svg` class - providing programmatic 
access to registering SVG image collections and accessing them in a variety of different formats and colors.

### In Memory Bundled CSS files

`SvgFeature` works by creating an in memory bundled `.css` file for each "image set" that's registered at the path `/css/{image-set}.css`, 
e.g. it's pre-configured with the **svg-auth** and **svg-icons** svg groups:

  - **/css/svg-auth.css** - Vendor Icons for each of the popular 3rd Party OAuth Providers
  - **/css/svg-icons.css** - Generic User Avatars (used as the default profile image)

SVG files are simply stored as strings in regular collections maintained in `Svg.CssFiles` and `Svg.Images` dictionaries which can be modified/extended as normal.

### Viewing SVG Icons

One thing that sets SVG apart from normal images is the multitude of ways they can be referenced. SVG's are commonly bundled in 
`.css` files and referenced by classes, but they can also be embedded in a native `<img>` tag and `<svg>` block element where they
can be displayed in different colors.

To make it as easy as possible to reference SVG images in different contexts we've created the dynamic `/metadata/svg` page 
(also available under the **SVG Images** link in your [/metadata page Debug Links](/metadata-page#debug-links)) where you can view
all your App's registered SVG images complete with different usage examples, code fragments and links to access SVG Image `.css` 
collections or individual SVG images:

![](/img/pages/svg/metadata-svg.png)

The **entire page is clickable** where you can first click on the SVG image you want to use then **click on any text fragment** to copy it, 
ready for pasting it in your web page.

### Loading SVG from FileSystem

The most user-friendly way to load custom SVG images is to load them from a custom directory, e.g:

```
/svg
    /svg-icons
        vue.svg
        spirals.html
    /my-icons
        myicon.svg
```

Then in your `AppHost` you can register all SVG images using `Svg.Load()`:

```csharp
public override void Configure(Container container)
{
    Svg.Load(RootDirectory.GetDirectory("/svg"));
}
```

::: info
`VirtualFiles` is configured to your projects **ContentRoot**, use `VirtualFileSources` to use your **WebRoot**, 
`RootDirectory` uses the FileSystem VFS in `VirtualFileSources` whereas `ContentRootDirectory` looks in `VirtualFiles`
:::

This will load all the SVG images in the `/svg` directory with the **sub directory** used for the **cssfile** (aka image-set) 
you want to add them to and the **file name** (without extension) used as the SVG identifier.

It will also evaluate any `.html` files in the directory with [#Script](https://sharpscript.net) and add the rendered SVG output,
e.g. we can load the generated SVG from the [Spirals Sharp App](https://github.com/mythz/spirals):

#### /svg/svg-icons/spirals.html

::: v-pre
```hbs
<svg height="640" width="240">
{{#each range(180) }}
    {{ 120 + 100 * cos((5)  * it * 0.02827) |> to => x }}
    {{ 320 + 300 * sin((1)  * it * 0.02827) |> to => y }}
    <circle cx="{{x}}" cy="{{y}}" r="{{it*0.1}}" fill="#556080" stroke="black" stroke-width="1"></circle>
{{/each}}
</svg>
```
:::

and the SVG rendered output will be registered as a normal static SVG Image.

### Registering SVGs from _init.html

An alternative way of registering SVG's is to register them in #Script Pages `_init.html` page that gets executed once on Startup
which will let you register multiple SVG images within 1 file using the `#svg` Script Block using the format `#svg <name> <image-set>`, e.g:

::: v-pre
```html
{{#svg vue app}}
<svg width="100" height="100" xmlns="http://www.w3.org/2000/svg">
    <g>
        <path fill="#556080" stroke="null" d="m79.43253,10.80794l0.01231,-0.02461l-18.15085,0l-11.38274,19.68085l0,0.0082l-11.37043,-19.68906l-18.15085,0l0,0.02051l-19.70136,0l49.22265,85.26183l49.22265,-85.25773"/>
    </g>
</svg>
{{/svg}}
```
:::

Which also supports using `#Script` to create and register dynamically rendered SVG images:

::: v-pre
```html
{{#svg spirals svg-icons}}
<svg height="640" width="240">
{{#each range(180) }}
    {{ 120 + 100 * cos((5)  * it * 0.02827) |> to => x }}
    {{ 320 + 300 * sin((1)  * it * 0.02827) |> to => y }}
    <circle cx="{{x}}" cy="{{y}}" r="{{it*0.1}}" fill="#556080" stroke="black" stroke-width="1"></circle>
{{/each}}
</svg>
{{/svg}}
```
:::

### Register Custom SVG Images via API

You can also register your own SVG images programmatically with:

```csharp
Svg.AddImage("<svg width='100' height='100' viewBox='0 0 100 100'>...</svg>", "myicon", "my-icons");
```

Where it will register the SVG under the **myicon** name and include it in the `/css/my-icons.css` css file.

The same icon can also be included in multiple stylesheets by adding its name to the `Svg.CssFiles` collection, e.g:

```csharp
Svg.CssFiles["svg-icons"].Add("myicon");
```

#### SVG APIs

Once added you can access your SVG images from the available `Svg` APIs:

```csharp
var svg = Svg.GetImage("myicon");
var dataUri = Svg.GetDataUri("myicon");
```

All SVG images are also available from the `Svg.Images` collection if you need to access them programmatically:

```csharp
foreach (var entry in Svg.Images) {
    var name = entry.Key;
    var svg = entry.Value;
    $"{name}: {svg}".Print();
}
```

#### Recommended SVG conventions

All built-in SVG's are `100x100` in size, it's not necessary but for consistency it's good for your SVG icons also retain the same size, 
but as they're vector images they can be easily resized when referencing them in your App.

If your icons use the **fill** colors registered in:

```csharp
Svg.FillColors = new[] { "#ffffff", "#556080" };
```

You will be able replace the fill colors with:

```csharp
var svg = Svg.GetImage("myicon", "#e33");
var dataUri = Svg.GetDataUri("myicon", "#e33");
```

## Using SVG images in CSS

On Startup ServiceStack generates `.css` files for all SVG icons in `Svg.CssFiles` so you can import all icons with a single 
stylesheet reference with all icons in each CSS file available from `/css/{name}.css`, e.g:

```html
<link rel="stylesheet" href="/css/svg-icons.css">
```

Each CSS file includes 2 CSS classes for each SVG image that are both configured with the SVG as a background image:

```css
.svg-myicon, .fa-myicon { background-image: url(...) }
```

Use the `svg-myicon` class when you want to set an HTML Element to use your SVG as its background:

```html
<div class="icon svg-myicon"></div>
```

A good way to set the size of all related icons is to use a shared class, e.g:

```css
.icon {
  width: 50px;
  height: 50px;
  background-size: 50px 50px;
  background-repeat: no-repeat;
  background-position: 2px 2px;
}
```

The `fa-myicon` class follows [Font Awesome](https://fontawesome.com) convention which you can use to render SVG icons inside buttons, e.g:

```html
<button class="btn btn-block btn-social btn-light">
  <i class="fab fa-myicon"></i> Label
</button>
```

You can either use [Bootstrap Button colors](https://getbootstrap.com/docs/4.3/components/buttons/#examples) to select the button color
you want or use a custom `btn-myicon` class to choose different backgrounds for each SVG, e.g:

```css
.btn-myicon {
  color: #212529;
  background-color: #dae0e5;
  border-color: #d3d9df;
}
```

The buttons requires the [Social Buttons for Bootstrap](https://lipis.github.io/bootstrap-social/) which is also embedded in ServiceStack.dll
that can be referenced from `/css/buttons.css`, e.g:

```html
<link rel="stylesheet" href="/css/buttons.css">
<link rel="stylesheet" href="/css/svg-icons.css">
```

### Inline CSS

An alternative to using external stylesheet references above, is to embed them as inline styles in your page which can benefit in reduced
network requests as well as provide better isolation than including all CSS your App's use in each page.

You can use `cssIncludes` to embed the contents of multiple css files in `#Script` pages with:

::: v-pre
```hbs
{{ 'buttons,svg-icons' |> cssIncludes }}
```
:::

Or in Razor with:

```html
@Html.CssIncludes("buttons","svg-icons")
```

## Using SVG images in `#Script`

In [#Script Pages](https://sharpscript.net/docs/script-pages) you can embed SVG xml with the `svgImage` and `svgDataUri` scripts:

::: v-pre
```hbs
{{ 'myicon' |> svgImage }}
{{ 'myicon'.svgImage('#e33') }}
```
:::

Inside an HTML IMG element using its data URI:

::: v-pre
```html
<img src="{{ 'myicon'.svgDataUri() }}">
<img src="{{ 'myicon'.svgDataUri('#e33') }}">
```
:::

Or as a background image in a custom CSS class:

::: v-pre
```css
.myicon {
  width: 150px;
  height: 150px;
  background-size: 142px;
  background-position: 4px;
  background-repeat: no-repeat;
  {{ 'myicon'.svgBackgroundImageCss() }} 
}
```
:::

Where you can use the class name to apply the above CSS to an element:

```html
<div class="myicon"></div>
```

### Using SVG images in Razor

Likewise there are HTML Helpers with the same name available in Razor Pages, where you can embed SVG images directly with:

```csharp
@Html.SvgImage("myicon")
@Html.SvgImage("myicon", "#e33")
```

Inside an HTML IMG element using its data URI:

```html
<img src='@Html.SvgDataUri("myicon")'>
<img src='@Html.SvgDataUri("myicon", "#e33")'>
```

Or inside a CSS class:

```css
.myicon {
  width: 150px;
  height: 150px;
  background-size: 150px;
  background-repeat: no-repeat;
  @Html.SvgBackgroundImageCss("myicon")
}
```

### Server Controls

Use these `#Script` methods to reference and modify individual SVG images in [#Script Pages](https://sharpscript.net/docs/script-pages):

```csharp
svgImage(string name) => Svg.GetImage(name)
svgImage(string name, string fillColor) => Svg.GetImage(name, fillColor)
svgDataUri(string name) => Svg.GetDataUri(name)
svgDataUri(string name, string fillColor) => Svg.GetDataUri(name, fillColor)
svgFill(string svg, string color) => Svg.Fill(svg, color)

svgBackgroundImageCss(string name) => Svg.GetBackgroundImageCss(name)
svgBackgroundImageCss(string name, string fillColor) => Svg.GetBackgroundImageCss(name, fillColor)
svgInBackgroundImageCss(string svg) => Svg.InBackgroundImageCss(svg)

svgBaseUrl(ScriptScopeContext scope) => 
    req(scope).ResolveAbsoluteUrl(HostContext.AssertPlugin<SvgFeature>().RoutePath);

Dictionary<string, string> svgImages() => Svg.Images;
Dictionary<string, string> svgDataUris() => Svg.DataUris;
Dictionary<string, List<string>> svgCssFiles() => Svg.CssFiles;
```

The same API's are also available in ServiceStack.Razor pages using the `@Html` helpers below:

```csharp
Html.SvgImage(name)
Html.SvgImage(name, fillColor)
Html.SvgDataUri(name)
Html.SvgDataUri(name, fillColor)
Html.SvgFill(svg, color);

Html.SvgBackgroundImageCss(name)
Html.SvgBackgroundImageCss(name, fillColor)
Html.SvgInBackgroundImageCss(svg)

Html.SvgBaseUrl()
```

### Mix in SVG Images

A nice consequence of the SVG support is being able to easily create a customized bundles of hand-picked SVG image assets
as opposed to being forced to choose from a limited library in a fixed bundle. 

As creating svg bundles just involves dropping SVG images inside your `/svg/{group}/` folder, we're also able take advantage of `mix`
to import SVG image-sets into your App with a single command. You can view the current list of all SVG image-sets on `mix` with:

:::sh
x mix [svg]
:::

Currently all [Material Design Icons](https://material.io/resources/icons/?style=baseline) are available separately by their logical group names:

```
Results matching tag [svg]:

   1. svg-action         Material Design Action Icons         to: svg/  by @ServiceStack  [svg]
   2. svg-alert          Material Design Alert Icons          to: svg/  by @ServiceStack  [svg]
   3. svg-av             Material Design Audio Visual Icons   to: svg/  by @ServiceStack  [svg]
   4. svg-communication  Material Design Communication Icons  to: svg/  by @ServiceStack  [svg]
   5. svg-content        Material Design Content Icons        to: svg/  by @ServiceStack  [svg]
   6. svg-device         Material Design Device Icons         to: svg/  by @ServiceStack  [svg]
   7. svg-editor         Material Design Editor Icons         to: svg/  by @ServiceStack  [svg]
   8. svg-file           Material Design File Icons           to: svg/  by @ServiceStack  [svg]
   9. svg-hardware       Material Design Hardware Icons       to: svg/  by @ServiceStack  [svg]
  10. svg-image          Material Design Image Icons          to: svg/  by @ServiceStack  [svg]
  11. svg-maps           Material Design Maps Icons           to: svg/  by @ServiceStack  [svg]
  12. svg-navigation     Material Design Navigation Icons     to: svg/  by @ServiceStack  [svg]
  13. svg-places         Material Design Places Icons         to: svg/  by @ServiceStack  [svg]
  14. svg-social         Material Design Social Icons         to: svg/  by @ServiceStack  [svg]
  15. svg-toggle         Material Design Toggle Icons         to: svg/  by @ServiceStack  [svg]
```

Once imported, you have the flexibility to further customize them individually to create your App's custom designer bundle.
You also have access to `#Script` to generate parts of your SVG image dynamically if needed, as seen above in `spirals.html`.


# REST, SOAP &amp; default endpoints
Source: https://docs.servicestack.net/endpoints

When you create a service, there are by default three endpoints:

- User-defined REST endpoint
- SOAP endpoint: `/[soap11|soap12]`
- Default endpoint: `/[xml|json|html|jsv|csv]/[reply|oneway]/[servicename]`

The preferred way to call the webservice is mostly using the REST endpoint. As you have seen, user-defined REST endpoints can be configured with the `Route` attribute for each Request DTO.

But you can also call your service by using the default endpoint, without configuring a REST url with the default endpoint.
Of course there's always the option to use the SOAP endpoint.

## Sample requests:

The possible requests for the following Request DTO are:

```csharp
[Route("/hello")]
public class Hello
{
    public string Name { get; set; }
}
```

## Option 1

### SOAP endpoint

```
POST example.org/soap11
```

```xml
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
    <soap:Body>

<Hello xmlns:i="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://schemas.servicestack.net/types">
  <Name>String</Name>
</Hello>

    </soap:Body>
</soap:Envelope>
```

### Rest endpoint:

```
POST example.org/hello
```

```js
{"Name":"World"}
```

### Default endpoint:

```
POST example.org/json/reply/Hello
```

```json
{"Name":"World"}
```


## Option 2

But you don't need to pass the `Name` of the Request DTO in the request body. There's also the possibility to set the value of `Name` with URL parameters (works only with REST and default endpoint of course).

### REST endpoint:

```
POST example.org/hello?Name=World
```

### Default endpoint:

```
POST example.org/json/reply/Hello?Name=World
```

You can also combine the two approaches. 


## Option 3

Last but not least there exists another way to set the value of `Name`! But this works only with the REST endpoint:
If you add the following mapping to the Request DTO above:

```csharp
[Route("/hello/{Name}")]
```

...you will be able to set the name in the URL itself, without any URL parameters:

### Rest endpoint:

```
GET example.org/hello/World
```

As you can see `{Name}` (in the mapping) is the placeholder for the value of the property `Name`.

::: info Tip
The last two approaches are mostly used for GET and DELETE requests, because often clients don't support to attach a request body for these HTTP methods
:::

::: info Tip
As you may have noticed, ServiceStack is also capable to support different formats (JSON, XML, etc). There exists another separate tutorial about formats
:::


# SOAP support
Source: https://docs.servicestack.net/soap-support

If you want to support SOAP, you have to ensure you adhere to some additional constraints where each method needs to be defined with the `Any()` endpoint and each DTO needs to be decorated with `[DataContract]` and `[DataMember]` attributes so their metadata is generated in your Services XSD and WSDL metadata.

### Configure

Register the `SoapFormat` Plugin to enable SOAP Support in ServiceStack (Requires ASP.NET Framework):

```csharp
Plugins.Add(new SoapFormat());
```

## SOAP + REST

SOAP only supports a single `POST` request but REST services also make use of `GET`, `PUT`, `DELETE`, etc requests, which aren't used in SOAP. So if you want to support SOAP and REST, you need to create one service for each operation which is also the [recommended API structure](/physical-project-structure) for creating [message-based Services](/why-servicestack#goals-of-service-design). The difference to be able to support SOAP is that Service implementations need to be defined with `Any()`, e.g:

```csharp
//Request DTO - Add DataMember attribute for all properties.
[DataContract]
[Route("/customers", "GET")]
[Route("/customers/{Id}", "GET")]
public class GetCustomers : IReturn<GetCustomersResponse> {...}

public class GetCustomersResponse
{
    [DataMember]
    public List<Customer> Results { get; set; }

    [DataMember]
    public ResponseStatus ResponseStatus { get; set; }
}

[DataContract]
[Route("/customers", "POST")]
public class AddCustomer : IReturn<GetCustomersResponse> {...}

[DataContract]
[Route("/customers/{Id}", "PUT")]
public class UpdateCustomer : IReturn<GetCustomersResponse> {...}

[DataContract]
[Route("/customers/{Id}", "DELETE")]
public class DeleteCustomer : IReturn<GetCustomersResponse> {...}

//Service
public class CustomersService : Service 
{
   public object Any(GetCustomers request){...}
   public object Any(AddCustomer request){...}
   public object Any(UpdateCustomer request){...}
   public object Any(DeleteCustomer  request){...}
}
```

Using `Any` will allow the Service to be executed on each HTTP Verb which is required for SOAP since all SOAP Requests are made with a HTTP POST Request wrapped inside a SOAP message and sent to the fixed `/soap11` or `/soap12` endpoints. You also want to make sure that **all DTO models** have `[DataContract]` attribute (and `[DataMember]` attribute for **all properties**) otherwise the XSD-schema embedded within the WSDL will be partially incomplete.  

## Consuming SOAP Services

Ideally the nicest experience for consuming SOAP Services would be to use a generic [C# ServiceClients](/csharp-client#httpwebrequest-service-clients), e.g:

```csharp
var client = new Soap12ServiceClient(BaseUrl);

var response = client.Send(new GetCustomers());
```

Although if you could use a generic ServiceClient, you'd typically be better off using the other cleaner and faster endpoints like JSON instead:

```csharp
var client = new JsonApiClient(BaseUrl);

var response = client.Get(new GetCustomers());
```

In either case you can share your DTOs in your `*.ServiceModel.dll` to use the same DTOs without code-gen or use 
[C# Add ServiceStack Reference](/csharp-add-servicestack-reference) to easily generate DTOs on the client.

### Visual Studios Add Service Reference

Since VS.NET's `Add Service Reference` is optimized for consuming **.asmx** or **WCF** RPC method calls it doesn't properly support multiple return values (e.g. when you also want a ResponseStatus property) where it will generate an ugly proxy API complete with **out** parameters.

If you want to ensure a *pretty proxy* is generated you should only have 1 first-level property which contains all the data you want to return.

### Using XSD.exe

One way around it is to share your services DTO's and use any of the typed [Generic Service Clients](/csharp-client#httpwebrequest-service-clients) that are in-built into ServiceStack. Alternatively you can use the `XSD.exe` command-line utility to generate your types on the client and use those in the typed Service Clients.


### REST-ful registration of multiple services

The Custom `[Route]` definitions are used to control how you want services exposed in REST APIs which all logically appear to exposed them under a single REST-ful resource, i.e:

| Request | Description |
|:-|:-|
| **GET /customers**    | Get All Customers  |
| **GET /customers/1**  | Get Customer #1    |
| **POST /customers**   | Add New Customer   |
| **PUT /customers/1**  | Update Customer #1 |
| **DELETE /customers** | Delete Customer #1 |


This Web Service now supports both **REST and SOAP** with REST API's using the above custom routes and SOAP requests posting WSDL Requests to their fixed `/soap11` or `/soap12` endpoints.

## SOAP Limitations

SOAP expects that each request always returns the same response DTO. So you need to follow the **Response DTO naming convention**, otherwise ServiceStack won't be able to generate the WSDLs and the SOAP endpoint won't be able to work. 

### DTO Naming Conventions

**Naming convention:** `{Request DTO Name} + Response`

#### Example:

**Request DTO** `DeleteCustomer` => **Response DTO** `DeleteCustomerResponse`

If you would leave the services as they are, the REST endpoint wouldn't exist. So you need to hook them all up on the same URL like that:

### Single WSDL Namespace

If you happen to generate requests from the WSDLs with a tool like SoapUI you may end up with an incorrectly generated request like this:

```xml
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" 
               xmlns:type="http://schemas.servicestack.net/types">
  <soap:Header/>
  <soap:Body>
    <type:Hello/>
  </soap:Body>
</soap:Envelope>
```

You can resolve this issue by adding the following line to your AssemblyInfo file
```csharp
[assembly: ContractNamespace("http://schemas.servicestack.net/types", 
           ClrNamespace = "<YOUR NAMESPACE>")]
```
e.g:

```csharp
[assembly: ContractNamespace("http://schemas.servicestack.net/types",
           ClrNamespace = "MyApp.ServiceModel")]
[assembly: ContractNamespace("http://schemas.servicestack.net/types",
           ClrNamespace = "MyApp.ServiceModel.Types")]
```

Rebuild and regenerate the request from the updated wsdl. You should get a correct request this time.

```xml
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" 
               xmlns:type="http://schemas.servicestack.net/types">
   <soap:Header/>
   <soap:Body>
      <type:Hello>
         <!--Optional:-->
         <type:Name>?</type:Name>
      </type:Hello>
   </soap:Body>
</soap:Envelope>
```

## Changing the default namespace

A requirement with SOAP endpoints is for all DTO types to share the same single namespace which should match the `Config.WsdlServiceNamespace` if you want to change it from the default namespace: `http://schemas.servicestack.net/types`. E.g. You can change the default WSDL Namespace in your AppConfig with:

```csharp
SetConfig(new HostConfig {
    WsdlServiceNamespace = "http://my.new.namespace.com/types",
});
```

This can easily be done by using the `[assembly:ContractNamespace]` attribute usually defined in the DTO project's AssemblyInfo.cs file, here is how this is done in the [ServiceStack.Examples project](https://github.com/ServiceStack/ServiceStack.Examples/blob/master/src/ServiceStack.Examples/ServiceStack.Examples.ServiceModel/Properties/AssemblyInfo.cs#L39):

```csharp
[assembly: ContractNamespace("http://my.new.namespace.com/types",
           ClrNamespace = "ServiceStack.Examples.ServiceModel.Operations")]
[assembly: ContractNamespace("http://my.new.namespace.com/types",
           ClrNamespace = "ServiceStack.Examples.ServiceModel.Types")]
```

### SOAP Exceptions

Exceptions in SOAP responses are returned with an `200 OK` HTTP Status so they are deserialized as normal responses in code-generated SOAP clients. The original HTTP Status code is available in the `X-Status` HTTP Header or SOAP Response Header named `X-Status`. This is transparently converted into a typed `WebServiceException` when using ServiceStack's built-in Soap 1.1/1.2 generic Service Clients as seen in [WebServicesTests](https://github.com/ServiceStack/ServiceStack/blob/master/tests/ServiceStack.WebHost.IntegrationTests/Tests/WebServicesTests.cs).

To check if the response was an error in non ServiceStack SOAP clients, check the `response.ResponseStatus.ErrorCode` property for a **non-null** value.

#### Convert SOAP Exceptions to SOAP Faults

If preferred, you can also convert SOAP Exceptions into a SOAP Fault by adding a ServiceExceptionHandler, e.g:

```csharp
ServiceExceptionHandlers.Add((req, request, ex) =>
{
    if (req.GetItem(Keywords.SoapMessage) is System.ServiceModel.Channels.Message requestMsg)
    {
        req.Response.UseBufferedStream = true;
        var msgVersion = requestMsg.Version;
        using (var response = XmlWriter.Create(req.Response.OutputStream))
        {
            var message = System.ServiceModel.Channels.Message.CreateMessage(
                msgVersion, new FaultCode("Receiver"), ex.ToString(), null);
            message.WriteMessage(response);
        }
        req.Response.End();
    }
    return null;
});
```

## Customize WSDL's and XSD's

There's finer-grain control available over which **Operations** and **Types** are exported in SOAP WSDL's and XSD's by overriding the new `ExportSoapOperationTypes()` and `ExportSoapType()` methods in your AppHost.

You can exclude specific Request DTO's from being emitted in WSDL's and XSD's with:

```csharp
[Exclude(Feature.Soap)]
public class HiddenFromSoap { .. } 
```

### Raw Access to WCF SOAP Message

`IRequiresSoapMessage` works similar to [IRequiresRequestStream](/serialization-deserialization) interface to tell ServiceStack to skip de-serialization of the request and instead pass the raw WCF Message to the Service instead for manual processing, e.g:

```csharp
public class RawWcfMessage : IRequiresSoapMessage {
	public Message Message { get; set; }
}

public object Post(RawWcfMessage request) { 
	request.Message... //Raw WCF SOAP Message
}
```

### Customize SOAP Response

You can override and customize how the SOAP Message Responses are written, here's a basic example:

```csharp
public override WriteSoapMessage(Message message, Stream outputStream)
{
    using (var writer = XmlWriter.Create(outputStream, Config.XmlWriterSettings))
    {
        message.WriteMessage(writer);
    }
}
```

::: info
The default [WriteSoapMessage](https://github.com/ServiceStack/ServiceStack/blob/fb08f5cb408ece66f203f677a4ec14ee9aad78ae/src/ServiceStack/ServiceStackHost.Runtime.cs#L484) implementation also raises a ServiceException and writes any returned response to a buffered Response Stream (if configured)
:::


# Error Handling
Source: https://docs.servicestack.net/error-handling

## Throwing C# Exceptions

In most cases you won't need to be concerned with ServiceStack's error handling since it provides native support for the normal use-case of throwing C# Exceptions, e.g.:

```csharp 
public object Post(User request) 
{
    if (string.IsNullOrEmpty(request.Name))
        throw new ArgumentNullException("Name");
}
```

### Default Mapping of C# Exceptions to HTTP Errors

By Default C# Exceptions inheriting from:

  - `ArgumentException` or `SerializationException` or `FormatException` is returned as a **400 BadRequest**
  - `NotImplementedException` or `NotSupportedException ` is returned as a **405 MethodNotAllowed** 
  - `FileNotFoundException` is return as **404 NotFound**
  - `AuthenticationException` is returned as **401 Unauthorized**
  - `UnauthorizedAccessException` is returned as **403 Forbidden**
  - `OptimisticConcurrencyException` is returned as **409 Conflict**
  - All Other normal C# Exceptions are returned as **500 InternalServerError**

Other custom mappings can be added to the [Config.MapExceptionToStatusCode dictionary](/error-handling#custom-mapping-of-c-exceptions-to-http-error-status),
by [implementing IHasStatusCode interface](/error-handling#implementing-ihasstatuscode) or by [returning a HttpError](/error-handling#returning-a-httperror).

### WebServiceException 

All Exceptions get injected into the `ResponseStatus` property of your Response DTO that is serialized into your ServiceClient's preferred Content-Type making error handling transparent regardless of your preferred format - i.e., the same C# Error handling code can be used for all ServiceClients.

```csharp 
try 
{
    var client = new JsonApiClient(BaseUri);
    var response = client.Send<UserResponse>(new User());
} 
catch (WebServiceException webEx) 
{
    /*
      webEx.StatusCode        = 400
      webEx.StatusDescription = ArgumentNullException
      webEx.ErrorCode         = ArgumentNullException
      webEx.ErrorMessage      = Value cannot be null. Parameter name: Name
      webEx.StackTrace        = (your Server Exception StackTrace - in DebugMode)
      webEx.ResponseDto       = (your populated Response DTO)
      webEx.ResponseStatus    = (your populated Response Status DTO)
      webEx.GetFieldErrors()  = (individual errors for each field if any)
    */
}
```

Where the `StatusCode` and `StatusDescription` are the HTTP StatusCode and Description which shows the top-level HTTP-layer details that all HTTP Clients see. The StatusDescription is typically short and used to indicate the type of Error returned which by default is the Type of the Exception thrown. HTTP Clients normally inspect the `StatusCode` to determine how to handle the error on the client.

All [Service Clients](/clients-overview) also have access to Application-level Error details which are returned in the Error Response DTO Body where the `ErrorCode` holds the Exception Type and is what clients would inspect to determine and handle the Type of Exception it is whilst the `ErrorMessage` holds the Server Exception Message which provides a human-friendly, longer and descriptive description of the Error that can be displayed to the end user. In [DebugMode](/debugging#debugmode) the `StackTrace` is populated with the Server StackTrace to help front-end developers from identifying the cause and location of the Error.

If the Error refers to a particular field such as a Field Validation Exception, `GetFieldErrors()` holds the error information for each field that has an Error.

These defaults can be changed to provide further customized error responses by the various options below:

### Enabling StackTraces

By default displaying StackTraces in Response DTOs are only enabled in Debug builds, although this behavior is overridable with:

```csharp
SetConfig(new HostConfig { DebugMode = true });
```

### Error Response Types

The Error Response that gets returned when an Exception is thrown varies on whether a conventionally-named `{RequestDto}Response` DTO exists or not. 

#### If it exists:
The `{RequestDto}Response` is returned, regardless of the service method's response type. If the `{RequestDto}Response` DTO has a **ResponseStatus** property, it is populated otherwise no **ResponseStatus** will be returned.  (If you have decorated the `{ResponseDto}Response` class and properties with `[DataContract]/[DataMember]` attributes, then **ResponseStatus** also needs to be decorated, to get populated).

#### Otherwise, if it doesn't:
A generic `ErrorResponse` gets returned with a populated **ResponseStatus** property.

The [Service Clients](/clients-overview) transparently handles the different Error Response types, and for schema-less formats like JSON/JSV/etc there's no actual visible difference between returning a **ResponseStatus** in a custom or generic `ErrorResponse` - as they both output the same response on the wire.

## Custom Exceptions

Ultimately all ServiceStack WebServiceExceptions are just Response DTO's with a populated [ResponseStatus](https://github.com/ServiceStack/ServiceStack/blob/master/src/ServiceStack.Interfaces/ResponseStatus.cs) that are returned with a HTTP Error Status. There are a number of different ways to customize how Exceptions are returned including:

### Custom mapping of C# Exceptions to HTTP Error Status

You can change what HTTP Error Status is returned for different Exception Types by configuring them with:

```csharp 
SetConfig(new HostConfig { 
    MapExceptionToStatusCode = {
        { typeof(CustomInvalidRoleException), 403 },
        { typeof(CustomerNotFoundException), 404 },
    }
});
```

### Returning a HttpError

If you want even finer grained control of your HTTP errors you can either **throw** or **return** an **HttpError** letting you customize the **Http Headers** and **Status Code** and HTTP Response **body** to get exactly what you want on the wire:

```csharp 
public object Get(User request) 
{
    throw HttpError.NotFound($"User {request.Name} does not exist");
}
```

The above returns a **404** NotFound StatusCode on the wire and is a short-hand for: 

```csharp 
new HttpError(HttpStatusCode.NotFound, 
    $"User {request.Name} does not exist");
```

### HttpError with a Custom Response DTO

The `HttpError` can also be used to return a more structured Error Response with:

```csharp
var responseDto = new ErrorResponse { 
    ResponseStatus = new ResponseStatus {
        ErrorCode = typeof(ArgumentException).Name,
        Message = "Invalid Request",
        Errors = new List<ResponseError> {
            new ResponseError {
                ErrorCode = "NotEmpty",
                FieldName = "Company",
                Message = "'Company' should not be empty."
            }
        }
    }
};

throw new HttpError(HttpStatusCode.BadRequest, "ArgumentException") {
    Response = responseDto,
}; 
```

### Implementing IResponseStatusConvertible

You can also override the serialization of Custom Exceptions by implementing the `IResponseStatusConvertible`
interface to return your own populated ResponseStatus instead. This is how `ValidationException` allows customizing the Response DTO is by [having ValidationException implement](https://github.com/ServiceStack/ServiceStack/blob/master/src/ServiceStack/FluentValidation/ValidationException.cs) the [IResponseStatusConvertible](https://github.com/ServiceStack/ServiceStack/blob/master/src/ServiceStack.Interfaces/Model/IResponseStatusConvertible.cs) interface. 

E.g. Here's a custom Exception example that returns a populated Field Error:  

```csharp
public class CustomFieldException : Exception, IResponseStatusConvertible
{
  ...
    public string FieldErrorCode { get; set; }
    public string FieldName { get; set; }
    public string FieldMessage { get; set; }

    public ResponseStatus ToResponseStatus() => new ResponseStatus {
        ErrorCode = GetType().Name,
        Message = Message,
        Errors = new List<ResponseError> {
            new ResponseError {
                ErrorCode = FieldErrorCode,
                FieldName = FieldName,
                Message = FieldMessage
            }
        }
    }
}
```

### Implementing IHasStatusCode

In addition to customizing the HTTP Response Body of C# Exceptions with 
[IResponseStatusConvertible](/error-handling#implementing-iresponsestatusconvertible), 
you can also customize the HTTP Status Code by implementing `IHasStatusCode`:

```csharp
public class Custom401Exception : Exception, IHasStatusCode
{
    public int StatusCode => 401;
}
```

Likewise `IHasStatusDescription` can be used to customize the `StatusDescription` and `IHasErrorCode` for customizing the `ErrorCode` returned, instead of its Exception Type.

### Overriding OnExceptionTypeFilter in your AppHost

You can also catch and modify the returned `ResponseStatus` returned by overriding `OnExceptionTypeFilter` in your AppHost, e.g. [ServiceStack uses this](https://github.com/ServiceStack/ServiceStack/blob/master/src/ServiceStack/ServiceStackHost.Runtime.cs#L310) to customize the returned ResponseStatus to automatically add a custom field error for `ArgumentExceptions` with the specified `ParamName`, e.g:

```csharp
public virtual void OnExceptionTypeFilter(
    Exception ex, ResponseStatus responseStatus)
{
    var argEx = ex as ArgumentException;
    var isValidationSummaryEx = argEx is ValidationException;
    if (argEx != null && !isValidationSummaryEx && argEx.ParamName != null)
    {
        var paramMsgIndex = argEx.Message.LastIndexOf("Parameter name:");
        var errorMsg = paramMsgIndex > 0
            ? argEx.Message.Substring(0, paramMsgIndex)
            : argEx.Message;

        responseStatus.Errors.Add(new ResponseError
        {
            ErrorCode = ex.GetType().Name,
            FieldName = argEx.ParamName,
            Message = errorMsg,
        });
    }
}
```

### Intercept Service Exceptions

As an alternative way of customizing Service Exceptions is to override `OnExceptionAsync()`
callback in your `Service` class (or base class) to intercept and modify Request DTOs, Responses or Error Responses, e.g:

```csharp
class MyServices : Service
{
    //Return custom error with additional metadata
    public override Task<object> OnExceptionAsync(object requestDto, Exception ex)
    {
        var error = DtoUtils.CreateErrorResponse(requestDto, ex);
        if (error is IHttpError httpError)
        {                
            var errorStatus = httpError.Response.GetResponseStatus();
            errorStatus.Meta = new Dictionary<string,string> {
                ["InnerType"] = ex.InnerException?.GetType().Name
            };
        }
        return Task.FromResult(error);
    }
}
```

::: info
Return `null` to continue with default error handling
:::

### Custom HTTP Errors

In Any Request or Response Filter you can short-circuit the [Request Pipeline](/order-of-operations) by emitting a Custom HTTP Response and Ending the request, e.g:

```csharp
this.PreRequestFilters.Add((req,res) => 
{
    if (req.PathInfo.StartsWith("/admin") && 
        !req.GetSession().HasRole("Admin", req.TryResolve<IAuthRepository>())) 
    {
        res.StatusCode = (int)HttpStatusCode.Forbidden;
        res.StatusDescription = "Requires Admin Role";
        res.EndRequest();
    }
});
```

Or if you need access to the Request DTO you can use a [Global Request Filter](/request-and-response-filters) instead, e.g:

```csharp
GlobalRequestFilters.Add((req,res,dto) => {
    if (req.Verb == HttpMethods.Post && dto is Authenticate authDto 
        && authDto.provider == CredentialsAuthProvider.Name && !authDto.UseTokenCookie) {
        res.StatusCode = (int)HttpStatusCode.Forbidden;
        res.StatusDescription = "Must use stateless JWT Cookies";
        res.EndRequest();       
    }
});
```

::: info
To end the Request in a  Custom HttpHandler use `res.EndHttpHandlerRequest()`
:::

### Fallback Error Pages

Use `IAppHost.GlobalHtmlErrorHttpHandler` for specifying a **fallback HttpHandler** for all error status codes, e.g.:

```csharp 
public override void Configure(Container container)
{
    this.GlobalHtmlErrorHttpHandler = new RazorHandler("/oops"),
}
```

For more fine-grained control, use `IAppHost.CustomErrorHttpHandlers` for specifying custom HttpHandlers to use with specific error status codes, e.g:

```csharp 
public override void Configure(Container container)
{
    this.CustomErrorHttpHandlers[HttpStatusCode.NotFound] = 
        new SharpPageHandler("/notfound");
    this.CustomErrorHttpHandlers[HttpStatusCode.Unauthorized] = 
        new SharpPageHandler("/login");
    this.CustomErrorHttpHandlers[HttpStatusCode.Forbidden] = 
        new SharpPageHandler("/forbidden");
}
```

Will render the contents of the `/notfound.html` for 404 NotFound Requests and `/login.html` page for 401 Unauthorized requests if you're using
static HTML, Single Page Apps or [#Script Pages](https://sharpscript.net/docs/script-pages).

If you're using Razor instead you can `RazorHandler` to render `/notfound.cshtml` or `/login.cshtml` ServiceStack Razor pages:

```csharp 
public override void Configure(Container container)
{
    this.CustomErrorHttpHandlers[HttpStatusCode.NotFound] = 
        new RazorHandler("/notfound");
    this.CustomErrorHttpHandlers[HttpStatusCode.Unauthorized] = 
        new RazorHandler("/login");
    this.CustomErrorHttpHandlers[HttpStatusCode.Forbidden] = 
        new RazorHandler("/forbidden");
}
```

### Register handlers for handling Service Exceptions

ServiceStack and its [API Design](/api-design) provides a flexible way to intercept exceptions. If you need a single entry point for all service exceptions, you can add a handler to `AppHost.ServiceExceptionHandler` in `Configure`. To handle exceptions occurring outside of services you can set the global `AppHost.UncaughtExceptionHandlers` handler, e.g.:

```csharp
public override void Configure(Container container)
{
    //Handle Exceptions occurring in Services:

    this.ServiceExceptionHandlers.Add((httpReq, request, exception) => {
        //log your exceptions here
        ...
        return null; //continue with default Error Handling

        //or return your own custom response
        //return DtoUtils.CreateErrorResponse(request, exception);
    });

    //Handle Unhandled Exceptions occurring outside of Services
    //E.g. Exceptions during Request binding or in filters:
    this.UncaughtExceptionHandlers.Add((req, res, operationName, ex) => {
         res.Write($"Error: {ex.GetType().Name}: {ex.Message}");
         res.EndRequest(skipHeaders: true);
    });
}
```

#### Async Exception Handlers

If your handlers need to make any async calls they can use the Async versions instead:

```csharp
this.ServiceExceptionHandlersAsync.Add(async (httpReq, request, ex) =>
{
    await LogServiceExceptionAsync(httpReq, request, ex);

    if (ex is UnhandledException)
        throw ex;

    if (request is IQueryDb)
        return DtoUtils.CreateErrorResponse(request, new ArgumentException("AutoQuery request failed"));

    return null;
});

this.UncaughtExceptionHandlersAsync.Add(async (req, res, operationName, ex) =>
{
    await res.WriteAsync($"UncaughtException '{ex.GetType().Name}' at '{req.PathInfo}'");
    res.EndRequest(skipHeaders: true);
});
```

### GatewayExceptionHandlers

Gateway Exception Handlers provide the same Exception Handling callbacks as ServiceExceptions which you can use
to intercept Exceptions from Gateway requests:

```csharp
IAppHost.GatewayExceptionHandlers
IAppHost.GatewayExceptionHandlersAsync 
```

Gateway Exceptions can also be intercepted in your `AppHost` by overriding:

```csharp
public override async Task OnGatewayException(IRequest httpReq, object request, Exception ex) => ...
```

### Error handling using a custom ServiceRunner

If you want to provide different error handlers for different actions and services you can just tell ServiceStack to run your services in your own custom [IServiceRunner](https://github.com/ServiceStack/ServiceStack/blob/master/src/ServiceStack.Interfaces/Web/IServiceRunner.cs) and implement the **HandleException** event hook in your AppHost:

```csharp
public override IServiceRunner<TRequest> CreateServiceRunner<TRequest>(
    ActionContext actionContext)
{           
    return new MyServiceRunner<TRequest>(this, actionContext); 
}
```

Where **MyServiceRunner** is just a custom class implementing the custom hooks you're interested in, e.g.:

```csharp
public class MyServiceRunner<T> : ServiceRunner<T> 
{
    public MyServiceRunner(IAppHost appHost, ActionContext actionContext) 
        : base(appHost, actionContext) {}

    public override Task<object> HandleExceptionAsync(IRequest req, TRequest requestDto, 
        Exception ex, object service) {
      // Called whenever an exception is thrown in your Services Action
    }
}
```

# Community Resources

  - [ServiceStack Exceptions and Errors](http://www.philliphaydon.com/2012/03/09/service-stack-exceptions-and-errors/) by [@philliphaydon](https://twitter.com/philliphaydon)


# Validation and Error Handling
Source: https://docs.servicestack.net/validation

As validation and error handling is an essential part of developing services, ServiceStack provides a rich array of error handling options that work intuitively out-of-the-box. 

Optimized for developer happiness ServiceStack allows you to idiomatically throw C# exceptions directly in your services and trivially consume them on the client with minimal effort, intuitively and conventionally - allowing the opportunity to inject generic error handling routines to handle errors for all your web services. 

As a bonus the most appropriate HTTP Status code is returned based upon the C# Exception type.

### Typed, Structured Exceptions end-to-end
The error handling support works end-to-end where all errors get auto-serialized into your Response DTO and re-hydrated into a C# Exception on ServiceStack's generic Service Clients. This allows you to idiomatically treat errors like normal C# Exceptions - providing easy access to rich, structured error messages in your clients. 

### JavaScript support included
To make it trivial to consume errors in JavaScript, you can use the lightweight and embedded dep-free [@servicestack/client form binding](/servicestack-client-umd#binding-html-forms) library or the [ss-utils.js](/ss-utils-js#bootstrap-forms) jQuery library to trivially bind your response errors to your **HTML form fields** with a **single line of code**.

## How it works

All Error handling and validation options described below are treated in the same way - serialized into the `ResponseStatus` property of your Response DTO making it possible for your clients applications to generically treat all Web Service Errors in the same way.

```csharp
public class Hello : IReturn<HelloResponse> {}

//Follows naming convention and is in the same namespace as 'Hello'
public class HelloResponse 
{
    public ResponseStatus ResponseStatus { get; set; } //Exception gets serialized here
}
```


If now an exception occurs in the service implementation, the exception is serialized.

**Example JSON output:**

```json
{
    "ResponseStatus": {
         "ErrorCode": "NotSupportedException",
         "Message": "..."
    }
}
```

It's up to the client how to handle this service error.

## Throw a C# Exception

The easiest way to generate an Error in ServiceStack is to simply throw a C# Exception:

```csharp 
public object Post(User request) 
{
	if (string.IsNullOrEmpty(request.Name))
		throw new ArgumentNullException("Name");
}
```

By Default C# Exceptions:

  - Inheriting from ArgumentException are returned as a HTTP StatusCode of **400 BadRequest**
  - NotImplementedException is returned as a **405 MethodNotAllowed** 
  - Other normal C# Exceptions are returned as **500 InternalServerError**

All Exceptions gets injected into the ResponseStatus property of your Response DTO that is serialized into your ServiceClient's preferred Content-Type making error handling transparent regardless of your preferred format - i.e. the same C# Error handling code can be used for all ServiceClients.

```csharp 
try 
{
    var client = new JsonApiClient(BaseUri);
    var response = client.Send<UserResponse>(new User());
} 
catch (WebServiceException webEx) 
{
    /*
      webEx.StatusCode  = 400
      webEx.ErrorCode   = ArgumentNullException
      webEx.Message     = Value cannot be null. Parameter name: Name
      webEx.StackTrace  = (your Server Exception StackTrace - if DebugMode is enabled)
      webEx.ResponseDto = (your populated Response DTO)
      webEx.ResponseStatus   = (your populated Response Status DTO)
      webEx.GetFieldErrors() = (individual errors for each field if any)
    */
}
```

### Enabling StackTraces

By default display StackTraces in your Response DTOs are disabled, but they're a good to have for development, which you can enable with:

```cs
SetConfig(new HostConfig { DebugMode = true });
```

## Customized Error Messages

If you want even finer grained control of your HTTP errors you can either **throw** or **return** a **HttpError** letting you customize the **Http Headers** and **Status Code** and HTTP Response **body** to get exactly what you want on the wire:

```csharp 
public object Get(User request) {
       throw HttpError.NotFound($"User {request.Name} does not exist");
}
```

the above is a short-hand for `new HttpError(HttpStatusCode.NotFound, $"User {request.Name} does not exist")` which returns a **404** NotFound StatusCode on the wire.

## Validation Feature

For more complex validation and to be able to return multiple validation errors ServiceStack includes the excellent [Fluent Validation](https://github.com/JeremySkinner/FluentValidation) library by [@JeremySkinner](http://twitter.com/JeremySkinner) - a very clean and DSL-like way to validate request DTOs. Even contextual validation for each HTTP method (GET, POST, ...) is supported.

ServiceStack's Fluent Validation feature is encapsulated in the `ValidationFeature` plugin which is registered by default,
it can be removed with:

```csharp
Plugins.RemoveAll(x => x is ValidationFeature);
```

### FluentValidation for request dtos

The example below uses this request dto for validation:

```csharp
[Route("/users")]
public class User
{
    public string Name { get; set; }
    public string Company { get; set; }
    public int Age { get; set; }
    public int Count { get; set; }
    public string Address { get; set; }
}
```

The validation rules for this request dto are made with [FluentValidation](https://github.com/JeremySkinner/FluentValidation/wiki). ServiceStack makes heavy use of [rule sets](https://github.com/JeremySkinner/FluentValidation/wiki/b.-Creating-a-Validator#rulesets) to provide different validation rules for each HTTP method (GET, POST, PUT...).

::: info Tip
First read the [documentation about FluentValidation](https://github.com/JeremySkinner/FluentValidation/wiki) before you continue reading
:::

```csharp
public interface IAddressValidator
{
    bool ValidAddress(string address);
}

public class AddressValidator : IAddressValidator
{
    public bool ValidAddress(string address)
    {
	return address != null
	    && address.Length >= 20
	    && address.Length <= 250;
    }
}

public class UserValidator : AbstractValidator<User>
{
    public IAddressValidator AddressValidator { get; set; }
    
    public UserValidator()
    {
        //Validation rules for all requests
        RuleFor(r => r.Name).NotEmpty();
        RuleFor(r => r.Age).GreaterThan(0);
        RuleFor(x => x.Address).Must(x => AddressValidator.ValidAddress(x));

        //Validation rules for GET request
        RuleSet(ApplyTo.Get, () => {
            RuleFor(r => r.Count).GreaterThan(10);
        });

        //Validation rules for POST and PUT request
        RuleSet(ApplyTo.Post | ApplyTo.Put, () => {
            RuleFor(r => r.Company).NotEmpty();
        });
    }
}
```

::: info
ServiceStack adds another extension method named `RuleSet` which can handle `ApplyTo` enum flags. This method doesn't exist in the core FluentValidation framework
:::

::: warning
If a validator for a request dto is created, all rules which aren't in any rule set are executed **+ the rules in the matching rule set**. 
Normally FluentValidation only executes the matching rule set and **ignores** all other rules (whether they're in a rule set or not) and the rules which don't belong 
to any rule set are normally only executed, if no rule set-name was given to the validate method of the validator. 
:::

Like services registered in the IoC container, validators are also auto-wired, so if there's a public property which can be resolved by the IoC container, the IoC container will inject it. In this case, the IoC container will resolve the property `AddressValidator`, if an object of the type `IAddressValidator` was registered.

::: info Tip
You can access the current `IRequest` in your Custom Validator from `base.Request`
:::

### Async Validators

Async validators can be registered using the `MustAsync` validator where you could simulate the following built-in **Not Empty** validation:

```csharp
public class MyRequestValidator : AbstractValidator<MyRequest>
{
    public MyRequestValidator()
    {
        RuleFor(x => x.Name).NotEmpty();
    }
}
```

And replace it with an Async version that uses the [Service Gateway](/service-gateway) to 
call a custom Async `GetStringLength` Service that returns the same `ErrorCode` and Error Message as the 
**Not Empty** validator:

```csharp
public class MyRequestValidator : AbstractValidator<MyRequest>
{
    public MyRequestValidator()
    {
        RuleFor(x => x.Name).MustAsync(async (s, token) => 
            (await Gateway.SendAsync(new GetStringLength { Value = s })).Result > 0)
        .WithMessage("'Name' should not be empty.")
        .WithErrorCode("NotEmpty");
    }
}
```

### Register Validators

The `ValidationFeature` plugin automatically scans and auto-wires all validators in the `AppHost.ServiceAssemblies` that's injected in the `AppHost` constructor.

This default behavior can be **disabled** with:

```csharp
appHost.ConfigurePlugin<ValidationFeature>(feature => {
    feature.ScanAppHostAssemblies = false;
});
```

Otherwise if the validators are in other assembles they can be registered using `RegisterValidators()`, e.g:

```csharp
//This method scans the assembly for validators
container.RegisterValidators(typeof(UserValidator).Assembly);
```

Optionally each validator can be registered individually:

```csharp
//Add the IAdressValidator which will be injected into the UserValidator
container.Register<IAddressValidator>(new AddressValidator());
```

Now the service etc can be created and the validation rules are checked every time a request comes in.

If you try now for example to send this request:

```
POST localhost:50386/validated
{
    "Name": "Max"
} 
```

You'll get this JSON response:

```json
{
    "ErrorCode": "GreaterThan",
    "Message": "'Age' must be greater than '0'.",
    "Errors": [
        {
            "ErrorCode": "GreaterThan",
            "FieldName": "Age",
            "Message": "'Age' must be greater than '0'."
        },
        {
            "ErrorCode": "NotEmpty",
            "FieldName": "Company",
            "Message": "'Company' should not be empty."
        }
    ]
}
```

As you can see, the `ErrorCode` and the `FieldName` provide an easy way to handle the validation error at the client side. 
If you want, you can also configure a custom `ErrorCode` for a validation rule:

```csharp
RuleFor(x => x.Name).NotEmpty().WithErrorCode("ShouldNotBeEmpty"); 
```

If the rule fails, the JSON response will look like that:

```json
{
    "ErrorCode": "ShouldNotBeEmpty",
    "FieldName": "Name",
    "Message": "'Name' should not be empty."
}
```

### Custom Validation

ServiceStack's internal implementation of [FluentValidation](https://github.com/JeremySkinner/FluentValidation) uses the latest 7.2 version which lets you take advantage of new features like implementing [Custom Validators](https://github.com/JeremySkinner/FluentValidation/wiki/e.-Custom-Validators#using-a-custom-validator), e.g:

```csharp
public class CustomValidationValidator : AbstractValidator<CustomValidation>
{
    public CustomValidationValidator()
    {
        RuleFor(request => request.Code).NotEmpty();
        RuleFor(request => request)
            .Custom((request, context) => {
                if (request.Code?.StartsWith("X-") != true)
                {
                    var propName = context.ParentContext.PropertyChain.BuildPropertyName("Code");
                    context.AddFailure(new ValidationFailure(propName, error:"Incorrect prefix") {
                        ErrorCode = "NotFound"
                    });
                }
            });
    }
}
```

## Use FluentValidation Everywhere

Of course FluentValidation can be used for any other classes (not only request DTOs), too:

```csharp
public class TestClass
{
    public string Text { get; set; }
    public int Length { get; set; }
}
```

Now the validator: 

```csharp
public class TestClassValidator : AbstractValidator<TestClass>
{
    public TestClassValidator()
    {
        RuleFor(x => x.Text).NotEmpty();
        RuleFor(x => x.Length).GreaterThan(0);
    }
}
```

::: info
If FluentValidation isn't used for request DTOs, it behaves the same as documented in the [Fluent Validation documentation](https://github.com/JeremySkinner/FluentValidation/wiki)
:::

Inside some service code you can validate an instance of this class:

```csharp
public class SomeService : Service
{
    //You should have registered your validator in the IoC container to inject the validator into this property
    public IValidator<TestClass> Validator { get; set; }

    public object Get(Validated request)
    {
        TestClass instance = new TestClass();

        ValidationResult result = this.Validator.Validate(instance);

        if (!result.IsValid)
        {
            //The result will be serialized into a ValidationErrorException and throw this one
            //The errors will be serialized in a clean, human-readable way (as the above JSON example)
            throw result.ToException();
        }

    }
}
```

## Populating the Response DTO Manually  

All the error handling methods illustrated above are just sugar coating for serializing exceptions into your Response DTOs [ResponseStatus](https://github.com/ServiceStack/ServiceStack/blob/master/src/ServiceStack.Interfaces/ServiceInterface.ServiceModel/ResponseStatus.cs) property. You don't have use any of this as you can simply populate the ResponseStatus property yourself, coupled with the HttpResult class you have complete control of your HTTP Response - this gives you the necessary freedom so you are able to define your own Error handling API and helpers if you have an existing validation library that you would like to use instead.

# Examples

## [World Validation](/world-validation)

See the annotated [World Validation Docs](/world-validation) for a detailed example of Fluent Validation that walks through and showcases the implementation 
of how the most popular **Server HTML rendered** approaches and **Client UI rendered** technologies which are able all to use the same 
single suite of Fluent Validators and ServiceStack Services.


# World Validation
Source: https://docs.servicestack.net/world-validation

The [World Validation App](https://github.com/NetCoreApps/Validation) covers a typical Apps examples you would find in most Apps, 
including **Login** and **Registration Forms** to **Sign In** and **Register** new Users who are then able to access the 
**same protected Services** to maintain their own private contact lists. 
It's a compact example that tries to cover a lot of use-cases typical in a real-world App, including maintaining a separate Data and DTO Model 
and using C# idioms like Enum's for defining a finite list of options which are re-used to populate its HTML UI.

The UI for the same App is re-implemented in **10 popular Web Development approaches**, each integrated with ServiceStack's validation.

As of this writing there **4 different server HTML** generated strategies that use HTML Form Posts to call back-end Services:

[![](https://raw.githubusercontent.com/ServiceStack/Assets/master/img/apps/Validation/home.png)](https://github.com/NetCoreApps/Validation)

<h4 class="mt-8 text-center">
  View Source on GitHub <a href="https://github.com/NetCoreApps/Validation">NetCoreApps/Validation</a> - 
  Live Demo <a href="http://validation.web-app.io">validation.web-app.io</a>
</h4>

### Server Rendered HTML UIs

 - [/server](https://github.com/NetCoreApps/Validation/tree/master/world/wwwroot/server) - Sharp Pages using Server Controls
 - [/server-ts](https://github.com/NetCoreApps/Validation/tree/master/world/wwwroot/server-ts) - Server HTML enhanced with TypeScript
 - [/server-jquery](https://github.com/NetCoreApps/Validation/tree/master/world/wwwroot/server-jquery) - Server HTML enhanced with jQuery
 - [/server-razor](https://github.com/NetCoreApps/Validation/tree/master/world/wwwroot/server-razor) - ServiceStack.Razor using Razor Helpers

### Client HTML UIs

The Client Examples use Ajax Forms and the [TypeScript JsonServiceClient](/typescript-add-servicestack-reference#typescript-serviceclient) 
to send TypeScript [dtos.ts](https://github.com/NetCoreApps/Validation/blob/master/world/wwwroot/dtos.ts) generated with [TypeScript Add ServiceStack Reference](/typescript-add-servicestack-reference):

 - [/vuetify](https://github.com/NetCoreApps/Validation/tree/master/world/wwwroot/vuetify) - Vue App using Vuetify's Material Design Controls using ServiceClient Requests
 - [/client-ts](https://github.com/NetCoreApps/Validation/tree/master/world/wwwroot/client-ts) - TypeScript UI using Ajax Forms and ServiceClient Requests
 - [/client-jquery](https://github.com/NetCoreApps/Validation/tree/master/world/wwwroot/client-jquery) - JavaScript UI using jQuery Ajax Requests
 - [/client-razor](https://github.com/NetCoreApps/Validation/tree/master/world/wwwroot/client-razor) - Client jQuery Ajax Requests rendered by Razor pages
 - [/client-vue](https://github.com/NetCoreApps/Validation/tree/master/world/wwwroot/client-vue) - Vue UI using TypeScript and ServiceClient Requests
 - [/client-react](https://github.com/NetCoreApps/Validation/tree/master/world/wwwroot/client-react) - React UI using TypeScript and ServiceClient Requests

The source code for all different strategies are encapsulated within their folders above except for the Razor examples which need to
maintain their shared resources in the [/Views](https://github.com/NetCoreApps/Validation/tree/master/world/Views) folder 
(representative of friction and restrictions when working with Razor).

### Server Implementation

This is the shared backend Server implementation that all UIs are using:

All Auth Configuration is encapsulated within a "no-touch" `IConfigureAppHost` plugin that's run once on Startup:

::include gists/apphost-auth-validation.md::

All Services and Validators used in this App. Extension methods are used to DRY reusable code and a Custom
[Auto Mapping](/auto-mapping) handles conversion between the `Contact` Data Model and Contact`` DTO:

::include gists/custom-validator-contact.md::

The dynamic App data used within ServiceStack Sharp Pages and Razor pages are maintained within Custom `ContactScripts` and `RazorHelpers`:

::include gists/scripts-razor-helpers.md::

Typed Request/Response Service Contracts including Data and DTO models that utilizes Enum's:

::include gists/contact-dtos.md::

Each UI implements 4 different screens which are linked from:

 - [Login Page](http://validation.web-app.io/login-links) - Sign In to ServiceStack's built-in Username/Password Credentials Auth Provider
 - [Registration Page](http://validation.web-app.io/register-links) - Calling ServiceStack's built-in `/register` Service to register a new User
 - [Contacts Page](http://validation.web-app.io/contact-links) - Contacts Form to Add a new Contact and view list of existing contacts
 - [Edit Contact Page](http://validation.web-app.io/contact-edit-links) - Edit Contact Form

### Shared Error Handling Concepts

Despite their respective differences they share the same concepts where all validation errors are populated from the Service's `ResponseStatus`
Error Response. The UI implementations takes care of binding all matching field errors next to their respective controls whilst the 
`validationSummary` or `errorResponseExcept` methods takes a list of field names that they **should not display** as they'll already be 
displayed next to their targeted control.

We'll cover just the **Login** and **Contacts** Pages since they're sufficiently different, to see what this looks like in practice:

## Login Page

The Login Page contains a standard Bootstrap Username/Password form with labels, placeholders and help text, which initially looks like:

![](https://raw.githubusercontent.com/ServiceStack/Assets/master/img/apps/Validation/login-validation.png)

What it looks like after submitting an empty form with Server Exception Errors rendered against their respective fields:

![](https://raw.githubusercontent.com/ServiceStack/Assets/master/img/apps/Validation/login-validation-failed.png)

### Server UIs

All Server Examples submits a HTML Form Post and renders full page responses:

<server-login-uis></server-login-uis>

### About Server Implementations

Unfortunately Validation in Bootstrap doesn't lend itself to easy server rendering as it requires co-ordination with label, input and error feedback 
elements so **Sharp Pages** wraps this in a `formInput` control from `BootstrapScripts` to render both Label and Input elements together. 
For those preferring Razor, these same controls are available as `@Html` Helpers as seen in **Server Razor** which ends up having identical 
behavior and markup, albeit rendered using a different View Engine.

**Server TypeScript** shows a more fine-grained version where we show how to bind validation errors to your own custom HTML markup. 
This would normally end up being a lot more tedious to do so we've extended it with our own declarative `data-invalid` attribute to hold the 
fields error message which drastically reduces the manual binding effort required. Calling the `bootstrap()` method will scan the form for populated 
`data-invalid` attributes where it's used to render the appropriate error message adjacent to the control and toggle the appropriate error classes.

All TypeScript examples only depends on the dependency-free [@servicestack/client](https://github.com/ServiceStack/servicestack-client) which is
available as both an [npm package](https://www.npmjs.com/package/@servicestack/client) and as a stand-alone 
[servicestack-client.umd.js](https://unpkg.com/@servicestack/client/dist/servicestack-client.umd.js) script include.

The **Server jQuery** version uses the exact same markup as **Server TypeScript** but requires a dependency on jQuery and uses the
`$(document).bootstrap()` jQuery plugin from ServiceStack's built-in [ss-utils.js](/ss-utils-js).

#### Continue and ErrorView

In order to enable full-page reloads in ServiceStack's built-in Services like its `/auth` and `/register` Services we need to submit 2 additional
hidden input fields: `errorView` to tell it which page it should render on **failed requests** and `continue` to tell it where to redirect to after
**successful requests**.

### Client UIs

In contrast to full page reloads all Client UIs submit Ajax forms and bind their JSON Error Response to the UI for a more fluid and flicker-free UX:

<client-login-uis></client-login-uis>

### About Client Implementations

**Vuetify** is a Vue App which uses the popular [Vuetify Material Design UI](https://vuetifyjs.com/en/) which is in contrast to all other UIs which use Bootstrap. 
It also uses the `JsonServiceClient` to send a JSON `Authenticate` Request whereas all other UIs sends HTML Form `x-www-form-urlencoded` Key/Value Pairs.

**Client TypeScript** only needs to render the initial Bootstrap Form Markup as `bootstrapForm()` takes care of submitting the Ajax Request and binding
any validation errors to the form. The `data-validation-summary` placeholder is used to render any other error summary messages except for the `userName` 
or `password` fields.

**Client jQuery** uses the exact same markup but uses `$('form').bootstrapForm()` jQuery plugin to handle the form Ajax request and any error binding.

**Client Razor** adopts the same jQuery implementation but is rendered using MVC Razor instead of **Sharp Pages**.

## Contacts Page

The Contacts Page is representative of a more complex page that utilizes a variety of different form controls where the same page is also responsible
for rendering the list of existing contacts:

![](https://raw.githubusercontent.com/ServiceStack/Assets/master/img/apps/Validation/contacts-validation.png)

Here's an example of what a partially submitted invalid form looks like:

![](https://raw.githubusercontent.com/ServiceStack/Assets/master/img/apps/Validation/contacts-validation-failed.png)

### Server UIs

<server-contact-uis></server-contact-uis>

### About Server Implementations

Both the Contacts UIs and Contacts Services are protected resources which uses a **partial** to protect its pages. 
Normally `redirectIfNotAuthenticated` wouldn't require a URL, but one is needed here so it knows the right login page it should redirect to.

#### Sharp Pages

In **Sharp Pages** our wrist-friendly server controls are back as we start to see more of its features. The arguments of the left of the `formInput` 
are for HTML attributes you want rendered on the input control whilst the arguments on the right (or 2nd argument) are to enlist the controls 
other "high-level features" like `values` which is used to populate a list of radio and checkboxes or `formSelect` options. The `inline` 
argument tells the control to render multiple controls in-line whilst you can use `help` to render some help text as an aside.

We also see the introduction of the `sendToGateway` method used to send the `GetContacts` Request DTO to call its Service using the 
[Service Gateway](/service-gateway), the Response of which is used to render the list of contacts on the Server. 

:::v-pre
Another difference is that there are multiple `<form>` elements on this page to handle deleting a contact by submitting an empty form post to
`/contacts/{{Id}}/delete`.
:::

**Sharp Pages** doesn't need to specify its own `ErrorView` or `Continue` Request params as its the default view used for `ContactServices`: 

```csharp
[DefaultView("/server/contacts")] // Render custom HTML View for HTML Requests
public class ContactServices : Service { ... }
```

This is typically all that's needed, as most real-world Apps would rarely have more than 1 HTML View per Service. 

#### Server TypeScript

With **Server TypeScript** you're starting to see the additional effort required when you need to use your own custom markup to render form controls. 

It differs with **Sharp Pages** in that instead of rendering the list of contacts on the server, it renders the `GetContacts` Response DTO
as JSON which is interpreted in the browser as a native JS Object literal which the `render()` method uses to render the list of contacts in the browser.

Deleting a contact is also handled differently where it uses the `JsonServiceClient` to send the `DeleteContact` Request DTO from the generated `dtos.ts`.
After the request completes it uses `GetContacts` to fetch an updated list of Contacts which it re-renders.

#### Server jQuery

**Server jQuery** adopts the same approach as **Server TypeScript** but renders it using jQuery and uses custom routes constructed on the client 
with jQuery's Ajax APIs to call the `ContactServices`.

#### Server Razor

**Server Razor** is very similar to **Sharp Pages** but implemented using Razor. In many cases the built-in script methods in Sharp Pages have
Razor equivalents, either in the base `ViewPage<T>` class like `RedirectIfNotAuthenticated()` or as a `@Html` helper.

### Client UIs

<client-contact-uis></client-contact-uis>

### About Client Implementations

**Vuetify** ends up being larger than other implementations as it also handles Edit Contacts functionality which is a separate page in other UIs.
It also includes additional functionality like client-side validation enabled in each control using its `:rules` attribute. One thing
that remains consistent is the way to call ServiceStack Services and handle errors by assigning it to `this.responseStatus` which the reactive
`errorResponse` method uses to bind to each control.

The remaining client implementations show that whilst the server controls require the least code, if you need custom markup it's much easier 
to render the initial markup once, then use `bootstrapForm()` to bind any validation errors and handle the ajax form submissions. It's especially 
valuable when you need to update a form where the same markup can be populated by just assigning the `model` property as done in the 
[Edit Contact Pages](http://validation.web-app.io/contact-edit-links):

```ts
const form = document.querySelector("form")!;
bootstrapForm(form,{
    model: CONTACT,
    success: function () {
        location.href = '/client-ts/contacts/';
    }
});
```

The amount of code can be even further reduced when using an SPA framework that allows easy componentization as seen in the 
[Vue Form Validation](#vue-lite-project-template-features) and [React Form Validation](#react-lite-project-template-features) examples.


# Declarative Validation
Source: https://docs.servicestack.net/declarative-validation

Declarative validation facilitate greater declarative functionality around ServiceStack Services where all existing 
[Fluent Validation Property Validators](/validation#validation-feature) can be annotated on Request DTOs using typed validation 
attributes which are decoupled from their Validator implementation so they're suitable to be annotated on impl-free Service Model DTOs and exported in 
[Add ServiceStack Reference](/add-servicestack-reference) Types.

::: info Tip
As they're decoupled the same rules could enable instant validation feedback on clients without server round trips
:::

The validators are incorporated into ServiceStack's existing Fluent Validation model so it [works with existing UI form binding](/world-validation). 

## Validation Feature

All of ServiceStack's Fluent Validation features is encapsulated within the `ValidationFeature` plugin which is pre-registered by default.

The Validator attributes are decoupled from any implementation and can be safely annotated on Request DTOs without adding any implementation dependencies. There's both Type Validators for applying API-level validation and property Validation attributes which enable an alternative declarative way of defining [Fluent Validation rules](/validation) on properties.

### Type Validation Attributes

| Attribute                      | Description                                                             |
|--------------------------------|-------------------------------------------------------------------------|
| `[ValidateRequest]`            | Validate Type against a custom Validator expression                     |
| `[ValidateIsAuthenticated]`    | Protect access to this API to Authenticated Users only                  |
| `[ValidateIsAdmin]`            | Protect access to this API to Admin Users only                          |
| `[ValidateHasPermission]`      | Protect access to this API to only Users assigned with ALL Permissions  |
| `[ValidateHasRole]`            | Protect access to this API to only Users assigned with ALL Roles        |

### Property Validation Attributes

| Attribute                      | Description                                                             |
|--------------------------------|-------------------------------------------------------------------------|
| `[Validate]`                   | Validate property against custom Validator expression                   |
| `[ValidateCreditCard]`         | Validate property against Fluent Validation CreditCardValidator         |
| `[ValidateEmail]`              | Validate property against Fluent's AspNetCoreCompatibleEmailValidator   |
| `[ValidateEmpty]`              | Validate property against Fluent Validation EmptyValidator              |
| `[ValidateEqual]`              | Validate property against Fluent Validation EqualValidator              |
| `[ValidateExactLength]`        | Validate property against Fluent Validation ExactLengthValidator        |
| `[ValidateExclusiveBetween]`   | Validate property against Fluent Validation ExclusiveBetweenValidator   |
| `[ValidateGreaterThan]`        | Validate property against Fluent Validation GreaterThanValidator        |
| `[ValidateGreaterThanOrEqual]` | Validate property against Fluent Validation GreaterThanOrEqualValidator |
| `[ValidateInclusiveBetween]`   | Validate property against Fluent Validation InclusiveBetweenValidator   |
| `[ValidateLength]`             | Validate property against Fluent Validation LengthValidator             |
| `[ValidateLessThan]`           | Validate property against Fluent Validation LessThanValidator           |
| `[ValidateLessThanOrEqual]`    | Validate property against Fluent Validation LessThanOrEqualValidator    |
| `[ValidateMaximumLength]`      | Validate property against Fluent Validation MaximumLengthValidator      |
| `[ValidateMinimumLength]`      | Validate property against Fluent Validation MinimumLengthValidator      |
| `[ValidateNotEmpty]`           | Validate property against Fluent Validation NotEmptyValidator           |
| `[ValidateNotEqual]`           | Validate property against Fluent Validation NotEqualValidator           |
| `[ValidateNotNull]`            | Validate property against Fluent Validation NotNullValidator            |
| `[ValidateNull]`               | Validate property against Fluent Validation NullValidator               |
| `[ValidateRegularExpression]`  | Validate property against Fluent Validation RegularExpressionValidator  |
| `[ValidateScalePrecision]`     | Validate property against Fluent Validation ScalePrecisionValidator     |

## Property Validator Examples

The Property Validator attributes provide an alternative way to apply Request DTO validation rules, the best way to demonstrate them 
is showing the same example below implemented using Fluent Validation APIs:

```csharp
public class ExampleValidatorsValidator : AbstractValidator<ExampleValidators>
{
    public ExampleValidatorsValidator()
    {
        RuleFor(x => x.CreditCard).CreditCard();
        RuleFor(x => x.Email).EmailAddress();
        RuleFor(x => x.Empty).Empty();
        RuleFor(x => x.Equal).Equal("Equal");
        RuleFor(x => x.ExclusiveBetween).ExclusiveBetween(10, 20);
        RuleFor(x => x.GreaterThanOrEqual).GreaterThanOrEqualTo(10);
        RuleFor(x => x.GreaterThan).GreaterThan(10);
        RuleFor(x => x.InclusiveBetween).InclusiveBetween(10, 20);
        RuleFor(x => x.Length).Length(10);
        RuleFor(x => x.LessThanOrEqual).LessThanOrEqualTo(10);
        RuleFor(x => x.LessThan).LessThan(10);
        RuleFor(x => x.NotEmpty).NotEmpty();
        RuleFor(x => x.NotEqual).NotEqual("NotEqual");
        RuleFor(x => x.Null).Null();
        RuleFor(x => x.ScalePrecision).ScalePrecision(1,1);
        RuleFor(x => x.RegularExpression).Matches(@"^[a-z]*$");
    }
}
```

For each property validator above you can use a Typed Property Validation Attribute in the format `[Validate*]`:

```csharp
public class ExampleValidators : ICreateDb<ExampleValidator>, IReturn<EmptyResponse>
{
    [ValidateCreditCard]
    public string CreditCard { get; set; }
    [ValidateEmail]
    public string Email { get; set; }
    [ValidateEmpty]
    public string Empty { get; set; }
    [ValidateEqual("Equal")]
    public string Equal { get; set; }
    [ValidateLessThan(10)]
    public int LessThan { get; set; }
    [ValidateLessThanOrEqual(10)]
    public int LessThanOrEqual { get; set; }
    [ValidateGreaterThan(10)]
    public int GreaterThan { get; set; }
    [ValidateGreaterThanOrEqual(10)]
    public int GreaterThanOrEqual { get; set; }
    [ValidateExclusiveBetween(10, 20)]
    public int ExclusiveBetween { get; set; }
    [ValidateInclusiveBetween(10, 20)]
    public int InclusiveBetween { get; set; }
    [ValidateExactLength(10)]
    public string Length { get; set; }
    [ValidateNotEmpty]
    public string NotEmpty { get; set; }
    [ValidateNotEqual("NotEqual")]
    public string NotEqual { get; set; }
    [ValidateNull]
    public string Null { get; set; }
    [ValidateScalePrecision(1,1)]
    public decimal ScalePrecision { get; set; }
    [ValidateRegularExpression("^[a-z]*$")]
    public string RegularExpression { get; set; }
}
```

All Typed Validator Attributes above are just providing a typed subclass wrapper around the generic `[Validate]`, so the implementation of
the `[ValidateLessThan]` is just:

```csharp
public class ValidateLessThanAttribute : ValidateAttribute
{
    public ValidateLessThanAttribute(int value) : base($"LessThan({value})") { }
}
```

### Generic Validator Attributes

So the same Typed Validator above is equivalent to using the untyped generic `[Validate]` attribute below:

```csharp
public class ExampleValidators : ICreateDb<ExampleValidator>, IReturn<EmptyResponse>
{
    [Validate("CreditCard")]
    public string CreditCard { get; set; }
    [Validate("Email")]
    public string Email { get; set; }
    [Validate("Empty")]
    public string Empty { get; set; }
    [Validate("Equal('Equal')")]
    public string Equal { get; set; }
    [Validate("ExclusiveBetween(10, 20)")]
    public int ExclusiveBetween { get; set; }
    [Validate("GreaterThanOrEqual(10)")]
    public int GreaterThanOrEqual { get; set; }
    [Validate("GreaterThan(10)")]
    public int GreaterThan { get; set; }
    [Validate("InclusiveBetween(10, 20)")]
    public int InclusiveBetween { get; set; }
    [Validate("ExactLength(10)")]
    public string Length { get; set; }
    [Validate("LessThanOrEqual(10)")]
    public int LessThanOrEqual { get; set; }
    [Validate("LessThan(10)")]
    public int LessThan { get; set; }
    [Validate("NotEmpty")]
    public string NotEmpty { get; set; }
    [Validate("NotEqual('NotEqual')")]
    public string NotEqual { get; set; }
    [Validate("Null")]
    public string Null { get; set; }
    [Validate("RegularExpression('^[a-z]*$')")]
    public string RegularExpression { get; set; }
    [Validate("ScalePrecision(1,1)")]
    public decimal ScalePrecision { get; set; }
}
```

Where the **Validator Expression** is a `#Script` Expression that returns a Fluent Validation `IPropertyValidator` defined
in the built-in [ValidateScripts.cs](https://github.com/ServiceStack/ServiceStack/blob/master/src/ServiceStack/ValidateScripts.cs):

```csharp
public class ValidateScripts : ScriptMethods
{
    public IPropertyValidator Null() => new NullValidator();
    public IPropertyValidator Empty() => new EmptyValidator(null);
    public IPropertyValidator Empty(object defaultValue) => new EmptyValidator(defaultValue);
    public IPropertyValidator Equal(object value) => new EqualValidator(value);
    public IPropertyValidator NotNull() => new NotNullValidator();
    public IPropertyValidator NotEmpty() => new NotEmptyValidator(null);
    public IPropertyValidator NotEmpty(object defaultValue) => new NotEmptyValidator(defaultValue);
    public IPropertyValidator NotEqual(object value) => new NotEqualValidator(value);
    public IPropertyValidator CreditCard() => new CreditCardValidator();
    public IPropertyValidator Email() => new AspNetCoreCompatibleEmailValidator();
    public IPropertyValidator Length(int min, int max) => new LengthValidator(min, max);
    public IPropertyValidator ExactLength(int length) => new ExactLengthValidator(length);
    public IPropertyValidator MaximumLength(int max) => new MaximumLengthValidator(max);
    public IPropertyValidator MinimumLength(int min) => new MinimumLengthValidator(min);
    public IPropertyValidator InclusiveBetween(IComparable from, IComparable to) =>
        new InclusiveBetweenValidator(from, to);
    public IPropertyValidator ExclusiveBetween(IComparable from, IComparable to) =>
        new ExclusiveBetweenValidator(from, to);
    public IPropertyValidator LessThan(int value) => new LessThanValidator(value);
    public IPropertyValidator LessThanOrEqual(int value) => new LessThanOrEqualValidator(value);
    public IPropertyValidator GreaterThan(int value) => new GreaterThanValidator(value);
    public IPropertyValidator GreaterThanOrEqual(int value) => new GreaterThanOrEqualValidator(value);
    public IPropertyValidator ScalePrecision(int scale, int precision) =>
        new ScalePrecisionValidator(scale, precision);
    public IPropertyValidator RegularExpression(string regex) => 
        new RegularExpressionValidator(regex, RegexOptions.Compiled);
}
```

### Validated Validator Expressions

Despite using untyped string Expressions, **Validator** expressions still provide early error detection as on `Startup` each `#Script` 
expression is evaluated and verified that it resolves to a valid `IPropertyValidator` instance otherwise fails with a **Startup Exception**.
If the instance returned is valid it's merged with any other `AbstractValidator<T>` that may also be defined for the same Request DTO Type, 
where it lets you mix n' match declarative attributes together with Fluent Validation rules.

### Defining Multiple Validators

You can specify multiple Property Validators should be applied within a single Validator expression by using `[]` Array notation, 
alternatively you can apply multiple Validate attributes and use C# syntax to combine them in a single line:

```csharp
public class ExampleValidators
{
    [Validate("[NotNull,InclusiveBetween(13,100)]")]
    public int? ValidateAge { get; set; }

    [ValidateNotNull,ValidateInclusiveBetween(13,100)]
    public int? TypedAge { get; set; }
}
```

### Registering Custom Declarative Validators

As `[Validate*]` attributes just execute a Script Method they're easily extensible by [defining and register your own](https://sharpscript.net/docs/methods), e.g:

```csharp
public class MyValidateScripts : ScriptMethods
{
    public IPropertyValidator Custom(int arg) => new MyCustomValidator(arg);
}
```

Which can be registered, either directly on your [Script Pages plugin](https://sharpscript.net/docs/script-pages) if your AppHost uses one:

```csharp
Plugins.Add(new SharpPagesFeature {
    ScriptMethods = { new CustomScriptMethods() }
});
```

Otherwise you can use the AppHost's new `ScriptContext` which adds it to the AppHost's empty `ScriptContext`:

```csharp
ScriptContext.ScriptMethods.Add(new CustomScriptMethods());
```

> `ScriptContext` also returns `SharpPagesFeature` if registered, in which case both registration examples are equivalent

After which you'll immediately be able to use it with the `[Validate]` attribute:

```csharp
[Validate("Custom(1)")]
public int Test { get; set; }
```

Likewise you can create a typed Validate attribute around it which you can use instead:

```csharp
public class ValidateCustomAttribute : ValidateAttribute
{
    public ValidateCustomAttribute(int arg) : base($"Custom({arg})") { }
}
//...

[ValidateCustom(1)]
public int Test { get; set; }
```

### Custom Script Validation

Fluent Validation Validators are a nice model for defining reusable validation rules however they can require a bit of boilerplate
if you only need to define a one-off validation check. In these cases we can provide an even lighter weight solution by being able
to defining our validation condition inline with `#Script` by specifying it in the `Condition` attribute, e.g:

```csharp
public class ExampleValidators : ICreateDb<ExampleValidator>, IReturn<EmptyResponse>
{
    [Validate(Condition = "it.isOdd()")]
    public int IsOddCondition { get; set; }

    [Validate(Condition = "it.isOdd() && it.log10() > 2")]
    public int IsOddAndOverTwoDigitsCondition { get; set; }

    [Validate(Condition = "it.isOdd() || it.log10() > 2")]
    public int IsOddOrOverTwoDigitsCondition { get; set; }
}
```

Script Conditions are valid if they return a **truthy** value and have access to the following arguments within their Expression: 

 - `Request`: IRequest
 - `dto`: Request DTO
 - `field`: Property Name
 - `it`: Property Value

If you're reusing the same Expression a nice solution for maintaining them is in a static class where you can use the `AllConditions`
and `AnyConditions` helper properties to compose individual checks, e.g:

```csharp
public static class ValidationConditions
{
    public const string IsOdd = "it.isOdd()";
    public const string IsOver2Digits = "it.log10() > 2";
}

public class ExampleValidators : ICreateDb<ExampleValidator>, IReturn<EmptyResponse>
{
    [Validate(Condition = ValidationConditions.IsOdd)]
    public int IsOddCondition { get; set; }

    [Validate(AllConditions = new[]{ ValidationConditions.IsOdd, ValidationConditions.IsOver2Digits })]
    public int IsOddAndOverTwoDigitsCondition { get; set; }

    [Validate(AnyConditions = new[]{ ValidationConditions.IsOdd, ValidationConditions.IsOver2Digits })]
    public int IsOddOrOverTwoDigitsCondition { get; set; }
}
```

Despite not using a validator all `#Script` Conditions are executed using a custom Fluent Validation `IPredicateValidator`
(called [ScriptConditionValidator](https://github.com/ServiceStack/ServiceStack/blob/master/src/ServiceStack/Validators.cs)) so it able to slot right 
in with all other Property Validators.

### Custom Error Codes and Messages

The other aspect of validators that can be overridden declaratively are the **ErrorCode** and Error **Message** returned in ServiceStack's
[structured Error Response](/error-handling), specified using the `ErrorCode` and `Message` Attribute properties:

```csharp
public class ExampleValidators : ICreateDb<ExampleValidator>, IReturn<EmptyResponse>
{
    [ValidateNotNull(ErrorCode = "ZError")]
    public string CustomErrorCode { get; set; }
    
    // Overrides both ErrorCode & Message
    [ValidateInclusiveBetween(1,2, ErrorCode = "ZError", 
        Message = "{PropertyName} has to be between {From} and {To}, you: {PropertyValue}")]
    public int CustomErrorCodeAndMessage { get; set; }

    // Overrides ErrorCode & uses Message from Validators
    [ValidateNotNull(ErrorCode = "RuleMessage")]
    public string ErrorCodeRule { get; set; }

    [Validate(Condition = ValidationConditions.IsOdd)]
    public int IsOddCondition { get; set; }

    [Validate(AllConditions = new[]{ ValidationConditions.IsOdd, ValidationConditions.IsOver2Digits }, 
        ErrorCode = "RuleMessage")]
    public int IsOddAndOverTwoDigitsCondition { get; set; }
}
```

All Error Messages can reference the `{PropertyName}` and `{PropertyValue}` in their messages along with any other MessageFormatter
placeholders defined by the validator, e.g. the [InclusiveBetweenValidator.cs](https://github.com/ServiceStack/ServiceStack/blob/master/src/ServiceStack/FluentValidation/Validators/InclusiveBetweenValidator.cs) used above also defines the `{From}`, `{To}` and `{Value}` placeholders.

`#Script` Conditions can define their Error codes in the centralized `ConditionErrorCodes` Dictionary in the `ValidationFeature` Plugin
where all `IsOdd` conditions will return the **NotOdd** custom error code.

The Error Messages can also be defined in the centralized `ErrorCodeMessages` Dictionary which defines the Error Messages that all failed
**NotOdd** or **RuleMessage** rules will use, e.g:

```csharp
Plugins.Add(new ValidationFeature {
    ConditionErrorCodes = {
        [ValidationConditions.IsOdd] = "NotOdd",
    },
    ErrorCodeMessages = {
        ["NotOdd"] = "{PropertyName} must be odd",
        ["RuleMessage"] = "ErrorCodeMessages for RuleMessage",
    }
});
```

## Type Validators

In addition to Property Validators there's also support for **Type Validators** which can be declaratively added to perform top-level 
validation on Request DTOs. They behave and function the same as Property Validators where you can use either the typed or the generic `[ValidateRequest]` attribute.

ServiceStack includes built-in Type Validator attributes for all [Authorization Filter Attributes](/auth/authentication-and-authorization#the-authenticate-attribute) 
but as they're decoupled from any implementation they can be safely annotated on Request DTOs without requiring any implementation dependencies.

```csharp
[ValidateIsAuthenticated]            // or [ValidateRequest("IsAuthenticated")]
[ValidateIsAdmin]                    // or [ValidateRequest("IsAdmin")]
[ValidateHasRole(role)]              // or [ValidateRequest($"HasRole(`{role}`)")]
[ValidateHasPermission(permission)]  // or [ValidateRequest($"HasPermission(`{permission}`)")
```

Just like Property Validators, the Typed Validator attributes are wrappers around the generic `[ValidateRequest]` attribute, e.g:

```csharp
public class ValidateIsAuthenticatedAttribute : ValidateRequestAttribute
{
    public ValidateIsAuthenticatedAttribute() : base("IsAuthenticated") { }
}
```

Which are also defined in [ValidateScripts.cs](https://github.com/ServiceStack/ServiceStack/blob/master/src/ServiceStack/ValidateScripts.cs) 
but instead return a `ITypeValidator`:

```csharp
public class ValidateScripts : ScriptMethods
{
    public ITypeValidator IsAuthenticated() => new IsAuthenticatedValidator();
    public ITypeValidator IsAuthenticated(string provider) => new IsAuthenticatedValidator(provider);
    public ITypeValidator HasRole(string role) => new HasRolesValidator(role);
    public ITypeValidator HasRoles(string[] roles) => new HasRolesValidator(roles);
    public ITypeValidator HasPermission(string permission) => new HasPermissionsValidator(permission);
    public ITypeValidator HasPermissions(string[] permission) => new HasPermissionsValidator(permission);
    public ITypeValidator IsAdmin() => new HasRolesValidator(RoleNames.Admin);
}
```

#### Custom Type Attributes

The easiest way to create a an `ITypeValidator` is to inherit from the `TypeValidator` base class, including both the **ErrorCode**
and **Error Message** failed requests should return. 

An example where you might use one is when testing the pre-condition state of an entity which doesn't logically map to a property.
In the example below we're validating to ensure that the entity doesn't have any Foreign Key References:

```csharp
public class NoRockstarAlbumReferences : TypeValidator
{
    public NoRockstarAlbumReferences() 
        : base("HasForeignKeyReferences", "Has RockstarAlbum References") {}

    public override async Task<bool> IsValidAsync(object dto, IRequest request)
    {
        //Example of using compiled accessor delegates to access `Id` property
        //var id = TypeProperties.Get(dto.GetType()).GetPublicGetter("Id")(dto).ConvertTo<int>();

        var id = ((IHasId<int>)dto).Id;
        using var db = HostContext.AppHost.GetDbConnection(request);
        return !await db.ExistsAsync<RockstarAlbum>(x => x.RockstarId == id);
    }
}
```

Then we need to register it as a custom script method to be able to reference it in `[ValidateRequest]`:

```csharp
public class MyValidators : ScriptMethods
{
    public ITypeValidator NoRockstarAlbumReferences() => new NoRockstarAlbumReferences();
}
```

Which we can now declaratively reference by script method name:

```csharp
[ValidateRequest(nameof(NoRockstarAlbumReferences))]
public class ExampleValidators : ICreateDb<Rockstar>, IReturn<RockstarWithIdResponse>, IHasId<int>
{
    public int Id { get; set; }
    
    [ValidateNotNull] //doesn't get validated if ValidateRequest is invalid
    public string NotNull { get; set; }
}
```

Type Validators are executed before any property validators, which if failed wont be executed.

### Type Script Conditions

Type Validators can also execute `#Script` expressions where we could implement the above FK check inline using
a sync [Database Script](https://sharpscript.net/docs/db-scripts):

```csharp
[ValidateRequest(Condition = "!dbExistsSync('SELECT * FROM RockstarAlbum WHERE RockstarId = @Id', { it.Id })", 
    ErrorCode = "HasForeignKeyReferences")]
public class ExampleValidators : ICreateDb<Rockstar>, IReturn<RockstarWithIdResponse>
{
    public int Id { get; set; }
    
    [ValidateNotNull] //doesn't get validated if ValidateRequest is invalid
    public string NotNull { get; set; }
}
```

::: info
the condition needs to return a **truthy** value so you'd need to use the sync DB Script APIs to return
a boolean instead of an async Task.
:::

Type Validators can also specify custom Error Codes and Error Messages, they can also specify a custom HTTP 
Error StatusCode that failed requests should return.

```csharp
[ValidateRequest(Condition = "it.Test.isOdd() && it.Test.log10() > 2",
    ErrorCode = "NotOddAndOver2Decimals", Message = "Pre-condition Failed", StatusCode = 401)]
public class ExampleValidators : ICreateDb<ExampleValidator>, IReturn<EmptyResponse> { }
```

## DB Validation Rules

Both Property and Type Validators can also be sourced from a **dynamic source** with both **Memory** and **RDBMS** implementations included 
along with a Management HTTP API which can be be managed remotely programmatically or from the [Validation Admin UI](/admin-ui-validation):

<div class="block p-4 rounded shadow">
    <a href="/admin-ui-validation">
        <img src="/img/pages/admin-ui/validation-category.png">
    </a>
</div>

Dynamic Validation Rules are cacheable locally giving them the same performance profile as declarative attributes in code whose caches are only invalidated once they've been updated, upon which they'll come into immediate effect.

Here's a [Modular Startup](/modular-startup) code you can drop into a ServiceStack Project to enable maintaining declarative Validation 
Rules in your configured RDBMS:

```csharp
using ServiceStack;
using ServiceStack.Data;

[assembly: HostingStartup(typeof(MyApp.ConfigureValidation))]

namespace MyApp
{
    public class ConfigureValidation : IHostingStartup
    {
        // Add support for dynamically generated db rules
        public void Configure(IWebHostBuilder builder) => builder
            .ConfigureServices(services => services.AddSingleton<IValidationSource>(c =>
                new OrmLiteValidationSource(c.Resolve<IDbConnectionFactory>(), HostContext.LocalCache)))
            .ConfigureAppHost(appHost => {
                appHost.Resolve<IValidationSource>().InitSchema();
            });
    }
}
```

::: info
The above code can be imported into your ServiceStack project by using `x mix validation-source` 
if you are using .NET 6 modular startup.
:::

DB Validation rules can be added programmatically, this example below adds 1x Type Validator and 2x Property Validators to the 
`DynamicRules` Request DTO:

```csharp
var validationSource = container.Resolve<IValidationSource>();
validationSource.SaveValidationRulesAsync(new List<ValidationRule> {
    new ValidationRule { Type  = nameof(DynamicRules), Validator = "IsAuthenticated" },
    new ValidationRule { Type  = nameof(DynamicRules), Validator = "NotNull", 
                         Field = nameof(DynamicRules.LastName) },
    new ValidationRule { Type  = nameof(DynamicRules), Validator = "InclusiveBetween(13,100)", 
                         Field = nameof(DynamicRules.Age) },
});
```

**Admin** Users can also manage these rules remotely using the `ModifyValidationRules` Service defined below:

```csharp
public class ModifyValidationRules : IReturnVoid
{
    public string AuthSecret { get; set; }

    public List<ValidationRule> SaveRules { get; set; }

    public int[] DeleteRuleIds { get; set; }

    public int[] SuspendRuleIds { get; set; }

    public int[] UnsuspendRuleIds { get; set; }
    
    public bool? ClearCache { get; set; }
}
```

### ServiceStack Studio Validators UI

ServiceStack Studio utilizes the above `ModifyValidationRules` for its support for [managing DB Validation rules](/studio#validators-ui),
with an optimized UX that lets you quickly select & configure all built-in & registered property & type validators where they're instantly applied.


# Debugging
Source: https://docs.servicestack.net/debugging

## SourceLink Enabled Packages 

To maximize the debuggability of ServiceStack packages all ServiceStack projects utilize **MSBuild generated NuGet packages** 
where all packages are embed **pdb symbols** and are configured with [support for SourceLink](https://github.com/dotnet/sourcelink/) 
to improve the debugging experience of ServiceStack Apps as source files can be downloaded on-the-fly from GitHub as you debug.

Scott Hanselman has written a [nice post on Source Link](https://www.hanselman.com/blog/ExploringNETCoresSourceLinkSteppingIntoTheSourceCodeOfNuGetPackagesYouDontOwn.aspx) 
and how it can be enabled inside VS.NET by turning on **Enable source link support**:

[![](https://www.hanselman.com/blog/content/binary/Windows-Live-Writer/7e5fb7b6dad8_140AA/image_0c73cb8d-bd5a-406e-a51d-a2eb4af12117.png)](https://www.hanselman.com/blog/ExploringNETCoresSourceLinkSteppingIntoTheSourceCodeOfNuGetPackagesYouDontOwn.aspx)

When enabled it should let you debug into the ServiceStack framework implementation, downloading the correct source files version from GitHub as and when needed.

### All ServiceStack GitHub projects use CI NuGet feed

In addition to using MSBuild generated packages all projects also utilize CI NuGet package feeds for external dependencies instead of copying 
.dll's in `/lib` folders. As a consequence you'll no longer have to build external ServiceStack GitHub projects or use GitHub published releases, 
as now the **master** repo of all GitHub projects can be built from a clean checkout at anytime.

The pre-release packages are still published using the **same version number** so if you get a build error from having a cached stale package
you'll need to [clear your local packages cache](/pre-release#redownloading-myget-packages) to download the latest build packages from the CI NuGet packages feed.

### Linking to Source projects

In order to get the best source-based development experience using the latest version of ServiceStack in your Projects, clone the ServiceStack
Repos you want to use:

 - [ServiceStack/ServiceStack](https://github.com/ServiceStack/ServiceStack)
 - [ServiceStack/ServiceStack.Text](https://github.com/ServiceStack/ServiceStack/tree/main/ServiceStack.Text)
 - [ServiceStack/ServiceStack.OrmLite](https://github.com/ServiceStack/ServiceStack/tree/main/ServiceStack.OrmLite)
 - [ServiceStack/ServiceStack.Aws](https://github.com/ServiceStack/ServiceStack/tree/main/ServiceStack.Aws)
 - [ServiceStack/ServiceStack.Azure](https://github.com/ServiceStack/ServiceStack/tree/main/ServiceStack.Azure)

Then reference the `*.Source.csproj` of each project you want to reference in your solution. 

This approach is used in our [Test.csproj](https://github.com/NetCoreApps/Test/blob/master/src/Test/Test.csproj) allowing us to debug directly into ServiceStack library source code just like any other project reference in our solution.

### Alternatives Debugging Solutions

[GitLink](https://oren.codes/2015/09/23/enabling-source-code-debugging-for-your-nuget-packages-with-gitlink/)
is another solution for debugging source code in NuGet packages.

Otherwise the most reliable solution for debugging ServiceStack source code is to 
[download the source code for the release](https://github.com/ServiceStack/ServiceStack/releases) on Github 
you want to debug, build the VS.NET Solution locally using **Debug** configuration then change your 
ServiceStack references to use your local **.dll**.

## Configuration

### DebugMode

ServiceStack allows additional debug information when in **DebugMode**, which is automatically set by 
default in **Debug** builds or explicitly with:

```csharp
SetConfig(new HostConfig { DebugMode = true });
```

In addition, users with the **Admin** role or Requests with an **AuthSecret** can also view Debug Info 
in production.

### StrictMode

You can configure Strict Mode in ServiceStack to enforce stricter behavior and have it throw Exceptions when it 
sees certain failure conditions. To enable Strict Mode across all libraries use:

```csharp
Env.StrictMode = true;
```

Otherwise to just enable StrictMode for ServiceStack:

```csharp
SetConfig(new HostConfig {
    StrictMode = true
})
```

When enabled ServiceStack will perform runtime checks to catch invalid state, currently:

 - Checks if Services return Value Types
 - Checks if UserSession has circular dependencies
 - Fails fast for exceptions on Startup

### Admin Role

Users in the `Admin` role have super-user access giving them access to any services or plugins protected 
with Roles and Permissions.

### AuthSecret

You can use **Config.AdminAuthSecret** to specify a special string to give you admin access without having 
to login by adding `?authsecret=xxx` to the query string, e.g:

```csharp
SetConfig(new HostConfig { AdminAuthSecret = "secretz" });
```

By-pass protected services using query string:

```
/my-service?authsecret=secretz
```

### AuthSecret HttpHeader

In addition to **authsecret** QueryString, FormData or Cookie, it can also be sent with any request with the `authsecret` HTTP Header, e.g:

```ts
let client = new JsonServiceClient(BaseUrl).apply(c => {
    c.basePath = '/api'
    c.headers.set('authsecret', authsecret)
})
```

Or it can be sent in the `authsecret` Cookie or `X-Param-Override-authsecret` HTTP Header.

## Debug Links

To provide better visibility to the hidden functionality in ServiceStack we've added **Debug Info** links 
section to the `/metadata` page which add links to any Plugins with Web UI's, e.g:

![Debug Info Links](http://i.imgur.com/2Hf3P9L.png)

The **Debug Links** section is only available in **DebugMode**.

You can add links to your own [Plugins](/plugins) in the metadata pages with:

```csharp
appHost.GetPlugin<MetadataFeature>()
    .AddPluginLink("swagger-ui/", "Swagger UI");

appHost.GetPlugin<MetadataFeature>()
    .AddDebugLink("?debug=requestinfo", "Request Info");
```

`AddPluginLink` adds links under the **Plugin Links** section and should be used if your plugin is publicly 
visible, otherwise use `AddDebugLink` for plugins only available during debugging or development.

## Startup Errors

When plugins are registered their Exceptions are swallowed and captured in `AppHost.StartupErrors` so an 
individual Rogue plugin won't prevent your ServiceStack AppHost from starting. But when a plugin doesn't 
work properly it can be hard to determine the cause was due to an Exception occuring at Startup. 

Alternatively enable [StrictMode](#strictmode) to have StartUp Exceptions thrown on StartUp.

## Debug Inspector

[![](https://sharpscript.net/assets/img/screenshots/metadata-debug.png)](https://sharpscript.net/metadata/debug)

All ServiceStack Apps have access to rich introspection and queryability for inspecting remote ServiceStack instances with the new [Debug Inspector](https://sharpscript.net/docs/servicestack-scripts#debug-template).

The Debug Template is a Service in `SharpPagesFeature` that's pre-registered in [DebugMode](#debugmode). The Service can also be available when not in **DebugMode** by enabling it with:

```csharp
Plugins.Add(new SharpPagesFeature { 
    MetadataDebugAdminRole = RoleNames.Admin,        // Only allow Admin users
})
```

This registers the Service but limits it to Users with the `Admin` role, alternatively you configure an 
[Admin Secret](/debugging#authsecret):

```csharp
SetConfig(new HostConfig { AdminAuthSecret = "secret" })
```

Which will let you access it by appending the authsecret to the querystring: `/metadata/debug?authsecret=secret`

Alternatively if preferred you can make the Debug Template Service available to:

```csharp
Plugins.Add(new SharpPagesFeature { 
    MetadataDebugAdminRole = RoleNames.AllowAnyUser,  // Allow Authenticated Users
    MetadataDebugAdminRole = RoleNames.AllowAnon,     // Allow anyone
})
```

Which is the configuration that allows [sharpscript.net/metadata/debug](https://sharpscript.net/metadata/debug) to be accessible to anyone.

## Lisp TCP Repl Server

A even greater way to get deeper insights into a Live running remote ServiceStack App is to open a
[Lisp TCP REPL Server](/lisp-tcp-repl-server) into the server to open a **"programmable gateway"** into any 
ServiceStack App where you're able to perform live queries, access IOC dependencies, invoke internal Server functions and query
the state of a running Server to provide invaluable insight when diagnosing issues on a remote server.

::: info YouTube
[youtu.be/HO523cFkDfk](https://youtu.be/HO523cFkDfk)
:::

[![](/img/pages/sharpscript/lisp-tcp-repl.gif)](https://youtu.be/HO523cFkDfk)


### Request Info

ServiceStack's Request Info feature is useful for debugging requests. Just add **?debug=requestinfo** 
in your `/pathinfo` and ServiceStack will return a dump of all the HTTP Request parameters to help with 
debugging interoperability issues. The RequestInfoFeature is only enabled in [DebugMode](/debugging#debugmode).

To better highlight the presence of Startup Errors a red warning banner will also appear in `/metadata` pages when in [DebugMode](/debugging#debugmode), e.g:

![](./img/pages/release-notes/startup-errors.png)

The number of Startup Errors is also added to the `X-Startup-Errors: n` Global HTTP Header so you'll be 
able to notice it when debugging HTTP Traffic.

If you prefer that any Plugin Exception is immediately visible you can register this callback in your 
`AppHost` to throw a YSOD with your first Startup Error:

```csharp
AfterInitCallbacks.Add(host => {
    var appHost = (ServiceStackHost)host;
    if (appHost.StartUpErrors.Count > 0)
        throw new Exception(appHost.StartUpErrors[0].Message);
});
```

## Plugins

There are a number of plugins that can help with debugging:

### [Request Logger](/request-logger)

Add an In-Memory `IRequestLogger` and service with the default route at `/requestlogs` which maintains a 
live log of the most recent requests (and their responses). Supports multiple config options incl. 
Rolling-size capacity, error and session tracking, hidden request bodies for sensitive services, etc.

```cs
Plugins.Add(new RequestLogsFeature());
```

The `IRequestLogger` is a great way to introspect and analyze your service requests in real-time, e.g:

![Live Screenshot](https://raw.githubusercontent.com/ServiceStack/Assets/master/img/wikis/request-logs-01.png)

It supports multiple queryString filters and switches so you filter out related requests for better analysis 
and debuggability:

![Request Logs Usage](https://raw.githubusercontent.com/ServiceStack/Assets/master/img/wikis/request-logs-02.png)

The [RequestLogsService](https://github.com/ServiceStack/ServiceStack/blob/master/src/ServiceStack/Admin/RequestLogsService.cs) is just a simple C# service under-the-hood but is a good example of how a little bit of code can provide a lot of value in ServiceStack's by leveraging its generic, built-in features.


# Service Clients Overview
Source: https://docs.servicestack.net/clients-overview

As ServiceStack Services are pure HTTP APIs they're accessible with any HTTP-capable client, but they're also capable of native client integrations with popular languages used to create Web, Mobile and Desktop Apps for maximum productivity and correctness.

The developer workflow is further simplified with IDE plugins that let you generate native client DTOs directly from your favorite IDEs:

<section class="text-center">
    <div class="container">
    <div class="mx-auto max-w-md px-4 text-center sm:max-w-3xl sm:px-6 lg:max-w-7xl lg:px-8">
      <h2 class="text-base font-semibold uppercase tracking-wider  text-indigo-600">Develop faster</h2>
      <p class="mt-2 text-3xl font-extrabold tracking-tight text-gray-900 dark:text-gray-50 sm:text-4xl">Right Click, Integrate</p>
      <p class="mx-auto mt-5 max-w-prose text-xl text-gray-500"> 
        Native client integrations for your APIs in all popular languages and IDEs
      </p>
    </div>
        <div class="flex flex-wrap">
          <div class="w-full lg:w-1/4 mt-4">
            <a href="https://marketplace.visualstudio.com/items?itemName=Mythz.ServiceStackVS">
              <div class="inline-flex justify-center">
                <img src="/img/pages/svg/vs-2019.svg" class="w-20 h-20">
              </div>
              <h3>Visual Studio</h3>
            </a>
            <h4>Languages Supported</h4>
            <p class="italic">
              C#, F#, TypeScript, VB.NET
            </p>
          </div>
          <div class="w-full lg:w-1/4 mt-4">
            <a href="https://plugins.jetbrains.com/plugin/17295-servicestack">
              <div class="inline-flex justify-center">
                <img src="/img/pages/svg/ides/icon-rider.svg"  class="w-20 h-20">
              </div>
              <h3>Rider</h3>
            </a>
            <h4>Languages Supported</h4>
            <p class="italic">
              C#, F#, TypeScript, VB.NET
            </p>
          </div>
          <div class="w-full lg:w-1/4 mt-4">
            <a href="https://plugins.jetbrains.com/plugin/7749-servicestack">
              <div class="inline-flex justify-center">
                <img src="/img/pages/svg/ides/icon-intellij-idea.svg" class="w-20 h-20">
              </div>
              <h3>IntelliJ</h3>
            </a>
            <h4>Languages Supported</h4>
            <p class="italic">
              Java, Kotlin, TypeScript
            </p>
          </div>
          <div class="w-full lg:w-1/4 mt-4">
            <a href="https://plugins.jetbrains.com/plugin/7749-servicestack">
              <div class="inline-flex justify-center">
                <img src="/img/pages/svg/ides/icon-webstorm.svg"  class="w-20 h-20">
              </div>
              <h3>WebStorm</h3>
            </a>
            <h4>Languages Supported</h4>
            <p class="italic">
              TypeScript
            </p>
          </div>
          <div class="w-full lg:w-1/4 mt-4">
            <a href="https://plugins.jetbrains.com/plugin/7749-servicestack">
              <div class="inline-flex justify-center">
                <img src="/img/pages/svg/ides/icon-pycharm.svg"  class="w-20 h-20">
              </div>
              <h3>PyCharm</h3>
            </a>
            <h4>Languages Supported</h4>
            <p class="italic">
              Python, TypeScript
            </p>
          </div>
          <div class="w-full lg:w-1/4 mt-4">
            <a href="https://plugins.jetbrains.com/plugin/7749-servicestack">
              <div class="inline-flex justify-center">
                <img src="/img/pages/svg/ides/icon-rubymine.svg"  class="w-20 h-20">
              </div>
              <h3>RubyMine</h3>
            </a>
            <h4>Languages Supported</h4>
            <p class="italic">
              TypeScript
            </p>
          </div>
          <div class="w-full lg:w-1/4 mt-4">
            <a href="https://plugins.jetbrains.com/plugin/7749-servicestack">
              <div class="inline-flex justify-center">
                <img src="/img/pages/svg/androidstudio.svg" class="w-20 h-20">
              </div>
              <h3>Android Studio</h3>
            </a>
            <h4>Languages Supported</h4>
            <p class="italic">
              Java, Kotlin, TypeScript
            </p>
          </div>
          <div class="w-full lg:w-1/4 mt-4">
            <a href="https://marketplace.eclipse.org/content/servicestackeclipse">
              <div class="inline-flex justify-center">
                <img src="/img/pages/svg/ides/eclipse-11.svg" height="4em" alt="" style="width:70px;height:70px;">
              </div>
              <h3>Eclipse</h3>
            </a>
            <h4>Languages Supported</h4>
            <p class="italic">
              Java
            </p>
          </div>
        </div>
    </div>
</section>

Support for all languages are implemented the same way where the generated DTOs can be used with idiomatic [generic Service Clients](#servicestack-clients) giving developers a consistent way of creating and updating your DTOs regardless of your language of choice.

### Command-line Tooling

The [x dotnet tool](/dotnet-tool) also allows us to generate these native service references from the command-line with the format `x <lang> <url>`, e.g. we can create C# DTOs for our App with:

:::sh
`x csharp https://localhost:5001`
:::

Output:

```
Saved to: dtos.ts
```

Or create a TypeScript ServiceStack Reference with:

:::sh
`x typescript https://localhost:5001`
:::

### Updating a ServiceStack Reference

To Update an existing ServiceStack Reference, call `x typescript` with the Filename, e.g:

:::sh
x typescript dtos.ts
:::

Result:

```
Updated: dtos.ts
```

This will update the File with your App's latest TypeScript Server DTOs. DTO customizations are also available by uncommenting the [TypeScript DTO Customization Options](/typescript-add-servicestack-reference#dto-customization-options) and updating them again.

#### Updating all DTOs

Calling `x typescript` without any arguments will update **all TypeScript DTOs** in the current directory:

:::sh
x typescript
:::


Other available languages include:

<table class="table table-bordered">
<tr>
    <th>Script</th>
    <th>Alias</th>
    <th>Language</th>
</tr>
<tr>
    <td>x csharp</td>
    <td>x cs</td>
    <td>C#</td>
</tr>
<tr>
    <td>x typescript</td>
    <td>x ts</td>
    <td>TypeScript</td>
</tr>
<tr>
    <td>x python</td>
    <td>x py</td>
    <td>Python</td>
</tr>
<tr>
    <td>x java</td>
    <td></td>
    <td>Java</td>
</tr>
<tr>
    <td>x kotlin</td>
    <td>x kt</td>
    <td>Kotlin</td>
</tr>
<tr>
    <td>x swift</td>
    <td></td>
    <td>Swift</td>
</tr>
<tr>
    <td>x dart</td>
    <td></td>
    <td>Dart</td>
</tr>
<tr>
    <td>x vbnet</td>
    <td>x vb</td>
    <td>VB.NET</td>
</tr>
<tr>
    <td>x fsharp</td>
    <td>x fs</td>
    <td>F#</td>
</tr>
</table>

### ServiceStack Clients

To enable its clean end-to-end typed API development model, the generated DTOs can be used with a generic Service Client available for each supported language:

  * [C#/.NET Client](/csharp-client)
  * [TypeScript Client](/typescript-add-servicestack-reference)
  * [Kotlin Client](/kotlin-add-servicestack-reference)
  * [Java Client](/java-add-servicestack-reference)
  * [Swift Client](/swift-add-servicestack-reference)
  * [Dart Client](/dart-add-servicestack-reference#example-usage)
  * [JavaScript Client](/javascript-client)
  * [MQ Clients](/redis-mq)

### Supported Languages

This [Add ServiceStack Reference](/add-servicestack-reference) feature is available for all the popular supported languages below:

<table class="table table-bordered w-full" style="text-align:center">
    <tr>
        <td><a href="/csharp-add-servicestack-reference">C#</a></td>
        <td><a href="/typescript-add-servicestack-reference">TypeScript</a></td>
        <td><a href="/javascript-add-servicestack-reference">JavaScript</a></td>
        <td><a href="/python-add-servicestack-reference">Python</a></td>
        <td><a href="/swift-add-servicestack-reference">Swift</a></td>
        <td><a href="/java-add-servicestack-reference">Java</a></td>
        <td><a href="/kotlin-add-servicestack-reference">Kotlin</a></td>
        <td><a href="/dart-add-servicestack-reference">Dart</a></td>
        <td><a href="/fsharp-add-servicestack-reference">F#</a></td>
        <td><a href="/vbnet-add-servicestack-reference">VB.NET</a></td>
    </tr>
</table>

![](./img/pages/add-ss-ref.svg)

## Development workflow preview

Here's quick walkthrough's installing the **ServiceStack** plugin and using it to add remote ServiceStack References in a new C# App:

<lite-youtube class="w-full mx-4 my-4" width="560" height="315" videoid="JKsgrstNnYY" style="background-image: url('https://img.youtube.com/vi/JKsgrstNnYY/maxresdefault.jpg')"></lite-youtube>

:::tip
VSCode and other IDEs will be able to use the command-line tool for adding and updating multiple Services references.
:::

### C# Xamarin.Android Example in VS.NET

Using C# to develop native Mobile and Desktop Apps provides a number of benefits including maximum reuse of your investments across multiple Client Apps where they're able to reuse shared functionality, libraries, knowledge, development workflow and environment in both Client and Server Apps. 

<lite-youtube class="w-full mx-4 my-4" width="560" height="315" videoid="cbYuem1b2tg" style="background-image: url('https://img.youtube.com/vi/cbYuem1b2tg/maxresdefault.jpg')"></lite-youtube>

### Call ServiceStack APIs from a Flutter App with native Dart client and DTOs

Walk through showing how you can use ServiceStack's Dart client library with your Flutter Android application to quickly get up and running with Add ServiceStack Reference.

<lite-youtube class="w-full mx-4 my-4" width="560" height="315" videoid="ocH5L-CikQ0" style="background-image: url('https://img.youtube.com/vi/ocH5L-CikQ0/maxresdefault.jpg')"></lite-youtube>

### Call ServiceStack APIs from Python

This video tutorial looks at how we can leverage Add ServiceStack Reference for Python in PyCharm, VSCode and [Python Jupyter Notebooks](/jupyter-notebooks-python).

<lite-youtube class="w-full mx-4 my-4" width="560" height="315" videoid="WjbhfH45i5k" style="background-image: url('https://img.youtube.com/vi/WjbhfH45i5k/maxresdefault.jpg')"></lite-youtube>

### Instant Client Apps

[Instant Client Apps](https://apps.servicestack.net/) is a free tool to jump start your native client application development using a wide range of languages and platforms including: C#, NodeJS, Dart, Java, Kotlin, Swift, VB .NET and F#:

<lite-youtube class="w-full mx-4 my-4" width="560" height="315" videoid="GTnuMhvUayg" style="background-image: url('https://img.youtube.com/vi/GTnuMhvUayg/maxresdefault.jpg')"></lite-youtube>

## gRPC

[ServiceStack gRPC](/grpc/) enables a highly productive development environment for developing high-performance gRPC HTTP/2 Services by making ServiceStack's existing typed Services available from ASP.NET's gRPC endpoints where ServiceStack offers a simplified development model for gRPC Clients for streamlined end-to-end productivity.

<lite-youtube class="w-full mx-4 my-4" width="560" height="315" videoid="UQlYodNS1xc" style="background-image: url('https://img.youtube.com/vi/UQlYodNS1xc/maxresdefault.jpg')"></lite-youtube>

## C# Mobile and Desktop Apps

[![](https://raw.githubusercontent.com/ServiceStackApps/HelloMobile/master/screenshots/splash-900.png)](https://github.com/ServiceStackApps/HelloMobile)

The generated DTOs provides a highly productive development workflow and enables a succinct end-to-end Typed API that can be used in both **.NET Framework** and **.NET Standard 2.0** [Generic Service Clients](/csharp-client) to facilitate Rapid Development in .NET's most popular Mobile and Desktop platforms:

 - WPF
 - UWP
 - Xamarin.Android
 - Xamarin.iOS
 - Xamarin.OSX
 - Xamarin.Forms
   - iOS
   - Android
   - UWP

The [HelloMobile](https://github.com/ServiceStackApps/HelloMobile) project contains multiple versions of the same App in all the above platforms demonstrating a number of different calling conventions, service integrations and reuse possibilities.

ServiceStack also allows for the maximum reuse possible by letting you reuse the same POCO DTOs used to define the Services contract with, in Clients Apps to provide its end-to-end typed API without any additional custom build tools, code-gen or any other artificial machinery, using just the DTOs in the shared `ServiceModel.dll` with any of the available highly performant [.NET generic Service Clients](/csharp-client) that be design encourages development of [resilient message-based Services](/what-is-a-message-based-web-service) for enabling [highly decoupled](/service-gateway) and easily [substitutable and mockable](/csharp-client#built-in-clients) Service Integrations.


### .NET Clients Message-based API

There are multiple C# service clients included, each optimized for their respective formats:

![ServiceStack HTTP Client Architecture](/img/pages/overview/servicestack-httpclients.png) 

- [JSON Client](https://github.com/ServiceStack/ServiceStack/blob/master/src/ServiceStack.Client/JsonServiceClient.cs)
- [XML Client](https://github.com/ServiceStack/ServiceStack/blob/master/src/ServiceStack.Client/XmlServiceClient.cs)
- [JSV Client](https://github.com/ServiceStack/ServiceStack/blob/master/src/ServiceStack.Client/JsvServiceClient.cs)
- [SOAP 1.1/1.2 Clients](https://github.com/ServiceStack/ServiceStack/blob/master/src/ServiceStack.Client/Soap12ServiceClient.cs)
- [ProtoBuf Client](https://github.com/ServiceStack/ServiceStack/blob/master/src/ServiceStack.ProtoBuf/ProtoBufServiceClient.cs)

All clients share the same [IServiceClient](https://github.com/ServiceStack/ServiceStack/blob/master/src/ServiceStack.Interfaces/IServiceClient.cs) and [IServiceClientAsync](https://github.com/ServiceStack/ServiceStack/blob/master/src/ServiceStack.Interfaces/IServiceClientAsync.cs) so they're easily swappable at runtime, and is what allows the same Unit test to be re-used as within an [Xml, JSON, JSV, SOAP Integration test](https://github.com/ServiceStack/ServiceStack/blob/master/tests/ServiceStack.WebHost.IntegrationTests/Tests/WebServicesTests.cs). The JSON, XML and JSV clients also share [IRestClient](https://github.com/ServiceStack/ServiceStack/blob/master/src/ServiceStack.Interfaces/IRestClient.cs) and [IRestClientAsync](https://github.com/ServiceStack/ServiceStack/blob/master/src/ServiceStack.Interfaces/IRestClientAsync.cs)

## What's the best way to expose our services to clients today?

### Native language client libraries

A productive option for clients (and the recommended approach by ServiceStack) would be to provide a native client library for each of the popular languages you wish to support. This is the approach of companies who really, really want to help you use their services like Amazon, Facebook and Windows Azure. This is an especially good idea if you want to support static languages (i.e. C# and Java) where having typed client libraries saves end-users from reverse engineering the types and API calls. It also saves them having to look up documentation since a lot of it can be inferred from the type info. ServiceStack's and Amazons convention of having `ServiceName` and `ServiceNameResponse` for each service also saves users from continually checking documentation to work out what the response of each service will be.

### Packaging client libraries

In terms of packaging your client libraries, sticking a link to a zip file on your Websites APIs documentation page would be the easiest approach. If the zip file was a link to a master archive of a Github repository, that would be better as you'll be able to accept bug fixes and usability tips from the community. Finally we believe the best way to make your client libraries available would be to host them in the target languages native package manager - letting end-users issue 1-command to automatically add it to their project, and another to easily update it when your service has changed.

### Using NuGet

For .NET this means adding it to NuGet, and if you use ServiceStack your package would just need to contain your types with a reference to [ServiceStack.Client](http://nuget.org/packages/ServiceStack.Client). One of the benefits of using ServiceStack is that all your types are already created since it's what you used to define your web services with!


# Community Resources

  - [Servicestack and PHP](http://www.majorsilence.com/servicestack_and_php) by [@majorsilence](https://github.com/majorsilence)


# C#/.NET Service Clients
Source: https://docs.servicestack.net/csharp-client

Using DTOs to define your web service interface makes it possible to provide strong-typed generic service clients without any code-gen or extra build-steps, leading to a productive end-to-end type-safe communication gateway from client to server.

<lite-youtube class="w-full mx-4 my-4" width="560" height="315" videoid="cbYuem1b2tg" style="background-image: url('https://img.youtube.com/vi/cbYuem1b2tg/maxresdefault.jpg')"></lite-youtube>

 **ServiceStack.Client** is the primary NuGet package containing ServiceStack's client libraries that can be included in your `.csproj` with:

:::copy
`<PackageReference Include="ServiceStack.Client" Version="8.*" />`
:::

Earlier **.NET 6.0** can use the [HttpClient-based JsonHttpClient](/csharp-client#jsonhttpclient) in:

:::copy
`<PackageReference Include="ServiceStack.HttpClient" Version="8.*" />`
:::

### JsonApiClient

From  **.NET 6+** it's recommended to use the newest [JsonApiClient](/releases/v6#jsonapiclient) released in v6+:

```csharp
var client = new JsonApiClient(baseUri);
```

### HttpClient Factory Registration

In client Apps that support it, the recommendation is to use a HttpClient Factory which can be done to register the `JsonApiClient` dependency in your App with:

```csharp
builder.Services.AddJsonApiClient(builder.Configuration["BaseUrl"]);
```

It's now recommended to use `JsonApiClient` when it's available, but for simplification the docs will continue to reference the substitutable & more broadly available `JsonServiceClient`.

#### Blazor Client Registration

**Blazor WASM** should instead use the tailored `AddBlazorApiClient()` which also configures a CORS-enabled typed `JsonApiClient`:

```csharp
builder.Services.AddBlazorApiClient(builder.Configuration["ApiBaseUrl"] ?? builder.HostEnvironment.BaseAddress);
```

### Setup

All ServiceStack's C# clients share the same interfaces and are created by passing in the **Base URI** of your ServiceStack service in the clients constructor, e.g. if your ServiceStack instance was hosted on the root path `/` on the **5001** custom port:

```csharp
var client = new JsonApiClient("https://host:5001");
```

Or if hosted on the `/custom` custom path:

```csharp
var client = new JsonApiClient("https://host/custom/");
```

### Recommended ServiceClient for .NET 6+#

Going forward we'll continue improving `JsonApiClient` with new .NET runtime features and optimizations as they're available and now that .NET's `HttpWebRequest` has been officially **deprecated in .NET 6+** we recommend switching to use `JsonApiClient` in .NET 6+ runtimes.

### Safe Sync HttpClient APIs

Until adding **net6.0** TFM builds there was no officially supported way to perform synchronous requests with `HttpClient`, to implement the complete `IServiceClient` interface, `JsonHttpClient` had to adopt the least problematic sync-over-async solution.

`JsonApiClient` improves its synchronous support by rewriting all Sync methods to use HttpClient's new blocking `Send()` method. Whilst Blocking I/O continues to impact scalability, it's nice to finally have an officially supported safe method to use free from deadlock concerns.

## High level `Api` and `ApiAsync` methods

.NET was originally conceived to use Exceptions for error control flow however there's been a tendency in modern languages & libraries to shun Exceptions and return errors as normal values, an approach we believe is a more flexible & ergonomic way to handle API responses.

### The ApiResult way

The new APIs simply returns a typed `ApiResult<Response>` Value Result that encapsulates either a Typed Response or a structured API Error populated in `ResponseStatus` allowing you to handle API responses programmatically without `try/catch` handling:

```csharp
var api = client.Api(new Hello { Name = name });
if (api.Failed) 
    Console.WriteLine($"Greeting failed! {api.Error.ErrorMessage}");
else
    Console.WriteLine($"API Says: {api.Response.Result}"); //api.Succeeded
```

### C# Example

A preview of what this looks like is visible in [Blazor WASMs Dev Model Preview](/templates/blazor-bootstrap#api-and-apiasync-methods) example code to create a new Booking:

```csharp
CreateBooking request = new();

ApiResult<IdResponse> api = new();

async Task OnSubmit()
{
    api = await Client.ApiAsync(request);

    if (api.Succeeded)
    {
        await done.InvokeAsync(api.Response!);
        request = new();
    }
}
```

Which despite its terseness handles both **success** and **error** API responses, **if successful** it invokes the `done()` callback notifying its parent of the new Booking API Response before resetting the Form's data model with a new Request DTO.

Upon **failure** the error response is populated in `api.Error` which binds to the UI via Blazor's `<CascadingValue Value=@api.Error>` to propagate it to all its child components in order to show contextual validation errors next to their respective Input controls.


### Available in all .NET and TypeScript Clients

The new `Api` and `ApiAsync` methods is available in all .NET Service Clients, including [Service Gateway's](/service-gateway).

## REST API

In addition, the Service Clients provide HTTP verbs (Get, Post & PostFile, Put, Delete, Patch, etc) enabling a productive typed API for consuming ServiceStack Services with their best matching Custom Routes as seen in the examples below:

> See [IServiceClient](https://github.com/ServiceStack/ServiceStack/blob/master/src/ServiceStack.Interfaces/IServiceClient.cs) for the full API available

### Using the recommended [API Design](/api-design)

```csharp
HelloResponse response = client.Get(new Hello { Name = "World!" });
response.Result.Print();
```

#### Async Example

Using C# `await`:

```csharp
HelloResponse response = await client.GetAsync(
    new Hello { Name = "World!" });
```

### Alternative API

```csharp
var response = client.Get<HelloResponse>("/hello/World!");
response.Result.Print();
```

#### Async Example

```csharp
var response = await client.GetAsync<HelloResponse>("/hello/World!");
```

## Service Client API

C#/.NET Clients can call the above Hello Service using any of the JSON, JSV, XML or SOAP Service Clients with the code below:

### Using the recommended [API Design](/api-design)

```csharp
var response = client.Send(new Hello { Name = "World!" });
response.Result.Print();
```

#### Async Example

```csharp
var response = await client.SendAsync(new Hello { Name = "World!" });
response.Result.Print();
```

### Alternative API

```csharp
var response = client.Send<HelloResponse>(new Hello { Name = "World!" });
response.Result.Print();
```

#### Async Example

```csharp
var response = await client.SendAsync<HelloResponse>(
    new Hello { Name = "World!" });
```

The service clients use the automatic [pre-defined routes](/endpoints) for each service.

### File Upload with Request

The `PostFileWithRequest*` methods can be used to upload a file with an API Request.

Here's an example calling [AI Server's](/ai-server/) `SpeechToText` API:

### C# Speech to Text

```csharp
using var fsAudio = File.OpenRead("audio.wav");
var response = client.PostFileWithRequest(new SpeechToText(),
    new UploadFile("audio.wav", fsAudio, "audio"));
```

### Multiple File Uploads

Whilst the `PostFilesWithRequest*` methods can be used to upload multiple files with an API Request, e.g:

### C# Watermark Video

```csharp
using var fsVideo = File.OpenRead("video.mp4");
using var fsWatermark = File.OpenRead("watermark.png");
var response = client.PostFilesWithRequest(new QueueWatermarkVideo {
        Position = WatermarkPosition.BottomRight
    }, [
        new UploadFile("video.mp4", fsVideo, "video"),
        new UploadFile("watermark.png", fsWatermark, "watermark")
    ]);
```


<a name="native-responses"></a>

### [Cache Aware Service Clients](/cache-aware-clients)

When [caching is enabled on Services](/http-caching), the Cache-aware Service Clients can dramatically improve performance by eliminating server requests entirely as well as reducing bandwidth for re-validated requests. They also offer an additional layer of resiliency as re-validated requests that result in Errors will transparently fallback to using pre-existing locally cached responses. For bandwidth-constrained environments like Mobile Apps they can dramatically improve the User Experience.

The Cache-Aware clients implement the full `IServiceClient` interface so they should be an easy drop-in enhancement for existing Apps:

```csharp
IServiceClient client = new JsonServiceClient(baseUrl).WithCache(); 

//equivalent to:
IServiceClient client = new CachedServiceClient(new JsonServiceClient(baseUrl));
```

Likewise for the HttpClient-based `JsonHttpClient`:

```csharp
IServiceClient client = new JsonHttpClient(baseUrl).WithCache(); 

//equivalent to:
IServiceClient client = new CachedHttpClient(new JsonHttpClient(baseUrl));
```

## Support for Native built-in Response Types

All of ServiceStack's generic Service Clients also allow you to fetch raw `string`, `byte[]` and `Stream` responses of any existing service, or when you need it, the underlying `HttpWebResponse` allowing fine-grained access to the HTTP Response. e.g With just the Service below:

```csharp
[Route("/poco/{Text}")]
public class Poco : IReturn<PocoResponse>
{
    public string Text { get; set; }
}

public class PocoResponse
{
    public string Result { get; set; }
}

public class NativeTypesExamples : Service
{
    public PocoResponse Any(Poco request)
    {
        base.Response.AddHeader("X-Response", request.Text);
        return new PocoResponse { 
            Result = "Hello, " + (request.Text ?? "World!") 
        };
    }
}
```

You can access it normally with the typed API:

```csharp
PocoResponse response = client.Get(new Poco { Text = "World" });
response.Result //Hello, World
```

Or as get the JSON as a raw string:

```csharp
string responseJson = client.Get<string>("/poco/World");
var dto = responseJson.FromJson<PocoResponse>();
dto.Result //Hello, World
```

Or as raw bytes:

```csharp
byte[] responseBytes = client.Get<byte[]>("/poco/World");
var dto = responseBytes.FromUtf8Bytes().FromJson<PocoResponse>();
dto.Result //Hello, World
```

Or as a Stream:

```csharp
using Stream responseStream = client.Get<Stream>("/poco/World");
var dto = responseStream.ReadFully()
    .FromUtf8Bytes()
    .FromJson<PocoResponse>();
dto.Result //Hello, World
```

Async download & write to file example:

```csharp
using var stream = await client.GetAsync<Stream>(new GetFile { Path = "/path/to/file.png" });
using var fs = File.Create(Path.Combine(uploadsDir, "file.png"));
await stream.CopyToAsync(fs);
```

Or even access the populated `HttpWebResponse` object:

```csharp
HttpWebResponse webResponse = client.Get<HttpWebResponse>("/poco/World");

webResponse.Headers["X-Response"] //= World

using var stream = webResponse.GetResponseStream();
using var sr = new StreamReader(stream);
var dto = sr.ReadToEnd().FromJson<PocoResponse>();
dto.Result //Hello, World
```

### Accessing raw service responses

ServiceStack isn't limited to just returning POCO's as you can effectively [return anything you want](/service-return-types) even images 
[/helloimage/ServiceStack?Width=600&height=300&Foreground=Yellow](https://test.servicestack.net/image-draw/ServiceStack?Width=600&height=300&Foreground=Yellow). These native responses can also be mark on your Request DTO `IReturn<T>` interface marker to give you a terse end-to-end API for fetching raw responses, e.g:

```csharp
[Route("/headers/{Text}")]
public class Headers : IReturn<HttpWebResponse>
{
    public string Text { get; set; }
}

[Route("/strings/{Text}")]
public class Strings : IReturn<string>
{
    public string Text { get; set; }
}

[Route("/bytes/{Text}")]
public class Bytes : IReturn<byte[]>
{
    public string Text { get; set; }
}

[Route("/streams/{Text}")]
public class Streams : IReturn<Stream>
{
    public string Text { get; set; }
}

public class BuiltInTypesService : Service
{
    public void Any(Headers request)
    {
        base.Response.AddHeader("X-Response", request.Text);
    }

    public string Any(Strings request)
    {
        return "Hello, " + (request.Text ?? "World!");
    }

    public byte[] Any(Bytes request)
    {
        return new Guid(request.Text).ToByteArray();
    }

    public byte[] Any(Streams request)
    {
        return new Guid(request.Text).ToByteArray();
    }        
}
```

### Accessing client raw responses

Which let you access the results as you would a normal response:

```csharp
using HttpWebResponse response = client.Get(new Headers { Text = "World" });
response.Headers["X-Response"] // "World"

string response = client.Get(new Strings { Text = "World" });
response // Hello, World

byte[] response = client.Get(new Bytes { 
    Text = Guid.NewGuid().ToString() 
});
var guid = new Guid(response);

using Stream stream = client.Get(new Streams { Text = Guid.NewGuid().ToString() });
var guid = new Guid(response.ReadFully());
```

All these APIs are also available asynchronously as well:

```csharp
using HttpWebResponse response = await client.GetAsync(
    new Strings { Text = "Test" });
response.Headers["X-Response"] // "World"

string response = await client.GetAsync(
    new Strings { Text = "World" });
response // Hello, World

byte[] response = await client.GetAsync(new Bytes { 
    Text = Guid.NewGuid().ToString() 
});
var guid = new Guid(response);

using Stream stream = await client.GetAsync(new Streams { 
    Text = Guid.NewGuid().ToString() 
});
var guid = new Guid(response.ReadFully());
```

::: warning
You must explicitly dispose all APIs returning either `HttpWebResponse` or `Stream` as seen in the above examples.
:::

They all behave the same as the sync versions except for `HttpWebResponse` which gets returned just after
the request is sent (asynchronously) and before any response is read so you can still access the HTTP Headers e.g:

```csharp
var client = new JsonServiceClient("http://localhost:2020/") 
{
    ResponseFilter = httpRes => {
        var header = httpRes.Headers["X-Response"];
    }
};
var response = await client.GetAsync(new Headers { Text = "World" });
```

Which makes a great starting point if you want to stream the responses back asynchronously as seen in this
[Reactive ServiceStack example](https://gist.github.com/bamboo/5078236) by [@rodrigobamboo](https://twitter.com/rodrigobamboo).

More examples can be found in the ServiceClients [Built-in native type response tests](https://github.com/ServiceStack/ServiceStack/blob/master/tests/ServiceStack.WebHost.Endpoints.Tests/ServiceClientsBuiltInResponseTests.cs)

## Sending Raw Data

.NET Service Clients can also send raw `string`, `byte[]` or `Stream` Request bodies in their custom Sync or Async API's, e.g:
 
```csharp
string json = "{\"Key\":1}";
client.Post<SendRawResponse>("/sendraw", json);

byte[] bytes = json.ToUtf8Bytes();
client.Put<SendRawResponse>("/sendraw", bytes);

Stream stream = new MemoryStream(bytes);
await client.PostAsync<SendRawResponse>("/sendraw", stream);
```

### Sending Typed Request with Raw Body

The `*Body` and `*BodyAsync` APIs have avaialble in all Service Clients lets you post a separate Request Body for Request DTOs 
that implement `IRequiresRequestStream` where they contain both properties and a custom Request Body, e.g:

```csharp
[Route("/json")]
public class SendJson : IRequiresRequestStream, IReturn<string>
{
    public string Name { get; set; }
    public Stream RequestStream { get; set; }
}

[Route("/text")]
public class SendText : IRequiresRequestStream, IReturn<string>
{
    public string Name { get; set; }
    public string ContentType { get; set; }
    public Stream RequestStream { get; set; }
}

public class SendRawService : Service
{
    [JsonOnly]
    public object Any(SendJson request) => request.RequestStream.ReadFully();

    public object Any(SendText request)
    {
        base.Request.ResponseContentType = request.ContentType ?? base.Request.AcceptTypes[0];
        return request.RequestStream.ReadFully();
    }
}
```

The new APIs accept both a Request DTO which specifies which Service to call and what properties to add to the QueryString and another
object to send in the raw HTTP Request Body, e.g:

```csharp
var client = new JsonServiceClient(BaseUrl);

var json = client.PostBody(new SendJson { Name = "JSON body" }, new PocoRequest { Foo = "Bar" });
json.FromJson<PocoRequest>().Foo //= Bar

json = await client.PutBodyAsync(new SendJson { Name = "JSON body" }, "{\"Foo\":\"Bar\"}");
json.FromJson<PocoRequest>().Foo //= Bar

var client = new JsonHttpClient(BaseUrl);
var request = new SendText { Name = "Text body", ContentType = "text/plain" };

var text = await client.PostBodyAsync(request, "foo");
text //= foo
```

## Client / Server Request Compression

You can  elect to compress HTTP Requests in any C#/.NET Service Clients by specifying the Compression 
Type you wish to use, e.g:

```csharp
var client = new JsonServiceClient(baseUrl) {
    RequestCompressionType = CompressionTypes.GZip,
};

var client = new JsonHttpClient(baseUrl) {
    RequestCompressionType = CompressionTypes.Deflate,
};

var response = client.Post(new Request { ... });
```

Where sending any HTTP Request containing a Request Body (e.g. POST/PUT) will send a compressed Request body
to the Server where it's now able to be transparently decompressed and deserialized into your Request DTO.

## Authentication

ServiceStack's [Auth Tests](https://github.com/ServiceStack/ServiceStack/blob/master/tests/ServiceStack.WebHost.Endpoints.Tests/AuthTests.cs#L108) shows different ways of authenticating when using the C# Service Clients. By default BasicAuth and DigestAuth is built into the clients, e.g:

```csharp
var client = new JsonServiceClient(baseUri) {
    UserName = UserName,
    Password = Password,
};

var request = new Secured { Name = "test" };
var response = client.Send<SecureResponse>(request);    
```

Behind the scenes ServiceStack will attempt to send the request normally but when the request is rejected and challenged by the Server the clients will automatically retry the same request but this time with the Basic/Digest Auth headers.

To skip the extra hop when you know you're accessing a secure service, you can tell the clients to always send the BasicAuth header with:

```csharp
client.AlwaysSendBasicAuthHeader = true;
```

### Sending Authenticate Request DTO

The alternative way to Authenticate is to make an explicit call to the `Authenticate` service (this requires `CredentialsAuthProvider` enabled) e.g:

```csharp
AuthenticateResponse authResponse = client.Post(new Authenticate {
    provider = CredentialsAuthProvider.Name, //= credentials
    UserName = "user",
    Password = "p@55word",
    RememberMe = true,                       //important tell client to retain permanent cookies
});

var request = new Secured { Name = "test" };
var response = client.Send<SecureResponse>(request);    
```

After a successful call to the `Authenticate` service the client is Authenticated and if **RememberMe** is set, the client will retain the Session Cookies added by the Server on subsequent requests which is what enables future requests from that client to be authenticated.

### Request and Response Filters

When needing to execute custom logic before and after requests are sent and received you can use Global Request/Response Filters:

```csharp
// Executed for all .NET HttpWebRequest ServiceClient instances like JsonServiceClient:
ServiceClientBase.GlobalRequestFilter = (HttpWebRequest req) => { ... };
ServiceClientBase.GlobalResponseFilter = (HttpWebResponse res) => { ... };

// Executed for all JsonHttpClient instances
JsonHttpClient.GlobalRequestFilter = (HttpRequestMessage req) => { ... };
JsonHttpClient.GlobalResponseFilter = (HttpResponseMessage res) => { ... };
```

Or use instance Request/Response Filters if you only want to run custom logic for a specific instances:

```csharp
var client = new JsonServiceClient(baseUrl) {
    RequestFilter = req => { ... },
    ResponseFilter = res => { ... },
}

var client = new JsonHttpClient(baseUrl) {
    RequestFilter = req => { ... },
    ResponseFilter = res => { ... },
}
```

### Upload and Download Progress on Async API's

The Async API's support on progress updates with the `OnDownloadProgress` and `OnUploadProgress` callbacks which can be used to provide UX Progress updates, e.g:

```csharp
var client = new JsonServiceClient(ListeningOn);

//Available in ASP.NET/HttpListener when downloading responses with known lengths 
//E.g: Strings, Files, etc.
client.OnDownloadProgress = (done, total) =>
    "{0}/{1} bytes downloaded".Print(done, total);

var response = await client.GetAsync(new Request());
```

::: info
total = -1 when 'Transfer-Encoding: chunked'
:::

Whilst the `OnUploadProgress` callback gets fired when uploading files, e.g:

```csharp
client.OnUploadProgress = (bytesWritten, total) => 
    "Written {0}/{1} bytes...".Print(bytesWritten, total);

client.PostFileWithRequest<UploadResponse>(url, 
    new FileInfo(path), new Upload { CreatedBy = "Me" });
```

### Custom Client Caching Strategy

The `ResultsFilter` and `ResultsFilterResponse` delegates on Service Clients can be used to enable a custom caching strategy. 

Here's a basic example implementing a cache for all **GET** Requests:

```csharp
var cache = new Dictionary<string, object>();

client.ResultsFilter = (type, method, uri, request) => {
    if (method != HttpMethods.Get) return null;
    object cachedResponse;
    cache.TryGetValue(uri, out cachedResponse);
    return cachedResponse;
};
client.ResultsFilterResponse = (webRes, response, method, uri, request) => {
    if (method != HttpMethods.Get) return;
    cache[uri] = response;
};

//Subsequent requests returns cached result
var response1 = client.Get(new GetCustomer { CustomerId = 5 });
var response2 = client.Get(new GetCustomer { CustomerId = 5 }); //cached response
```

The `ResultsFilter` delegate is executed with the context of the request before the request is made. Returning a value of type `TResponse` short-circuits the request and returns that response. Otherwise the request continues and its response passed into the `ResultsFilterResponse` delegate where it can be cached. 

### Implicitly populate SessionId and Version Number

Service Clients can be used to auto-populate Request DTO's implementing `IHasSessionId` or `IHasVersion` by assigning the `Version` and `SessionId` properties on the Service Client, e.g:

```csharp
client.Version = 1;
client.SessionId = authResponse.SessionId;
```

Which populates the SessionId and Version number on each Request DTO's that implementing the specific interfaces, e.g:

```csharp
public class Hello : IReturn<HelloResponse>, IHasSessionId, IHasVersion {
    public int Version { get; set; }
    public string SessionId { get; set; }
    public string Name { get; set; }
}

client.Get(new Hello { Name = "World" }); //Auto populates Version and SessionId
```

### HTTP Verb Interface Markers

You can decorate your Request DTO's using the `IGet`, `IPost`, `IPut`, `IDelete` and `IPatch` interface markers and the `Send` and  `SendAsync` API's will use it to automatically send the Request using the selected HTTP Method. E.g:

```csharp
public class HelloByGet : IGet, IReturn<HelloResponse>
{
    public string Name { get; set; }
}
public class HelloByPut : IPut, IReturn<HelloResponse> 
{
    public string Name { get; set; }
}

var response = client.Send(new HelloByGet { Name = "World" }); //GET

await client.SendAsync(new HelloByPut { Name = "World" }); //PUT
```

Interface markers is supported in all .NET Service Clients, they're also included in the generated 
[Add ServiceStack Reference](/add-servicestack-reference) DTO's so they're also available in the
[Java JsonServiceClient](/java-add-servicestack-reference) and
[Swift JsonServiceClient](/swift-add-servicestack-reference). It's also available in our 3rd Party [StripeGateway](https://github.com/ServiceStack/Stripe).

Whilst a simple feature, it enables treating your remote services as a message-based API 
[yielding its many inherent advantages](/advantages-of-message-based-web-services#advantages-of-message-based-designs) 
where your Application API's need only pass Request DTO models around to be able to invoke remote Services, decoupling the Service Request from its implementation which can be now easily managed by a high-level adapter that takes care of proxying the Request to the underlying Service Client. The adapter could also add high-level functionality of it's own including auto retrying of failed requests, generic error handling, logging/telemetrics, event notification, throttling, offline queuing/syncing, etc.

## File Uploads

File uploads can be accessed within Service implementations from the `Request.Files` collection which you can write to the registered
[Writable Virtual Files Provider](/virtual-file-system) with:

```csharp
[Route("/files/upload")]
public class UploadFile {}

public class UploadFileService : Service
{
    readonly string UploadsDir = "uploads";

    public object Post(UploadFile request)
    {
        var uploadedFile = base.Request.Files[0];
        VirtualFiles.WriteFile(UploadsDir.CombineWith(uploadedFile.FileName), uploadedFile.InputStream);
        return new FileUploadResponse { ... };
    }
}
```

Alternatively [Managed File Uploads](/locode/files-overview) can provide a more effortless solution for configuring custom validation, multiple upload locations
and also includes File APIs to access & manage file uploads.

### Uploading File with Request

The Service Clients utilize standard [HTTP multipart/form-data](https://www.ietf.org/rfc/rfc2388.txt) Content-Type for 
uploading files as demonstrated in Talent Blazor's
[FileUploadTests.cs](https://github.com/NetCoreApps/TalentBlazor/blob/main/TalentBlazor.Tests/FileUploadTests.cs)
which uploads a single attachment when creating a Contact with a Profile Image and multiple file attachments when
submitting a Job Application:

```csharp
var profileImg = await ProfileImageUrl.GetStreamFromUrlAsync();
var contact = await client.PostFileWithRequestAsync<Contact>(profileImg, "cody-fisher.png", 
    new CreateContact
    {
        FirstName = "Cody",
        LastName = "Fisher",
        Email = "cody.fisher@gmail.com",
        JobType = "Security",
        PreferredLocation = "Remote",
        PreferredWorkType = EmploymentType.FullTime,
        AvailabilityWeeks = 1,
        SalaryExpectation = 100_000,
        About = "Lead Security Associate",
    }, fieldName:nameof(CreateContact.ProfileUrl));

// contact.ProfileUrl = /profiles/cody-fisher.png

var uploadedImage = await client.BaseUri.CombineWith(contact.ProfileUrl).GetStreamFromUrlAsync();
var coverLetter = new FileInfo($"{AppData}/sample_coverletter.pdf");
var resume = new FileInfo($"{AppData}/sample_resume.pdf");

var attachmentsField = nameof(CreateJobApplication.Attachments);
var uploadAttachments = new UploadFile[] {
    new(coverLetter.Name, coverLetter.OpenRead(), attachmentsField),
    new(resume.Name, coverLetter.OpenRead(), attachmentsField),
    new(contact.ProfileUrl.LastRightPart('/'), uploadedImage, attachmentsField),
};

var jobApp = await client.PostFilesWithRequestAsync<JobApplication>(new CreateJobApplication {
        JobId = 1,
        AppliedDate = DateTime.UtcNow,
        ContactId = contact.Id,
    }, uploadAttachments);

uploadAttachments.Each(x => x.Stream.Dispose());
```

This example also shows APIs are able to submit files from any `Stream` that can be sourced from anywhere,
including the HTTP Response stream of a Remote URI or files from a local hard drive. 

### Using HttpClient MultipartFormDataContent

The [.NET 6+ JsonApiClient](/csharp-client#jsonapiclient) lets us provide an even more flexible approach by utilizing 
`MultipartFormDataContent()` which we've enhanced with high-level extension methods to enable a Fluent API for constructing 
custom API Requests populated from multiple sources, which can be sent using its `ApiForm*` methods:

```csharp
var profileImg = await ProfileImageUrl.GetStreamFromUrlAsync();
using var createContact = new MultipartFormDataContent()
    .AddParams(new CreateContact
    {
        FirstName = "Cody",
        LastName = "Fisher",
        Email = "cody.fisher@gmail.com",
        JobType = "Security",
        PreferredLocation = "Remote",
        PreferredWorkType = EmploymentType.FullTime,
        AvailabilityWeeks = 1,
        SalaryExpectation = 100_000,
        About = "Lead Security Associate",
    })
    .AddFile(nameof(CreateContact.ProfileUrl), "cody-fisher.png", profileImg);

var contactApi = await client.ApiFormAsync<Contact>(typeof(CreateContact).ToApiUrl(), createContact);
// contactApi.Succeeded = true
var contact = contactApi.Response!;
// contact.ProfileUrl   = /profiles/cody-fisher.png

using var uploadedImage = await client.BaseUri.CombineWith(contact.ProfileUrl).GetStreamFromUrlAsync();
var coverLetter = new FileInfo($"{AppData}/sample_coverletter.pdf");
var resume = new FileInfo($"{AppData}/sample_resume.pdf");

var attachmentsField = nameof(CreateJobApplication.Attachments);
var createJobApp = new MultipartFormDataContent()
    .AddParams(new CreateJobApplication {
        JobId = 1,
        AppliedDate = DateTime.UtcNow,
        ContactId = contact.Id,
    })
    .AddFile(attachmentsField, coverLetter)
    .AddFile(attachmentsField, resume)
    .AddFile(attachmentsField, contact.ProfileUrl.LastRightPart('/'), uploadedImage);

var jobAppApi = await client.ApiFormAsync<JobApplication>(
    typeof(CreateJobApplication).ToApiUrl(), createJobApp);
// jobAppApi.Succeeded = true
var jobApp = jobAppApi.Response!;
```

::: tip
All `JsonApiClient` Async APIs also have 
[safe sync equivalents](/csharp-client#safe-sync-httpclient-apis) when access outside an async method is needed 
:::

### Upload a single File

You can use the `PostFile` API to upload a single File, with the Route of the Service you want to call,
the name of the file and the `Stream` of its contents, e.g:

```csharp
var client = new JsonServiceClient(baseUrl);
using var fileStream = new FileInfo(filePath).OpenRead();
var fileName = "upload.html";
var response = client.PostFile<FileUploadResponse>("/files/upload", 
    fileStream, fileName, MimeTypes.GetMimeType(fileName));
```

Files uploaded using the `PostFile*` APIs are uploaded as a HTTP POST using the `multipart/form-data` Content-Type which can 
be accessed from the `IRequest.Files` collection in your Services, e.g:

```csharp
[Route("/files/upload")]
public class UploadFile {}

public class UploadFileService : Service
{
    readonly string UploadsDir = "uploads";

    public object Post(UploadFile request)
    {
        var uploadedFile = base.Request.Files[0];
        VirtualFiles.WriteFile(UploadsDir.CombineWith(uploadedFile.FileName), uploadedFile.InputStream);
        return new FileUploadResponse { ... };
    }
}
```

You can use the `PostFileWithRequest` API To also include additional metadata with your File Upload, e.g:

```csharp
[DataContract]
[Route("/files/upload")]
public class FileUpload : IReturn<FileUploadResponse>
{
    [DataMember]
    public int CustomerId { get; set; }

    [DataMember]
    public DateTime CreatedDate { get; set; }
}

var client = new JsonApiClient(baseUrl);
var fileInfo = new FileInfo(filePath);
using var fileStream = fileInfo.OpenRead();
var request = new FileUpload {
    CustomerId = customerId,
    CreatedDate = fileInfo.CreationTimeUtc,
};

var response = client.PostFileWithRequest<FileUploadResponse>(
    "/files/upload", fileStream, fileInfo.Name, request);
```

### Multiple File Uploads

The `PostFilesWithRequest` APIs available in all .NET Service Clients allow you to easily upload multiple 
streams within a single HTTP request. It supports populating Request DTO with any combination of QueryString 
and POST'ed FormData in addition to multiple file upload data streams:

```csharp
using var stream1 = uploadFile1.OpenRead();
using var stream2 = uploadFile2.OpenRead();

var client = new JsonServiceClient(baseUrl);
var response = client.PostFilesWithRequest<MultipleFileUploadResponse>(
    "/multi-fileuploads?CustomerId=123",
    new MultipleFileUpload { CustomerName = "Foo,Bar" },
    new[] {
        new UploadFile("upload1.png", stream1),
        new UploadFile("upload2.png", stream2),
    });
```

Example using only a Typed Request DTO. The `JsonApiClient` also includes async equivalents for each of the 
`PostFilesWithRequest` APIs:

```csharp
using var stream1 = uploadFile1.OpenRead();
using var stream2 = uploadFile2.OpenRead();

var client = new JsonApiClient(baseUrl);
var response = await client.PostFilesWithRequestAsync<MultipleFileUploadResponse>(
    new MultipleFileUpload { CustomerId = 123, CustomerName = "Foo,Bar" },
    new[] {
        new UploadFile("upload1.png", stream1),
        new UploadFile("upload2.png", stream2),
    });
```

### Versatile Multi Part Content Type APIs

[AutoQueryCrudTests.References.cs](https://github.com/ServiceStack/ServiceStack/blob/main/ServiceStack/tests/ServiceStack.WebHost.Endpoints.Tests/AutoQueryCrudTests.References.cs)
showcases how we can take advantage of `MultipartFormDataContent` to construct custom requests using a combination
of different Content Type sources, including single and multiple file attachments within a single request:

```csharp
public class MultipartRequest : IPost, IReturn<MultipartRequest>
{
    public int Id { get; set; }
    public string String { get; set; }
    
    // Complex types sent as JSV by default
    public Contact Contact { get; set; }
    
    [MultiPartField(MimeTypes.Json)]
    public PhoneScreen PhoneScreen { get; set; }
    
    [MultiPartField(MimeTypes.Csv)]
    public List<Contact> Contacts { get; set; }
    
    [UploadTo("profiles")]
    public string ProfileUrl { get; set; }
    
    [UploadTo("applications")]
    public List<UploadedFile> UploadedFiles { get; set; } 
}
```

[Complex types are sent using JSV](/serialization-deserialization) by default which is a
more human & wrist-friendly and more efficient format than JSON, however we could also take advantage of the flexibility
in HTTP **multipart/form-data** requests to construct an HTTP API Request utilizing multiple Content-Type's optimized
for the data we're sending, e.g:

- JSON/JSV more optimal for hierarchical graph data 
- CSV more optimal for sending tabular data
- File Uploads are more optimal for sending large files

To facilitate this in our Server APIs we can use `[MultiPartField]` attribute to instruct ServiceStack which registered
serializer it should use to deserialize the form-data payload, whilst we can continue using the generic `[UploadTo]`
attribute in normal APIs to handle our File Uploads and populate the Request DTO with the uploaded file metadata.

Our `MultipartFormDataContent` extension methods simplifies our client logic by allowing us to easily populate this 
custom request in a single Fluent construction expression:

```csharp
using var content = new MultipartFormDataContent()
    .AddParam(nameof(MultipartRequest.Id), 1)
    .AddParam(nameof(MultipartRequest.String), "foo")
    .AddParam(nameof(MultipartRequest.Contact), 
        new Contact { Id = 1, FirstName = "First", LastName = "Last" })
    .AddJsonParam(nameof(MultipartRequest.PhoneScreen), 
        new PhoneScreen { Id = 3, JobApplicationId = 1, Notes = "The Notes"})
    .AddCsvParam(nameof(MultipartRequest.Contacts), new[] {
        new Contact { Id = 2, FirstName = "First2", LastName = "Last2" },
        new Contact { Id = 3, FirstName = "First3", LastName = "Last3" },
    })
    .AddFile(nameof(MultipartRequest.ProfileUrl), "profile.txt", file1Stream)
    .AddFile(nameof(MultipartRequest.UploadedFiles), "uploadedFiles1.txt", file2Stream)
    .AddFile(nameof(MultipartRequest.UploadedFiles), "uploadedFiles2.txt", file3Stream));

var api = await client.ApiFormAsync<MultipartRequest>(typeof(MultipartRequest).ToApiUrl(), content);
if (!api.Succeeded) api.Error.PrintDump();
```

## Capture HTTP Headers in .NET Service Clients

A common issue when trying to diagnose service integration issues is wanting to inspect the full HTTP traffic to help identify issues. Inside .NET Applications this would typically require using an external packet sniffer like Fiddler but just like Post Command **raw** HTTP captured output above you can now capture the raw HTTP traffic of all .NET `*ServiceClient` with the new `CaptureHttp()` API.

To print HTTP requests to the Console use:

```csharp
var client = new JsonServiceClient(BaseUrl);
client.CaptureHttp(print:true);

var authResponse = client.Send(new Authenticate { provider = "credentials", UserName = "admin", Password = "test" });
```

Which will print out the raw HTTP Request & Response Headers and body to the Console, e.g:

```
POST /json/reply/Authenticate HTTP/1.1
Host: test.servicestack.net
Accept: application/json
User-Agent: ServiceStack .NET Client 5.121
Accept-Encoding: gzip,deflate
Content-Type: application/json

{"provider":"credentials","UserName":"admin","Password":"test"}

HTTP/1.1 200 OK
Server: nginx/1.18.0, (Ubuntu)
Date: Sat, 21 Aug 2021 09:51:34 GMT
Transfer-Encoding: chunked
Connection: keep-alive
Set-Cookie: ss-id=o7VAdXm7JKLy92XiQcQQ; path=/; samesite=strict; httponly, ss-pid=I2MdbrzWZILqNCOqGlyR; expires=Wed, 21 Aug 2041 09:51:34 GMT; path=/; samesite=strict; httponly, ss-opt=temp; expires=Wed, 21 Aug 2041 09:51:34 GMT; path=/; samesite=strict; httponly, X-UAId=2; expires=Wed, 21 Aug 2041 09:51:34 GMT; path=/; samesite=strict; httponly, ss-tok=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiIsImtpZCI6IjNuLyJ9.eyJzdWIiOjIsImlhdCI6MTYyOTUzOTQ5NCwiZXhwIjoxNjMwNzQ5MDk0LCJlbWFpbCI6ImFkbWluQGdtYWlsLmNvbSIsImdpdmVuX25hbWUiOiJGaXJzdCBhZG1pbiIsImZhbWlseV9uYW1lIjoiTGFzdCBhZG1pbiIsIm5hbWUiOiJhZG1pbiBEaXNwbGF5TmFtZSIsInByZWZlcnJlZF91c2VybmFtZSI6ImFkbWluIiwicm9sZXMiOlsiQWRtaW4iXSwianRpIjoxMTR9.rHk-OdCwd8wR4AsT7exLRUr59-mzFs0FvKZUeZhvKMI; expires=Sat, 04 Sep 2021 09:51:34 GMT; path=/; samesite=strict; httponly, ss-reftok=eyJ0eXAiOiJKV1RSIiwiYWxnIjoiSFMyNTYiLCJraWQiOiIzbi8ifQ.eyJzdWIiOjIsImlhdCI6MTYyOTUzOTQ5NCwiZXhwIjoxNjYxMDc1NDk0LCJqdGkiOi02OX0.35MpYdz-QIkbVf98y_wNTA9PIYDy_EEQc3zfkpFvuQc; expires=Sun, 21 Aug 2022 09:51:34 GMT; path=/; samesite=strict; httponly
Vary: Accept
Access-Control-Allow-Credentials: true
Access-Control-Allow-Headers: Content-Type, Allow, Authorization, X-Args
Access-Control-Allow-Methods: GET, POST, PUT, DELETE, PATCH, OPTIONS, HEAD
X-Powered-By: ServiceStack/5.111 NetCore/Linux
X-Cookies: ss-tok,ss-reftok
Content-Type: application/json; charset=utf-8

{"userId":"2","sessionId":"o7VAdXm7JKLy92XiQcQQ","userName":"admin","displayName":"admin DisplayName","bearerToken":"eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiIsImtpZCI6IjNuLyJ9.eyJzdWIiOjIsImlhdCI6MTYyOTUzOTQ5NCwiZXhwIjoxNjMwNzQ5MDk0LCJlbWFpbCI6ImFkbWluQGdtYWlsLmNvbSIsImdpdmVuX25hbWUiOiJGaXJzdCBhZG1pbiIsImZhbWlseV9uYW1lIjoiTGFzdCBhZG1pbiIsIm5hbWUiOiJhZG1pbiBEaXNwbGF5TmFtZSIsInByZWZlcnJlZF91c2VybmFtZSI6ImFkbWluIiwicm9sZXMiOlsiQWRtaW4iXSwianRpIjoxMTR9.rHk-OdCwd8wR4AsT7exLRUr59-mzFs0FvKZUeZhvKMI","refreshToken":"eyJ0eXAiOiJKV1RSIiwiYWxnIjoiSFMyNTYiLCJraWQiOiIzbi8ifQ.eyJzdWIiOjIsImlhdCI6MTYyOTUzOTQ5NCwiZXhwIjoxNjYxMDc1NDk0LCJqdGkiOi02OX0.35MpYdz-QIkbVf98y_wNTA9PIYDy_EEQc3zfkpFvuQc","profileUrl":"data:image/svg+xml,...","roles":["Admin"],"permissions":[],"responseStatus":{}}
```

Alternatively you can log it to the debug logger with:

```csharp
var client = new JsonServiceClient(BaseUrl);
client.CaptureHttp(log:true);
```

Or if preferred you can capture it in a `StringBuilder` to inspect later by disabling clearing it after each request:

```csharp
var client = new JsonServiceClient(BaseUrl);
client.CaptureHttp(clear:false);
```

Which will begin capturing all HTTP requests made by that client in a `StringBuilder` you can access with:

```csharp
client.HttpLog
```

### ServiceClient URL Resolvers

The urls used in all .NET Service Clients are now customizable with the new `UrlResolver` and `TypedUrlResolver` 
delegates. 

E.g. you can use this feature to rewrite the URL used with the Request DTO Type Name used as the subdomain by:

```csharp
[Route("/test")] 
class Request {}

var client = JsonServiceClient("http://example.org/api") {
    TypedUrlResolver =  (meta, httpMethod, dto) => 
        meta.BaseUri.Replace("example.org", dto.GetType().Name + ".example.org")
            .CombineWith(dto.ToUrl(httpMethod, meta.Format)));
};

var res = client.Get(new Request());  //= http://Request.example.org/api/test
var res = client.Post(new Request()); //= http://Request.example.org/api/test
```

This feature is also implemented in `JsonHttpClient`, examples below shows rewriting APIs that use custom urls:

```csharp
var client = JsonHttpClient("http://example.org/api") {
    UrlResolver = (meta, httpMethod, url) => 
        meta.BaseUri.Replace("example.org", "111.111.111.111").CombineWith(url))
};

await client.DeleteAsync<MockResponse>("/dummy"); 
//=http://111.111.111.111/api/dummy

await client.PutAsync<MockResponse>("/dummy", new Request()); 
//=http://111.111.111.111/api/dummy
```

## [ServiceStack.Discovery.Consul](https://github.com/wwwlicious/servicestack-discovery-consul)

This feature makes it easier to support features like
[ServiceStack.Discovery.Consul](https://github.com/wwwlicious/servicestack-discovery-consul)
plugin which enables external RequestDTO endpoint discovery 
by integrating with [Consul.io](http://consul.io) to provide automatic service registration and health checking.

## Built-in Clients

All REST and ServiceClients share the same interfaces (`IServiceClient`, `IRestClient` and `IRestClientAsync`) so they can easily be replaced (for increased perf/debuggability/etc) with a single line of code.

### JsonHttpClient

The new `JsonHttpClient` is an alternative to the existing generic typed `JsonServiceClient` for consuming ServiceStack Services which instead of using **HttpWebRequest** is based on Microsoft's latest async [HttpClient](https://www.nuget.org/packages/Microsoft.Net.Http). 

JsonHttpClient implements the full [IServiceClient API](https://gist.github.com/mythz/4683438240820b522d39) making it an easy drop-in replacement for your existing JsonServiceClient where in most cases it can simply be renamed to JsonHttpClient, e.g:

```csharp
//IServiceClient client = new JsonServiceClient("https://techstacks.io");
IServiceClient client = new JsonHttpClient("https://techstacks.io");

var response = await client.GetAsync(new GetTechnology { Slug = "servicestack" })
```

::: warning
As .NET's HttpClient only supports async APIs it needs to use "sync over async" to implement sync APIs **which should be avoided**. If your API needs to make sync API calls it should use .NET 6's `JsonApiClient` or the `JsonServiceClient` instead.
:::

#### Install

JsonHttpClient can be downloaded from NuGet at:

:::copy
`<PackageReference Include="ServiceStack.HttpClient" Version="8.*" />`
:::

### Xamarin Native HttpClient

Using the default managed `HttpClient` implementation in Xamarin has a 
[number of issues](https://docs.microsoft.com/en-us/xamarin/cross-platform/macios/http-stack#cons-2) in iOS and Android devices.

Xamarin's MSDN docs explain the advantages of native implementations and show how you can enable 
[native HttpClient implementation for iOS/macOS](https://docs.microsoft.com/en-us/xamarin/cross-platform/macios/http-stack) for your project.

If you want to [programmatically enable it for iOS/macOS](https://docs.microsoft.com/en-us/xamarin/cross-platform/macios/http-stack#programmatically-setting-the-httpmessagehandler), you'll likely want to configure it once on the `GlobalHttpMessageHandlerFactory`
for all `JsonHttpClient` instances to use, e.g:

```csharp
// iOS
JsonHttpClient.GlobalHttpMessageHandlerFactory = () => 
    new NSUrlSessionHandler();
```

Or to only configure it for a specific client you can initialize an instance with:

```csharp
// iOS
var client = new JsonHttpClient(baseUrl) { 
    HttpMessageHandler = new NSUrlSessionHandler()
};
```

Refer to the [Xamarin MSDN docs for Android HttpClient](https://docs.microsoft.com/en-us/xamarin/android/app-fundamentals/http-stack?tabs=windows) for
how to enable it in your project, which can be globally programmatically configured with:

```csharp
// Android
JsonHttpClient.GlobalHttpMessageHandlerFactory = () => 
    new Xamarin.Android.Net.AndroidClientHandler();
```

Or per instance with:

```csharp
// Android
var client = new JsonHttpClient(baseUrl) { 
    HttpMessageHandler = new Xamarin.Android.Net.AndroidClientHandler()
};
```

### Differences with JsonServiceClient

Whilst the goal is to retain the same behavior in both clients, there are some differences resulting from using HttpClient where the Global and Instance Request and Response Filters are instead passed HttpClients `HttpRequestMessage` and `HttpResponseMessage`. 

Also, all API's are **Async** under-the-hood where any Sync API's that doesn't return a `Task<T>` just blocks on the Async `Task.Result` response. As this can dead-lock in certain environments we recommend sticking with the Async API's unless safe to do otherwise. 

### HttpWebRequest Service Clients

Whilst the list below contain the built-in clients based on .NET's built-in `HttpWebRequest`:

- implements both `IRestClient` and `IServiceClient`:
    - [JsonServiceClient](https://github.com/ServiceStack/ServiceStack/blob/master/src/ServiceStack.Client/JsonServiceClient.cs)
    (uses default endpoint with **JSON**) - recommended
    - [JsvServiceClient](https://github.com/ServiceStack/ServiceStack/blob/master/src/ServiceStack.Client/JsvServiceClient.cs)
    (uses default endpoint with **JSV**)
    - [XmlServiceClient](https://github.com/ServiceStack/ServiceStack/blob/master/src/ServiceStack.Client/XmlServiceClient.cs)
    (uses default endpoint with **XML**)
    - [CsvServiceClient](https://github.com/ServiceStack/ServiceStack/blob/master/src/ServiceStack.Client/CsvServiceClient.cs)
    (uses default endpoint with **CSV**)
    - [MsgPackServiceClient](/messagepack-format)
    (uses default endpoint with **Message-Pack**)
    - [ProtoBufServiceClient](/protobuf-format)
    (uses default endpoint with **Protocol Buffers**)
- implements `IServiceClient` only:
    - [Soap11ServiceClient](https://github.com/ServiceStack/ServiceStack/blob/master/src/ServiceStack.Client/Soap11ServiceClient.cs) (uses **SOAP 11** endpoint)
    - [Soap12ServiceClient](https://github.com/ServiceStack/ServiceStack/blob/master/src/ServiceStack.Client/Soap12ServiceClient.cs)
    (uses **SOAP 12** endpoint)

#### Install

The HttpWebRequest clients above are available in:

:::copy
`<PackageReference Include="ServiceStack.Client" Version="8.*" />`
:::

# Community Resources

  - [Reactive ServiceStack](https://gist.github.com/bamboo/5078236) by [@rodrigobamboo](https://twitter.com/rodrigobamboo)


# JsonServiceClient
Source: https://docs.servicestack.net/javascript-client

The **@servicestack/client** library enables the best end-to-end typed developer experience for calling ServiceStack APIs in
any TypeScript or JavaScript project.

## Usage in TypeScript or npm projects

Projects using TypeScript or any npm build system can install the dependency-free library with:

::: sh
npm install @servicestack/client
:::

Which can be used with your APIs typed DTOs that TypeScript projects can generate using 
[TypeScript Add ServiceStack Reference](/typescript-add-servicestack-reference#typescript-serviceclient) with:

::: sh
`x ts https://localhost:5001`
:::

Which will save your API DTOs to **dtos.ts** that can be referenced in your code with:

```ts
import { Hello } from "./dtos"
```

### JavaScript npm projects

Non-TypeScript npm projects can choose to either have TypeScript generate the DTOs into the preferred JavaScript target:

::: sh
tsc dtos.ts 
:::

Alternatively they can generate ES6 annotated DTOs using [JavaScript Add ServiceStack Reference](/javascript-add-servicestack-reference) with:

::: sh
`x mjs https://localhost:5001`
:::

Which will save your API DTOs to **dtos.mjs** where they can be referenced in your code with:

```ts
import { Hello } from "./dtos.mjs"
```

### Example Usage

Either solution gives you the same productive end-to-end Typed API access, e.g:

```ts
import { JsonServiceClient } from "@servicestack/client"

const client = new JsonServiceClient()

const api = await client.api(new Hello({ Name: 'World' }))
if (api.succeeded) {
    console.log(api.response.result)
} else {
    console.log(api.error)
}
```

## Usage in .NET Apps without npm

Modern JavaScript Apps not using an npm build system like the [Razor Vue Tailwind templates](/vue/#getting-started) can download 
**@servicestack/client** from:

 - https://unpkg.com/@servicestack/client@2/dist/servicestack-client.mjs
 - https://unpkg.com/@servicestack/client@2/dist/servicestack-client.min.mjs (minified)

Then use an [importmap](/javascript-add-servicestack-reference#import-maps) to specify where to load **@servicestack/client** from, e.g:

```html
<script async src="https://ga.jspm.io/npm:es-module-shims@1.6.3/dist/es-module-shims.js"></script><!--safari-->
<script type="importmap">
{
    "imports": {
        "@servicestack/client": "/js/servicestack-client.mjs"
    }
}
</script>
```

### ImportMap in Razor Pages or MVC

Razor Pages or MVC projects can use `@Html.ImportMap()` in **_Layout.cshtml** to use different builds for development and production, e.g:

```csharp
@if (Context.Request.Headers.UserAgent.Any(x => x.Contains("Safari") && !x.Contains("Chrome")))
{
    <script async src="https://ga.jspm.io/npm:es-module-shims@1.6.3/dist/es-module-shims.js"></script>
}
@Html.ImportMap(new()
{
    ["@servicestack/client"] = ("/js/servicestack-client.mjs", "/js/servicestack-client.min.mjs"),
})
```

This lets your source code reference the library by package name to enable using the same source code in a 
[JavaScript Module](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules), e.g:

```html
<script type="module">
import { JsonServiceClient } from "@servicestack/client"

const client = new JsonServiceClient()

const api = await client.api(new Hello({ Name: 'World' }))
</script>
```

### JavaScript API DTOs

Your [JavaScript API DTOs](/javascript-add-servicestack-reference) can either directly reference the **/types/mjs** endpoint:

```js
import { Hello } from '/types/mjs'
```

### Enable static analysis and intelli-sense 

Or for better IDE intelli-sense during development, save the annotated Typed DTOs to disk with the [x dotnet tool](/dotnet-tool):

:::sh
x mjs
:::

Then reference it instead to enable IDE static analysis when calling Typed APIs from JavaScript:

```js
import { Hello } from '/js/dtos.mjs'
client.api(new Hello({ name }))
```
    
To also enable static analysis for **@servicestack/client**, install the dependency-free library as a dev dependency:
    
:::sh
npm install -D @servicestack/client
:::

Where only its TypeScript definitions are used by the IDE during development to enable its type-checking and intelli-sense.

#### Support Legacy Browsers

JavaScript Projects needing to support legacy browsers can use [ES3 Common.js DTOs](/commonjs-add-servicestack-reference) to 
enable access using old-style `<script>` includes.

## JsonServiceClient

To create `JsonServiceClient` instances in v6+ projects using the [JSON /api route](/endpoint-routing#api-pre-defined-route) use:

```js
const client = new JsonServiceClient(baseUrl)
```

Where it's configured to not use any JSON HTTP Headers to enable more efficient CORS requests without preflight requests.

Alternatively if needed you can use `useBasePath()` to revert back to using legacy `/json/reply` pre-defined Routes:

```js
const client = new JsonServiceClient(baseUrl).useBasePath()
```

### API Reference

<a href="https://api.locode.dev/classes/client.JsonServiceClient.html"><div class="my-8 mx-auto max-w-xl block flex justify-center shadow hover:shadow-lg rounded py-1"><img class="p-4" src="/img/pages/clients/JsonServiceClient-ui-reference.png"></div></a>

### API method

The `api` returns a typed `ApiResult<Response>` Value Result that encapsulates either a Typed Response or a 
structured API Error populated in `ResponseStatus` allowing you to handle API responses programmatically without
`try/catch` handling:

```ts
const api = client.api(new Hello({ name }))
if (api.failed) {
    console.log(`Greeting failed! ${e.errorCode}: ${e.errorMessage}`);
    return;
}

console.log(`API Says: ${api.response.result}`) //api.succeeded
```

### Simplified API Handling

Being able to treat errors as values greatly increases the ability to programmatically handle and genericise api handling
and greatly simplifies functionality needing to handle both successful and error responses like binding to UI components.

An example of this is below where we're able to concurrently fire off multiple unrelated async requests in parallel, 
wait for them all to complete, print out the ones that have succeeded or failed then access their strong typed responses: 

```ts
import { JsonServiceClient } from "@servicestack/client"

let requests:ApiRequest[] = [
    new AppOverview(),            // GET => AppOverviewResponse
    new DeleteTechnology(),       // DELETE => IReturnVoid (requires auth) 
    new GetAllTechnologies(),     // GET => GetAllTechnologiesResponse
    new GetAllTechnologyStacks(), // GET => GetAllTechnologyStacksResponse
]

let results = await Promise.all(requests.map(async (request) =>
    ({ request, api:await client.api(request) as ApiResponse}) ))

let failed = results.filter(x => x.api.failed)
console.log(`${failed.length} failed:`)
failed.forEach(x =>
    console.log(`    ${x.request.getTypeName()} Request Failed: ${failed.map(x => x.api.errorMessage)}`))

let succeeded = results.filter(x => x.api.succeeded)
console.log(`\n${succeeded.length} succeeded: ${succeeded.map(x => x.request.getTypeName()).join(', ')}`)

let r = succeeded.find(x => x.request.getTypeName() == 'AppOverview')?.api.response as AppOverviewResponse
if (r) console.log(`Top 5 Technologies: ${r.topTechnologies.slice(0,4).map(tech => tech.name).join(', ')}`)
```

Output:

```
1 failed
DeleteTechnology Request Failed: Unauthorized

3 succeeded: AppOverview, GetAllTechnologies, GetAllTechnologyStacks
Top 5 Technologies: Redis, MySQL, Amazon EC2, Nginx
```

Being able to treat Errors as values has dramatically reduced the effort required to accomplish the same feat if needing 
to handle errors with `try/catch`.

### Ideal Typed Message-based API

The TypeScript `JsonServiceClient` enables the same productive, typed API development experience available 
in ServiceStack's other [1st-class supported client platforms](/typescript-add-servicestack-reference). 

The `JsonServiceClient` leverages the additional type hints ServiceStack embeds in each TypeScript Request DTO 
to achieve the ideal typed, message-based API - so all API requests benefit from a succinct, boilerplate-free 
Typed API. 

Here's a quick look at what it looks like. The example below shows how to create a 
[C# Gist in Gistlyn](https://github.com/ServiceStack/Gistlyn) 
after adding a [TypeScript ServiceStack Reference](/typescript-add-servicestack-reference)
to `gistlyn.com` and installing the [@servicestack/client](https://www.npmjs.com/package/@servicestack/client) 
npm package: 

```ts
import { JsonServiceClient } from '@servicestack/client';
import { StoreGist, GithubFile } from './dtos';

const client = new JsonServiceClient("https://gistlyn.com");

const request = new StoreGist({
    files: { 
        [file.filename]: new GithubFile({
            filename: 'main.cs',
            content: 'var greeting = "Hi, from TypeScript!";' 
        }) 
    }
})

const api = client.api(request); //response:StoreGistResponse
if (api.succeeded) {
    console.log(`New C# Gist was created with id: ${r.gist}`);
    location.href = `https://gist.cafe/${r.gist}`;
} else {
    console.log("Failed to create Gist: ", e.errorMessage);
}
```

Where the `response` param is typed to `StoreGistResponse` DTO Type.

### Sending additional arguments with Typed API Requests

Many AutoQuery Services utilize [implicit conventions](/autoquery/rdbms#implicit-conventions) 
to query fields that aren't explicitly defined on AutoQuery Request DTOs, these can now be queried by specifying additional arguments with the typed Request DTO, e.g:

```ts
//typed to QueryResponse<TechnologyStack> 
const response = await client.get(new FindTechStacks(), { VendorName: "ServiceStack" });
```

Which will [return TechStacks](http://techstacks.io/ss_admin/autoquery/FindTechStacks) developed by ServiceStack.

### Calling APIs with Custom URLs

You can call Services using relative or absolute urls, e.g:

```ts
client.get<GetTechnologyResponse>("/technology/ServiceStack")

client.get<GetTechnologyResponse>("http://techstacks.io/technology/ServiceStack")

// GET http://techstacks.io/technology?Slug=ServiceStack
client.get<GetTechnologyResponse>("/technology", { Slug: "ServiceStack" }) 
```

as well as POST Request DTOs to custom urls:

```ts
client.postToUrl("/custom-path", request, { Slug: "ServiceStack" });

client.putToUrl("http://example.org/custom-path", request);
```

### Raw Data Responses

The `JsonServiceClient` also supports Raw Data responses like `string` and `byte[]` which also get a Typed API 
once declared on Request DTOs using the `IReturn<T>` marker:

```csharp
public class ReturnString : IReturn<string> {}
public class ReturnBytes : IReturn<byte[]> {}
```

Which can then be accessed as normal, with their Response typed to a JavaScript `string` or `Uint8Array` for 
raw `byte[]` responses:

```ts
let str:string = await client.get(new ReturnString());

let data:Uint8Array = await client.get(new ReturnBytes());
```

### Authenticating using Basic Auth

Basic Auth support is implemented in `JsonServiceClient` and follows the same API made available in the C# 
Service Clients where the `userName/password` properties can be set individually, e.g:

```ts
var client = new JsonServiceClient(baseUrl);
client.userName = user;
client.password = pass;

const response = await client.get(new SecureRequest());
```

Or use `client.setCredentials()` to have them set both together.

### Authenticating using Credentials

Alternatively you can authenticate using userName/password credentials by 
[adding a TypeScript Reference](/typescript-add-servicestack-reference#add-typescript-reference) 
to your remote ServiceStack Instance and sending a populated `Authenticate` Request DTO, e.g:

```ts
const response = await client.post(new Authenticate({
    provider: "credentials", userName, password, rememberMe: true }));
```

This will populate the `JsonServiceClient` with 
[Session Cookies](/auth/sessions#cookie-session-ids) 
which will transparently be sent on subsequent requests to make authenticated requests.

### Authenticating using JWT

Use the `bearerToken` property to Authenticate with a [ServiceStack JWT Provider](/auth/jwt-authprovider) using a JWT Token:

```ts
client.bearerToken = jwtToken;
```

Alternatively you can use a [Refresh Token](/auth/jwt-authprovider#refresh-tokens) instead:

```ts
client.refreshToken = refreshToken;
```

### Authenticating using an API Key

Use the `bearerToken` property to Authenticate with an [API Key](/auth/api-key-authprovider):

```ts
client.bearerToken = apiKey;
```

### Transparently handle 401 Unauthorized Responses

If the server returns a 401 Unauthorized Response either because the client was Unauthenticated or the 
configured Bearer Token or API Key used had expired or was invalidated, you can use `onAuthenticationRequired`
callback to re-configure the client before automatically retrying the original request, e.g:

```ts
client.onAuthenticationRequired = async () => {
    const authClient = new JsonServiceClient(authBaseUrl);
    authClient.userName = userName;
    authClient.password = password;
    const response = await authClient.get(new Authenticate());
    client.bearerToken = response.bearerToken;
};

//Automatically retries requests returning 401 Responses with new bearerToken
var response = await client.get(new Secured());
```

### Automatically refresh Access Tokens

With the [Refresh Token support in JWT](/auth/jwt-authprovider#refresh-tokens) 
you can use the `refreshToken` property to instruct the Service Client to automatically fetch new 
JWT Tokens behind the scenes before automatically retrying failed requests due to invalid or expired JWTs, e.g:

```ts
//Authenticate to get new Refresh Token
const authClient = new JsonServiceClient(authBaseUrl);
authClient.userName = userName;
authClient.password = password;
const authResponse = await authClient.get(new Authenticate());

//Configure client with RefreshToken
client.refreshToken = authResponse.RefreshToken;

//Call authenticated Services and clients will automatically retrieve new JWT Tokens as needed
const response = await client.get(new Secured());
```

Use the `refreshTokenUri` property when refresh tokens need to be sent to a different ServiceStack Server, e.g:

```ts
client.refreshToken = refreshToken;
client.refreshTokenUri = authBaseUrl + "/access-token";
```

### [ServerEvents Client](/typescript-server-events-client)

The [TypeScript ServerEventClient](/typescript-server-events-client) 
is an idiomatic port of ServiceStack's 
[C# Server Events Client](/csharp-server-events-client) 
in native TypeScript providing a productive client to consume ServiceStack's 
[real-time Server Events](/server-events) that can be used in TypeScript 
[Web, Node.js Server and React Native iOS and Android Mobile Apps](https://github.com/ServiceStackApps/typescript-server-events).

```ts
const channels = ["home"];
const client = new ServerEventsClient("/", channels, {
    handlers: {
        onConnect: (sub:ServerEventConnect) => {  // Successful SSE connection
            console.log("You've connected! welcome " + sub.displayName);
        },
        onJoin: (msg:ServerEventJoin) => {        // User has joined subscribed channel
            console.log("Welcome, " + msg.displayName);
        },
        onLeave: (msg:ServerEventLeave) => {      // User has left subscribed channel
            console.log(msg.displayName + " has left the building");
        },
        onUpdate: (msg:ServerEventUpdate) => {    // User channel subscription was changed
            console.log(msg.displayName + " channels subscription were updated");
        },        
        onMessage: (msg:ServerEventMessage) => {},// Invoked for each other message
        //... Register custom handlers
        announce: (text:string) => {},            // Handle messages with simple argument
        chat: (chatMsg:ChatMessage) => {},        // Handle messages with complex type argument
        CustomMessage: (msg:CustomMessage) => {}, // Handle complex types with default selector
    },
    receivers: { 
        //... Register any receivers
        tv: {
            watch: function (id) {                // Handle 'tv.watch {url}' messages 
                var el = document.querySelector("#tv");
                if (id.indexOf('youtu.be') >= 0) {
                    var v = splitOnLast(id, '/')[1];
                    el.innerHTML = templates.youtube.replace("{id}", v);
                } else {
                    el.innerHTML = templates.generic.replace("{id}", id);
                }
                el.style.display = 'block'; 
            },
            off: function () {                    // Handle 'tv.off' messages
                var el = document.querySelector("#tv");
                el.style.display = 'none';
                el.innerHTML = '';
            }
        }
    },
    onException: (e:Error) => {},                 // Invoked on each Error
    onReconnect: (e:Error) => {}                  // Invoked after each auto-reconnect
})
.addListener("theEvent",(e:ServerEventMessage) => {}) // Add listener for pub/sub event trigger
.start();                                             // Start listening for Server Events!
```

When publishing a DTO Type for your Server Events message, your clients will be able to benefit from the generated DTOs in [TypeScript ServiceStack References](/typescript-add-servicestack-reference).

## Rich intelli-sense support

Even pure HTML/JS Apps that don't use TypeScript or any external dependencies will still benefit from the Server 
generated `dtos.ts` and TypeScript definitions where you'll be able to benefit from rich intelli-sense support 
in smart IDEs like [Rider](https://www.jetbrains.com/rider/) for both the client library:

![](/img/pages/mix/init-rider-ts-client.png)

As well as your App's server generated DTOs:

![](/img/pages/release-notes/v6.6/mjs-intellisense.png)


# Service Gateway
Source: https://docs.servicestack.net/service-gateway

The Service Gateway is implemented on top of ServiceStack's existing message-based architecture to open up 
exciting new possibilities for development of loosely-coupled
[Modularized Service Architectures](/modularizing-services).

The new [IServiceGateway](https://github.com/ServiceStack/ServiceStack/blob/master/src/ServiceStack.Interfaces/IServiceGateway.cs)
interfaces represent the minimal surface area required to support ServiceStack's different calling conventions 
in a formalized API that supports both Sync and Async Service Integrations:

```csharp
public interface IServiceGateway
{
    // Normal Request/Reply Services
    TResponse Send<TResponse>(object requestDto);

    // Auto Batched Request/Reply Requests
    List<TResponse> SendAll<TResponse>(IEnumerable<object> requestDtos);

    // OneWay Service
    void Publish(object requestDto);

    // Auto Batched OneWay Requests
    void PublishAll(IEnumerable<object> requestDtos);
}

// Equivalent Async API's
public interface IServiceGatewayAsync
{
    Task<TResponse> SendAsync<TResponse>(object requestDto, 
        CancellationToken token = default(CancellationToken));

    Task<List<TResponse>> SendAllAsync<TResponse>(IEnumerable<object> requestDtos, 
        CancellationToken token = default(CancellationToken));

    Task PublishAsync(object requestDto, 
        CancellationToken token = default(CancellationToken));

    Task PublishAllAsync(IEnumerable<object> requestDtos, 
        CancellationToken token = default(CancellationToken));
}
```

The minimum set of API's above requires the least burden for `IServiceGateway` implementers whilst the
[ServiceGatewayExtensions](https://github.com/ServiceStack/ServiceStack/blob/master/src/ServiceStack.Client/ServiceGatewayExtensions.cs)
overlays convenience API's common to all implementations providing the nicest API's possible for Request DTO's 
implementing the recommended `IReturn<T>` and `IReturnVoid` interface markers. The extension methods also 
provide fallback pseudo-async support for `IServiceGateway` implementations that also don't implement the
optional `IServiceGatewayAsync`, but will use native async implementations for those that do.

Naked Request DTO's without annotations are sent as a **POST** but alternative Verbs are also supported 
by annotating Request DTO's with 
[HTTP Verb Interface Markers](/csharp-client#http-verb-interface-markers)
where Request DTO's containing `IGet`, `IPut`, etc. are sent using the typed Verb API, e.g:

```csharp
[Route("/customers/{Id}")]
public class GetCustomer : IGet, IReturn<Customer>
{
    public int Id { get; set ;}
}

var customer = client.Send(new GetCustomer { Id = 1 }); //GET /customers/1
//Equivalent to:
var customer = client.Get(new GetCustomer { Id = 1 });  
```

### Service Integration API's

To execute existing ServiceStack Services internally you can call `ExecuteRequest(requestDto)` which 
passes the Request DTO along with the current `IRequest` into the `ServiceController.Execute()` to execute. 
The alternative is to call `ResolveService<T>` to resolve an autowired instance of the Service that's 
injected with the current `IRequest` context letting you call methods on the Service instance directly.
Below is an example of using both API's:

```csharp
public object Any(GetCustomerOrders request)
{
    using var orderService = base.ResolveService<OrderService>();
    return new GetCustomerOrders {
        Customer = (Customer)base.ExecuteRequest(new GetCustomer { Id = request.Id }),
        Orders = orderService.Any(new QueryOrders { CustomerId = request.Id })
    };
}
```

The recommended approach now is to instead use the `IServiceGateway` accessible from `base.Gateway` 
available in all Service, Razor Views, MVC ServiceStackController classes, etc. It works similar to
the `ExecuteRequest()` API (which it now replaces) where you can invoke a Service with just a populated 
Request DTO, but instead yields an ideal typed API for Request DTO's implementing the recommended `IReturn<T>`
or `IReturnVoid` markers:

```csharp
public object Any(GetCustomerOrders request)
{
    return new GetCustomerOrders {
        Customer = Gateway.Send(new GetCustomer { Id = request.Id }),
        Orders = Gateway.Send(new QueryOrders { CustomerId = request.Id })
    };
}
```

Or you can use the Async API if you prefer the non-blocking version:

```csharp
public async Task<GetCustomerOrdersResponse> Any(GetCustomerOrders request)
{
    return new GetCustomerOrdersResponse {
        Customer = await Gateway.SendAsync(new GetCustomer { Id = request.Id }),
        Orders = await Gateway.SendAsync(new QueryOrders { CustomerId = request.Id })
    };
}
```

The capability that sets the ServiceGateway apart (other than offering a nicer API to work with) 
is that this System could later have its **Customer** and **Order** Subsystems split out into different 
hosts and this exact Service implementation would continue to function as before, albeit a little slower due 
to the overhead of any introduced out-of-process communications.

The default implementation of `IServiceGateway` uses the 
[InProcessServiceGateway](https://github.com/ServiceStack/ServiceStack/blob/master/src/ServiceStack/InProcessServiceGateway.cs)
which delegates the Request DTO to the appropriate `ServiceController.Execute()` or 
`ServiceController.ExecuteAsync()` methods to execute the Service. One noticeable difference is that any 
Exceptions thrown by downstream Services are automatically converted into the same `WebServiceException` 
that clients would throw when calling the Service externally, this is so Exceptions are indistinguishable
whether it's calling an internal Service or an external one, which begins touching on the benefits of the 
Gateway... 

The ServiceGateway is the same interface whether you're calling an Internal Service on the Server or a 
remote Service from a client. It exposes an ideal message-based API that's
[optimal for remote Service Integrations](http://www.infoq.com/articles/interview-servicestack) 
that also supports 
[Auto Batched Requests](/auto-batched-requests) 
for combining multiple Service Calls into a single Request, minimizing latency when possible.

### Substitutable Service Gateways

These characteristics makes it easy to substitute and customize the behavior of the Gateway as visible in the
examples below. The easiest scenario to support is to redirect all Service Gateway calls to a remote 
ServiceStack instance which can be done by registering any .NET Service Client against the `IServiceGateway` 
interface, e.g:

```csharp
public override void Configure(Container container)
{
    container.Register<IServiceGateway>(c => new JsonApiClient(baseUrl));
}
```

A more likely scenario you'd want to support is a mix where internal requests are executed in-process 
and external requests call their respective Service. If your system is split in two this becomes a simple
check to return the local InProcess Gateway for Requests which are defined in this ServiceStack instance
otherwise return a Service Client configured to the alternative host when not, e.g:

```csharp
public class CustomServiceGatewayFactory : ServiceGatewayFactoryBase
{
    public override IServiceGateway GetGateway(Type requestType)
    {
        var isLocal = HostContext.Metadata.RequestTypes.Contains(requestType);
        var gateway = isLocal
            ? (IServiceGateway)base.localGateway
            : new JsonApiClient(alternativeBaseUrl);
        return gateway;
    }
}
```

For this we needed to implement the
[IServiceGatewayFactory](https://github.com/ServiceStack/ServiceStack/blob/master/src/ServiceStack.Interfaces/Web/IServiceGatewayFactory.cs)
so we can first capture the current `IRequest` that's needed in order to call the In Process Service Gateway with.
The convenience [ServiceGatewayFactoryBase](https://github.com/ServiceStack/ServiceStack/blob/master/src/ServiceStack/ServiceGatewayFactoryBase.cs)
abstracts the rest of the API away so you're only tasked with returning the appropriate Service Gateway for 
the specified Request DTO. 

Capturing the current `IRequest` makes the Gateway factory instance non-suitable to use as a singleton, 
so we'll need to register it with `AddTransient` or `ReuseScope.None` scope so a new instance is resolved each time:

```csharp
public override void Configure(Container container)
{
    container.AddTransient<IServiceGatewayFactory>(() => new CustomServiceGatewayFactory());
    
// Equivalent to:
//    container.Register<IServiceGatewayFactory>(x => new CustomServiceGatewayFactory())
//        .ReusedWithin(ReuseScope.None);
}
```

### Call Internal and External Services from URLs

The `Metadata.CreateRequestFromUrl()` API lets you create Request DTOs from absolute or relative URLs. This is useful if you need a generic routine to be able to execute a number of different Services from a collection or URL's, e.g:

```csharp
var processUrls = new []{ "https://example.org/invoices/generate?userId=1", "/assets/1/generate" };
foreach (var url in processUrls) 
{
    var request = HostContext.Metadata.CreateRequestFromUrl(url);
    var responseType = HostContext.Metadata.GetResponseTypeByRequest(request.GetType());
    var response = HostContext.AppHost.GetServiceGateway().Send(responseType, request);

    db.Insert(new Task { Url = url, Response = response.ToJson(), Completed = DateTime.UtcNow });
}
```

The Service Gateway provides an optimal way for executing Services where it will transparently execute local requests in process or external requests remotely using either the configured [Service Gateway](#substitutable-service-gateways) or Service Discovery Solution.

## Service Discovery

This demonstrates the underpinnings by which we can plug into and intercept all intra-Service calls and apply our own high-level custom logic which sets the foundation for other value-added functionality like [Service Discovery](/service-discovery) which can transparently route service calls to the most appropriate available remote endpoint at run-time, automatically without additional configuration or code-maintenance overhead.

## Designing for Microservices

Whether or not Systems 
[benefit overall from a fine-grained microservices architecture](http://blog.cleancoder.com/uncle-bob/2014/09/19/MicroServicesAndJars.html),
enough to justify the additional latency, management and infrastructure overhead it requires, we still see 
value in the development process of designing for Microservices where decoupling naturally 
isolated components into loosely-coupled subsystems has software-architecture benefits with overall complexity 
of an entire system being reduced into smaller, more manageable logical scopes which encapsulates their capabilities behind re-usable, 
[coarse-grained messages to small, well-defined facades](http://stackoverflow.com/a/32940275/85785).

The ServiceGateway and its Services Discovery ecosystem together with ServiceStack's recommended use of 
impl-free reusable POCO DTO's and its ability to 
[modularize Service implementations across multiple projects](/modularizing-services)
naturally promote a microservices-ready architecture where Service interactions are loosely-coupled behind 
well-defined, reusable, coarse-grained messages. Designing systems in this way later allows the isolated
Service Implementation .dll to be extracted from the main System and wrapped into its own AppHost. Together 
with an agreed Service Discovery solution, allows you to spawn multiple instances of the new Service -
letting you scale, deploy and maintain it independently from the rest of the system.


# Add ServiceStack Reference
Source: https://docs.servicestack.net/add-servicestack-reference

ServiceStack's **Add ServiceStack Reference** feature allows adding generated Native Types for the most popular typed languages and client platforms directly from within most major IDE's starting with [ServiceStackVS](/create-your-first-webservice#step-1-download-and-install-servicestackvs) - providing a simpler, cleaner and more versatile alternative to WCF's legacy **Add Service Reference** feature built into VS.NET.

Add ServiceStack Reference now supports 
[C#](/csharp-add-servicestack-reference), 
[TypeScript](/typescript-add-servicestack-reference), 
[JavaScript](/javascript-add-servicestack-reference),
[Python](/python-add-servicestack-reference),
[PHP](/php-add-servicestack-reference),
[Swift](/swift-add-servicestack-reference), 
[Java](/java-add-servicestack-reference), 
[Kotlin](/kotlin-add-servicestack-reference), 
[Dart](/dart-add-servicestack-reference), 
[F#](/fsharp-add-servicestack-reference),
[VB.NET](/vbnet-add-servicestack-reference) and
[ES3 Common.js](/commonjs-add-servicestack-reference) including integration with most leading IDE's to provide a flexible alternative than sharing your DTO assembly with clients. Clients can now easily add a reference to a remote ServiceStack url and update DTOs directly from within VS.NET, Xamarin Studio, Xcode, Android Studio, IntelliJ and Eclipse. We plan on expanding on this foundation into adding seamless, typed, end-to-end integration with other languages - Add a [feature request for your favorite language](https://servicestack.net/ideas) to prioritize support for it sooner!

Native Types provides an alternative for sharing DTO dlls, that can enable a better dev workflow for external clients who are now able to generate (and update) Typed APIs for your Services from a single remote url directly within their favorite IDE - reducing the burden and effort required to consume ServiceStack Services whilst benefiting from clients native language strong-typing feedback.

### Supported Languages

<table class="table table-bordered w-full" style="text-align:center">
    <tr>
        <td><a href="/csharp-add-servicestack-reference">C#</a></td>
        <td><a href="/typescript-add-servicestack-reference">TypeScript</a></td>
        <td><a href="/javascript-add-servicestack-reference">JavaScript</a></td>
        <td><a href="/python-add-servicestack-reference">Python</a></td>
        <td><a href="/php-add-servicestack-reference">PHP</a></td>
        <td><a href="/swift-add-servicestack-reference">Swift</a></td>
        <td><a href="/java-add-servicestack-reference">Java</a></td>
        <td><a href="/kotlin-add-servicestack-reference">Kotlin</a></td>
        <td><a href="/dart-add-servicestack-reference">Dart</a></td>
        <td><a href="/fsharp-add-servicestack-reference">F#</a></td>
        <td><a href="/vbnet-add-servicestack-reference">VB.NET</a></td>
    </tr>
</table>

![](./img/pages/add-ss-ref.svg)

### IDE Integration

To provide a seamless Development Experience, Add ServiceStack Reference is available as a plugin in most major IDEs which will allow your API Consumers to 
be able easily add a typed Service Reference to your Services with just its URL in their preferred language from within JetBrains Rider, VS.NET, Android Studio, PyCharm, IntelliJ IDEA, RubyMine, PhpStorm, WebStorm and Eclipse:

[![](./img/pages/servicestack-reference/ide-plugins-splash.png)](https://www.youtube.com/watch?v=JKsgrstNnYY)

Here's a quick walk through installing the **ServiceStack** plugin and using it to add a remote ServiceStack Reference in a new C# Application:

<lite-youtube class="w-full mx-4 my-4" width="560" height="315" videoid="JKsgrstNnYY" style="background-image: url('https://img.youtube.com/vi/JKsgrstNnYY/maxresdefault.jpg')"></lite-youtube>

:::tip
VSCode and other IDEs will be able to use the [Simple Command Line Utility](#simple-command-line-utilities) to add and update multiple Services references with a single command.
:::

### Call ServiceStack APIs from a Flutter App with native Dart client and DTOs

Walk through showing how you can use ServiceStack's Dart client library with your Flutter Android application to quickly get up and running with Add ServiceStack Reference.

<lite-youtube class="w-full mx-4 my-4" width="560" height="315" videoid="ocH5L-CikQ0" style="background-image: url('https://img.youtube.com/vi/ocH5L-CikQ0/maxresdefault.jpg')"></lite-youtube>

### C# Xamarin.Android Example in VS.NET

Using C# to develop native Mobile and Desktop Apps provides a number of benefits including maximum reuse of your investments across multiple Client Apps where they're able to reuse shared functionality, libraries, knowledge, development workflow and environment in both Client and Server Apps. 

<lite-youtube class="w-full mx-4 my-4" width="560" height="315" videoid="cbYuem1b2tg" style="background-image: url('https://img.youtube.com/vi/cbYuem1b2tg/maxresdefault.jpg')"></lite-youtube>

### Call ServiceStack APIs from Python

This video tutorial looks at how we can leverage Add ServiceStack Reference for Python in PyCharm, VSCode and [Python Jupyter Notebooks](/jupyter-notebooks-python).

<lite-youtube class="w-full mx-4 my-4" width="560" height="315" videoid="WjbhfH45i5k" style="background-image: url('https://img.youtube.com/vi/WjbhfH45i5k/maxresdefault.jpg')"></lite-youtube>

### Call ServiceStack APIs from PHP

This video tutorial looks at how we can easily integrate .NET Typed APIs to extend popular PHP Applications like Wordpress, Drupal or Laravel with [PHP Add ServiceStack Reference](/php-add-servicestack-reference).

<lite-youtube class="w-full mx-4 my-4" width="560" height="315" videoid="ZLVdaJ38vwc" style="background-image: url('https://img.youtube.com/vi/ZLVdaJ38vwc/maxresdefault.jpg')"></lite-youtube>

### Instant Client Apps

[Instant Client Apps](https://apps.servicestack.net/) is a free tool to jump start your native client application development using a wide range of languages and platforms including: C#, NodeJS, Dart, Java, Kotlin, Swift, VB .NET and F#:

<lite-youtube class="w-full mx-4 my-4" width="560" height="315" videoid="GTnuMhvUayg" style="background-image: url('https://img.youtube.com/vi/GTnuMhvUayg/maxresdefault.jpg')"></lite-youtube>

## gRPC

[ServiceStack gRPC](/grpc/) enables a highly productive development environment for developing high-performance gRPC HTTP/2 Services by making ServiceStack's existing typed Services available from ASP.NET's gRPC endpoints where ServiceStack offers a simplified development model for gRPC Clients for streamlined end-to-end productivity.

<lite-youtube class="w-full mx-4 my-4" width="560" height="315" videoid="UQlYodNS1xc" style="background-image: url('https://img.youtube.com/vi/UQlYodNS1xc/maxresdefault.jpg')"></lite-youtube>
## C# Mobile and Desktop Apps

[![](https://raw.githubusercontent.com/ServiceStackApps/HelloMobile/master/screenshots/splash-900.png)](https://github.com/ServiceStackApps/HelloMobile)

The generated DTOs provides a highly productive development workflow and enables a succinct end-to-end Typed API that can be used in both **.NET Framework** and **.NET Standard 2.0** [Generic Service Clients](/csharp-client) to facilitate Rapid Development in .NET's most popular Mobile and Desktop platforms:

 - WPF
 - UWP
 - Xamarin.Android
 - Xamarin.iOS
 - Xamarin.OSX
 - Xamarin.Forms
   - iOS
   - Android
   - UWP

The [HelloMobile](https://github.com/ServiceStackApps/HelloMobile) project contains multiple versions of the same App in all the above platforms demonstrating a number of different calling conventions, service integrations and reuse possibilities.

ServiceStack also allows for the maximum reuse possible by letting you reuse the same POCO DTOs used to define the Services contract with, in Clients Apps to provide its end-to-end typed API without any additional custom build tools, code-gen or any other artificial machinery, using just the DTOs in the shared `ServiceModel.dll` with any of the available highly performant [.NET generic Service Clients](/csharp-client) that be design encourages development of [resilient message-based Services](/what-is-a-message-based-web-service) for enabling [highly decoupled](/service-gateway) and easily [substitutable and mockable](/csharp-client#built-in-clients) Service Integrations.

## Utilize Native SDKs and Languages

Add ServiceStack Reference lets you utilize the native SDK's and development environment whilst maintaining the same productive development experience made possible with native idiomatic Service Clients in Web and across the most popular Mobile and Desktop platforms. App Developers can generate Typed DTOs for any ServiceStack Service in Android Apps using either [Java](/java-add-servicestack-reference) and [Kotlin](/kotlin-add-servicestack-reference), or use the [Swift](/swift-add-servicestack-reference) for development of native iOS or OSX Apps or [TypeScript](/typescript-add-servicestack-reference) for calling Services from [React Native, Node.js or Web Apps](https://github.com/ServiceStackApps/typescript-server-events).

### Flexible Customizations

Options for the generated DTOs can be further customized by updating the commented section in the header of the file. Each language will have different options for leveraging features native to each Language. See the specific language documentation for details on available options:

* [C# Options](/csharp-add-servicestack-reference#change-default-server-configuration)
* [TypeScript Options](./typescript-add-servicestack-reference.md#customize-dto-type-generation)
* [JavaScript Options](./javascript-add-servicestack-reference.md#customize-dto-type-generation)
* [Python Options](./python-add-servicestack-reference.md#customize-dto-type-generation)
* [Swift Options](/swift-add-servicestack-reference#swift-configuration)
* [Java Options](/java-add-servicestack-reference#java-configuration)
* [Kotlin Options](/kotlin-add-servicestack-reference#kotlin-configuration)
* [Dart Options](/dart-add-servicestack-reference#change-default-server-configuration)
* [F# Options](/fsharp-add-servicestack-reference#change-default-server-configuration)
* [VB.Net Options](/vbnet-add-servicestack-reference)

## Simple command-line utilities

The [x dotnet tool](/dotnet-tool) provides simple command-line utilities to easily Add and Update ServiceStack References for all of ServiceStack's supported languages.

## Installation

:::sh
dotnet tool install --global x 
:::

::include npx-get-dtos.md::

This will make the following utilities available from your command-line which will let you download the Server DTO classes for a remote ServiceStack endpoint in your chosen language which you can use with ServiceStack's generic Service clients to be able to make end-to-end API calls.

<table class="table table-bordered">
<tr>
    <th>Script</th>
    <th>Alias</th>
    <th>Language</th>
</tr>
<tr>
    <td>x csharp</td>
    <td>x cs</td>
    <td>C#</td>
</tr>
<tr>
    <td>x typescript</td>
    <td>x ts</td>
    <td>TypeScript</td>
</tr>
<tr>
    <td>x mjs</td>
    <td></td>
    <td>JavaScript</td>
</tr>
<tr>
    <td>x python</td>
    <td>x py</td>
    <td>Python</td>
</tr>
<tr>
    <td>x java</td>
    <td></td>
    <td>Java</td>
</tr>
<tr>
    <td>x kotlin</td>
    <td>x kt</td>
    <td>Kotlin</td>
</tr>
<tr>
    <td>x swift</td>
    <td></td>
    <td>Swift</td>
</tr>
<tr>
    <td>x dart</td>
    <td></td>
    <td>Dart</td>
</tr>
<tr>
    <td>x vbnet</td>
    <td>x vb</td>
    <td>VB.NET</td>
</tr>
<tr>
    <td>x fsharp</td>
    <td>x fs</td>
    <td>F#</td>
</tr>
</table>

## Usage

We'll walkthrough an example using TypeScript to download Server Types from the [techstacks.io](https://techstacks.io) ServiceStack Website to see how this works:

### Adding a ServiceStack Reference

To Add a TypeScript ServiceStack Reference just call `x typescript` with the URL of 
a remote ServiceStack instance:

:::sh
x typescript https://techstacks.io
:::


Result:

```
Saved to: dtos.ts
```

Calling `x typescript` with just a URL will save the DTOs using the Host name, you can override this by specifying a FileName as the 2nd argument:

:::sh
x typescript https://techstacks.io Tech
:::

Result:

```
Saved to: Tech.dtos.ts
```

### Updating a ServiceStack Reference

To Update an existing ServiceStack Reference, call `x typescript` with the Filename:

:::sh
x typescript dtos.ts
:::

Result:

```
Updated: dtos.ts
```

Which will update the File with the latest TypeScript Server DTOs from [techstacks.io](https://techstacks.io). You can also customize how DTOs are generated by uncommenting the [TypeScript DTO Customization Options](/typescript-add-servicestack-reference#dto-customization-options) and updating them again.

#### Updating all TypeScript DTOs

Calling `x typescript` without any arguments will update **all TypeScript DTOs** in the current directory:

:::sh
x typescript
:::

Result:

```
Updated: Tech.dtos.ts
Updated: dtos.ts
```

To make it more wrist-friendly you can also use the shorter `x ts` alias instead of `x typescript`.

### Installing Generic Service Client

Now we have our TechStacks Server DTOs we can use them with the generic `JsonServiceClient` in the [@servicestack/client](https://www.npmjs.com/package/@servicestack/client) npm package to make Typed API Calls.

:::sh
npm install @servicestack/client
:::

#### TechStacks Example

Once installed create a `demo.ts` file with the example below using both the `JsonServiceClient` from the **@servicestack/client** npm package and the Server DTOs we 
want to use from our local `dtos.ts` above:

```ts
import { JsonServiceClient } from '@servicestack/client';
import { GetTechnology, GetTechnologyResponse } from './dtos';

var client = new JsonServiceClient("https://techstacks.io")

async function main() {
    let request = new GetTechnology()
    request.Slug = "ServiceStack"

    const response = await client.get(request)
    console.log(response.Technology.VendorUrl)
}

main()
```

The `JsonServiceClient` is populated with the **BaseUrl** of the remote ServiceStack instance we wish to call. Once initialized we can send populated Request DTOs and handle
the Typed Response DTOs in Promise callbacks.

To run our TypeScript example we just need to compile it with TypeScript:

:::sh
tsc demo.ts
:::

Which will generate the compiled `demo.js` (and `typescript.dtos.js`) which we can then run with node:

:::sh
node demo.js
:::

Result:

```
https://servicestack.net
```


#### [Invoke ServiceStack APIs from the command-line](/post-command)

Easily inspect and invoke C# .NET Web APIs from the command-line with Post Command which allows you to both inspect and
call any ServiceStack API with just its name and a JS Object literal. API Responses returned in human-friendly markdown tables by default or 
optionally as JSON & raw HTTP.

### Built in Authentication

One of the benefits of utilizing smart generic Service Clients is being able to embed high-level generic functionality like 
Authentication that would be tedious and error prone for all API Consumers to have to implement manually.

All smart generic Service Clients have support for most of [built-in Authentication](/auth/authentication-and-authorization) options
including [OAuth Providers](https://github.com/ServiceStackApps/AndroidJavaChat) and [Sign In with Apple](/auth/signin-with-apple)
that are able to take advantage of the integrated and transparent JWT and Refresh Token Cookie support.

### Refresh Token Cookies supported in all Service Clients

::include jwt-service-clients.md::

### Integrate with Visual Studio

You can also easily integrate this within your VS.NET dev workflows by [adding it as an External Tool](https://docs.microsoft.com/en-us/visualstudio/ide/managing-external-tools?view=vs-2019) in the **External Tools** dialog box by choosing `Tools > External Tools`:

![](/img/pages/servicestack-reference/tool-ts-reference.png)

|  ||
|-|-|
| Title             | Update TypeScript &Reference |
| Command           | web.exe |
| Arguments         | ts |
| Initial directory | $(ProjectDir) |
|  ||

Which will then let you update all your `*dtos.ts` TypeScript References in your project by clicking on `Tools > Update TypeScript Reference` 
or using the `ALT+T R` keyboard shortcut.

If you wanted to Update your `*dtos.cs` **C# ServiceStack References** instead, just change Arguments to `cs`:

![](/img/pages/servicestack-reference/tool-cs-reference.png)

|  ||
|-|-|
| **Title**             | Update C# &Reference |
| **Command**           | web.exe |
| **Arguments**         | cs |
| **Initial directory** | $(ProjectDir) |
|  ||

Refer to the [x usage output](#usage) above for the arguments or aliases for all other supported languages.

### Integrate with Rider

Just like with VS.NET above you can [add an External Tool](https://www.jetbrains.com/help/rider/Settings_Tools_External_Tools.html) 
in [JetBrains Rider](https://www.jetbrains.com/rider/) by opening the Settings dialog with `CTRL+ALT+S` then searching for `external tools` 
under the **Tools** category:

![](/img/pages/servicestack-reference/rider-tool-ts-reference.png)

|  ||
|-|-|
| **Name**              | Update TypeScript Reference |
| **Command**           | web.exe |
| **Arguments**         | ts |
| **Working directory** | $FileParentDir$ |
|  ||

Now you can update your `*dtos.ts` TypeScript References in your project by clicking on `External Tools > Update TypeScript Reference`
in the right-click context menu:

![](/img/pages/servicestack-reference/rider-tool-ts-reference-run.png)

If you're updating references frequently you can save time by [assigning it a keyboard shortcut](https://www.jetbrains.com/help/rider/Configuring_Keyboard_and_Mouse_Shortcuts.html).


## Multiple File Upload Support with API Requests supported in all languages

To be able to call [AI Server](/ai-server/) APIs requiring file uploads we've added multiple file upload support with API Requests to the generic service clients for all our supported languages.

Here's what that looks like for different languages calling AI Server's `SpeechToText` API:

### C# Speech to Text

```csharp
using var fsAudio = File.OpenRead("audio.wav");
var response = client.PostFileWithRequest(new SpeechToText(),
    new UploadFile("audio.wav", fsAudio, "audio"));
```

### Dart Speech to Text

```dart
var audioFile = new File('audio.wav');
var uploadFile = new UploadFile(
    fieldName: 'audio',
    fileName: audioFile.uri.pathSegments.last,
    contentType: 'audio/wav',
    contents: await audioFile.readAsBytes()
);

var response = await client.postFileWithRequest(new SpeechToText(), uploadFile);
```

### Python Speech to Text

```python
with open("files/audio.wav", "rb") as audio:
  response = client.post_file_with_request(SpeechToText(), 
    UploadFile(field_name="audio", file_name="audio.wav", content_type="audio/wav", stream=audio))
```

### PHP Speech to Text

```php
$audioFile = __DIR__ . '/files/audio.wav';

/** @var GenerationResponse $response */
$response = $client->postFileWithRequest(new SpeechToText(),
    new UploadFile(
        filePath: $audioFile,
        fileName: 'audio.wav',
        fieldName: 'audio',
        contentType: 'audio/wav'
    ));
```

### Swift Speech to Text

```swift
guard let audioURL = Bundle.module.url(forResource: "audio.wav", withExtension: nil) else {
    return
}

let audioData = try Data(contentsOf: audioURL)
let response: TextGenerationResponse = try await client.postFileWithRequestAsync(
    request:SpeechToText(), 
    file:UploadFile(fileName: "audio.wav", data:audioData, fieldName:"audio"))
```

### Kotlin Speech to Text

```kotlin
val audioBytes = Files.readAllBytes(Paths.get("audio.wav"))
val response = client.postFileWithRequest(SpeechToText(),
    UploadFile("audio", "audio.wav", "audio/wav", audioBytes))
```

### Java Speech to Text

```java
byte[] audioBytes = Files.readAllBytes(Paths.get("audio.wav"));
var response = client.postFileWithRequest(request,
    new UploadFile("audio", "audio.wav", "audio/wav", audioBytes));
```

### TypeScript Speech to Text

```js
// Create FormData and append the file
const formData = new FormData()
const audioFile = fs.readFileSync('audio.wav')
const blob = new Blob([audioFile], { type: 'audio/wav' })

// Explicitly set the field name as 'audio'
formData.append('audio', blob, 'audio.wav')

const api = await client.apiForm(new SpeechToText(), formData)
```

### Multiple File Uploads

All languages also support a `postFilesWithRequest` variant for uploading multiple files with an API Request.
E.g. here's an example of using `PostFilesWithRequest` to generate a video with a Watermark:

### C# Watermark Video

```csharp
using var fsVideo = File.OpenRead("video.mp4");
using var fsWatermark = File.OpenRead("watermark.png");
var response = client.PostFilesWithRequest(new QueueWatermarkVideo {
        Position = WatermarkPosition.BottomRight
    }, [
        new UploadFile("video.mp4", fsVideo, "video"),
        new UploadFile("watermark.png", fsWatermark, "watermark")
    ]);
```

## Advantages over WCF

 - **Simple** Server provides DTOs based on metadata and options provided. No heavy client side tools, just a HTTP request!
 - **Versatile** Clean DTOs works in all JSON, XML, JSV, MsgPack and ProtoBuf [generic service clients](/csharp-client#built-in-clients)
 - **Reusable** Generated DTOs are not coupled to any endpoint or format. Defaults are both partial and virtual for maximum re-use 
 - **Resilient** Messaging-based services offer a number of [advantages over RPC Services](/advantages-of-message-based-web-services)
 - **Flexible** DTO generation is customizable, Server and Clients can override built-in defaults
 - **Integrated** Rich Service metadata annotated on DTO's, [Internal Services](/auth/restricting-services) are excluded when accessed externally

## In Contrast with WCF's Add Service Reference

WCF's **Add Service Reference** also allows generating a typed client from a single url, and whilst it's a great idea, the complexity upon what it's built-on and the friction it imposes were the primary reasons we actively avoided using it (pre-ServiceStack). We instead opted to reuse our server DTO types and created Generic WCF Proxies, to provide a cleaner and simpler solution when consuming our own WCF services. 

## ServiceStack's Native Types Feature

As with any ServiceStack feature one of our primary goals is to [minimize unnecessary complexity](/autoquery#why-not-complexity) by opting for approaches that yield maximum value and minimal complexity, favoring re-use and simple easy to reason about solutions over opaque heavy black-box tools.

We can already see from the WCF scenario how ServiceStack already benefits from its message-based design, where as it's able to reuse any [Generic Service Client](/clients-overview), only application-specific DTO's ever need to be generated, resulting in a much cleaner, simpler and friction-less solution.

Code-first is another approach that lends itself to simpler solutions, which saves the effort and inertia from adapting to interim schemas/specs, often with impedance mismatches and reduced/abstract functionality. In ServiceStack your code-first DTOs are the master authority where all other features are projected off. 

C# also has great language support for defining POCO Data Models, that's as terse as a DSL but benefits from great IDE support and minimal boilerplate, e.g:

```csharp
[Route("/path")]
public class Request : IReturn<Response>
{
    public int Id { get; set; }
    public string Name { get; set; }
    ...
}
```

Starting from a C# model, whilst naturally a better programmatic fit also ends up being richer and more expressive than XSD's which supports additional metadata annotations like Attributes and Interfaces. 

### Remove Native Types Feature

Native Types is enabled by default in ServiceStack projects. It can be disabled by removing the `NativeTypesFeature` plugin:

```csharp
Plugins.RemoveAll(x => x is NativeTypesFeature);
```

### Excluding Types from Add ServiceStack Reference

To remove a type from the metadata and code generation you can annotate Request DTOs with `[ExcludeMetadata]`, e.g:

```csharp
[ExcludeMetadata]
public class ExcludedFromMetadata
{
    public int Id { get; set; }
}
```

An alternative is it add it to the `IgnoreTypes` collection in the NativeTypes Feature Metadata Config in your AppHost:

```csharp
var nativeTypes = this.GetPlugin<NativeTypesFeature>();
nativeTypes.MetadataTypesConfig.IgnoreTypes.Add(typeof(TypeToIgnore));
```

If you only want to limit code generation based on where the reference is being added from you can use the 
[Restrict Attribute](/auth/restricting-services), 
E.g you can limit types to only appear when the reference is added from localhost:

```csharp
[Restrict(LocalhostOnly = true)]
public class RestrictedToLocalhost { }
```

Or when added from within an internal network:

```csharp
[Restrict(InternalOnly = true)]
public class RestrictedToInternalNetwork { }
```

There's also the rarer option when you only want a service accessible from external requests with:

```csharp
[Restrict(ExternalOnly = true)]
public class RestrictedToExternalRequests { }
```

### Export Types

By default the `NativeTypeFeature` doesn't emit any **System** types built into the Base Class Libraries, these can be 
emitted for non-.NET Languages with the new `ExportTypes` list, e.g. if your DTO's exposes the `DayOfWeek` System Enum it can
be exported by adding it to the pre-registered NativeTypesFeature's Plugin with:

```csharp
var nativeTypes = this.GetPlugin<NativeTypesFeature>();
nativeTypes.MetadataTypesConfig.ExportTypes.Add(typeof(DayOfWeek));
```

If any of your DTO's has a `DayOfWeek` property it will emitted in the generated DTO's, Java example:

```java
public static enum DayOfWeek
{
    Sunday,
    Monday,
    Tuesday,
    Wednesday,
    Thursday,
    Friday,
    Saturday;
}
```

### Force Include Types in Native Types DTOs

ServiceStack's Add ServiceStack Reference feature carefully limits which DTOs it generates based on just the DTOs needed by different clients packages to call APIs. There's many reasons why Types aren't generated, e.g. they already exist in service client library, the APIs have [Visibility or Access restrictions](/auth/restricting-services), their built-in APIs purposefully hidden by ServiceStack to reduce bloat, etc.

We can override these rules for specific Types by including them in `Metadata.ForceInclude`, e.g:

```csharp
public override void Configure(Container container)
{
    Metadata.ForceInclude = new() {
        typeof(MetadataApp),
        typeof(AppMetadata),
        typeof(AdminQueryUsers),
        typeof(AdminGetUser),
        typeof(AdminCreateUser),
        typeof(AdminUpdateUser),
        typeof(AdminDeleteUser),
    };
}
```

### Enable Versioning

You can implement our [recommended Versioning strategy](http://stackoverflow.com/a/12413091/85785) 
and embed a version number to all generated Request DTOs by specifying an `AddImplicitVersion`, 
either globally on the Server in your AppHost:

```csharp
var nativeTypes = this.GetPlugin<NativeTypesFeature>();
nativeTypes.MetadataTypesConfig.AddImplicitVersion = 1;
```

Alternatively you can configure [AddImplicitVersion in client Options](/csharp-add-servicestack-reference#addimplicitversion).

### Generating Types from Metadata

Behind the scenes ServiceStack captures all metadata on your Services DTOs including Sub -classes, Routes, `IReturn` marker, C# Attributes, textual Description as well as desired configuration into a serializable object model accessible from `/types/metadata`: 

## How it works

The Add ServiceStack Reference dialog just takes the URL provided and requests the appropriate route for the current project. Eg, for C#, the path used is at `/types/csharp`. The defaults are specified by the server and the resultant DTOs are saved and added the the project as `<Name>.dtos.<ext>`. The `Update ServiceStack Reference` menu is available when any file matches same naming convention of `<Name>.dtos.<ext>`. An update then looks at the comments at the top of the file and parses them to provide overrides when requesting new DTOs from the server. ServiceStackVS also watches these DTO files for updates, so just by saving them these files are updated from the server.

### Language Paths

| Path                | Language |
| --                  | -- |
| /types/csharp       | C# |
| /types/typescript   | TypeScript |
| /types/typescript.d | Ambient TypeScript Definitions |
| /types/js           | CommonJS |
| /types/python       | Python |
| /types/swift        | Swift |
| /types/java         | Java |
| /types/kotlin       | Kotlin |
| /types/dart         | Dart |
| /types/fsharp       | F# |
| /types/vbnet        | VB .NET  |
| /types/metadata     | Metadata |

::include add-servicestack-reference-footer.md::


# C# Add ServiceStack Reference
Source: https://docs.servicestack.net/csharp-add-servicestack-reference

[![](https://raw.githubusercontent.com/ServiceStackApps/HelloMobile/master/screenshots/splash-900.png)](https://github.com/ServiceStackApps/HelloMobile)

The primary and most popular [Add ServiceStack Reference](/add-servicestack-reference) language supported is C#, providing a flexible alternative than sharing your DTO assembly with clients, now clients can easily add a reference to a remote ServiceStack instance and update DTO's directly from within VS.NET. This also lays the groundwork and signals our approach on adding support for typed API's in other languages in future. Add a [feature request for your favorite language](https://servicestack.net/ideas) to prioritize support for it sooner!

Our goal with Native Types is to provide an alternative for sharing DTO dlls, that can enable a better dev workflow for external clients who are now able to generate (and update) Typed APIs for your Services from a remote url - reducing the burden and effort required to consume ServiceStack Services whilst benefiting from clients native language strong-typing feedback.

C# Xamarin.Android Example in VS.NET

<lite-youtube class="w-full mx-4 my-4" width="560" height="315" videoid="cbYuem1b2tg" style="background-image: url('https://img.youtube.com/vi/cbYuem1b2tg/maxresdefault.jpg')"></lite-youtube>

## Add ServiceStack Reference

The easiest way to [Add a ServiceStack reference](/add-servicestack-reference) to your project is to right-click on your project to bring up [ServiceStackVS's](/templates/install-servicestackvs) `Add ServiceStack Reference` context-menu item. This opens a dialog where you can add the url of the ServiceStack instance you want to typed DTO's for, as well as the name of the DTO source file that's added to your project.

[![Add ServiceStack Reference](https://raw.githubusercontent.com/ServiceStack/Assets/master/img/apps/StackApis/add-service-ref-flow.png)](https://raw.githubusercontent.com/ServiceStack/Assets/master/img/apps/StackApis/add-service-ref-flow.png)

After clicking OK, the servers DTOs and [ServiceStack.Client](https://www.nuget.org/packages/ServiceStack.Client) NuGet package are added to the project, providing an instant typed API:

[![Calling ServiceStack Service](https://raw.githubusercontent.com/ServiceStack/Assets/master/img/apps/StackApis/call-service.png)](https://raw.githubusercontent.com/ServiceStack/Assets/master/img/apps/StackApis/call-service.png)

With the C# code generated on the Server, the role of [ServiceStackVS's](/create-your-first-webservice) **Add ServiceStack Reference** is then just to integrate the remote C# DTOs into the clients VS.NET project. This is just getting the generated DTOs from the server with default options set by the server and adding them locally to your project within Visual Studio.

![Add CSharp ServiceStack Reference Demo](https://github.com/ServiceStack/Assets/raw/master/img/servicestackvs/servicestack%20reference/addref-csharp.gif)

## Update ServiceStack Reference
If your server has been updated and you want to update to client DTOs, simply right-click on the DTO file within VS.NET and select `Update ServiceStack Reference`. 

![CSharp update demo](https://github.com/ServiceStack/Assets/raw/master/img/servicestackvs/servicestack%20reference/updateref-csharp.gif)

## Consuming Services from Mobile Clients

Thanks to [ServiceStack.Client](https://www.nuget.org/packages/ServiceStack.Client) PCL Support, it can also be used from within supported client platforms. Here's a quick Android demo of adding a ServiceStack reference to [blazor-vue.web-templates.io](https://blazor-vue.web-templates.io) and consuming one of StackApi's Services:

[![Android Add ServiceStack Reference](https://raw.githubusercontent.com/ServiceStack/ServiceStackVS/master/Images/android-add-ref-demo.gif)](https://raw.githubusercontent.com/ServiceStack/ServiceStackVS/master/Images/android-add-ref-demo.gif)

## DTO Customization Options 

The header comments in the generated DTOs allows for further customization of how they're generated where ServiceStackVS automatically watches for any file changes and updates the generated DTOs with any custom Options provided. Options that are preceded by a C# single line comment `//` are defaults from the server that can be overridden, e.g:

```csharp
/* Options:
Date: 2025-06-04 09:45:54
Version: 8.80
Tip: To override a DTO option, remove "//" prefix before updating
BaseUrl: https://blazor-vue.web-templates.io

//GlobalNamespace: 
//MakePartial: True
//MakeVirtual: True
//MakeInternal: False
//MakeDataContractsExtensible: False
//AddNullableAnnotations: False
//AddReturnMarker: True
//AddDescriptionAsComments: True
//AddDataContractAttributes: False
//AddIndexesToDataMembers: False
//AddGeneratedCodeAttributes: False
//AddResponseStatus: False
//AddImplicitVersion: 
//InitializeCollections: False
//ExportValueTypes: False
//IncludeTypes: 
//ExcludeTypes: 
//AddNamespaces: 
//AddDefaultXmlNamespace: http://schemas.servicestack.net/types
*/
```

To override these options on the client, the `//` has to be removed. For example, if we did not want our classes to be partial by default for the C# client, our options would look like below:

```csharp
/* Options:
Date: 2025-06-04 09:46:15
Version: 8.80
Tip: To override a DTO option, remove "//" prefix before updating
BaseUrl: https://blazor-vue.web-templates.io

//GlobalNamespace: 
MakePartial: False
//MakeVirtual: True
//MakeInternal: False
//MakeDataContractsExtensible: False
//AddNullableAnnotations: False
//AddReturnMarker: True
//AddDescriptionAsComments: True
//AddDataContractAttributes: False
//AddIndexesToDataMembers: False
//AddGeneratedCodeAttributes: False
//AddResponseStatus: False
//AddImplicitVersion: 
//InitializeCollections: False
//ExportValueTypes: False
//IncludeTypes: 
//ExcludeTypes: 
//AddNamespaces: 
//AddDefaultXmlNamespace: http://schemas.servicestack.net/types
*/
```

Options that do not start with a `//` are sent to the server to override any defaults set by the server.

### Change Default Server Configuration

The above defaults are also overridable on the ServiceStack Server by modifying the default config on the `NativeTypesFeature` Plugin, e.g:

```csharp
var nativeTypes = this.GetPlugin<NativeTypesFeature>();
nativeTypes.MetadataTypesConfig.MakeVirtual = false;
...
```

### Customize DTO Type generation

Additional C# specific customization can be statically configured like `PreTypeFilter`, `InnerTypeFilter` & `PostTypeFilter` (available in all languages) can be used to inject custom code 
in the generated DTOs output. 

Use the `PreTypeFilter` to generate source code before and after a Type definition, e.g. this will append the `[Validate]` attribute on non enum & interface types:

```csharp
CSharpGenerator.PreTypeFilter = (sb, type) => {
    if (!type.IsEnum.GetValueOrDefault() && !type.IsInterface.GetValueOrDefault())
    {
        sb.AppendLine("[Validate]");
    }
};
```

The `InnerTypeFilter` gets invoked just after the Type Definition which can be used to generate common members for all Types and interfaces, e.g:

```csharp
CSharpGenerator.InnerTypeFilter = (sb, type) => {
    sb.AppendLine("public string Id { get; } = Guid.NewGuid().ToString();");
};
```

There's also `PrePropertyFilter` & `PostPropertyFilter` for generating source before and after properties, e.g:

```csharp
CSharpGenerator.PrePropertyFilter = (sb , prop, type) => {
    if (prop.Name == "Id")
    {
        sb.AppendLine("[PrimaryKey]");
    }
};
```

### Emit custom code

To enable greater flexibility when generating complex Typed DTOs, you can use `[Emit{Language}]` attributes to generate code before each type or property.

These attributes can be used to generate different attributes or annotations to enable client validation for different validation libraries in different languages, e.g:

```csharp
[EmitCSharp("[Validate]")]
[EmitCode(Lang.CSharp | Lang.Swift | Lang.Dart, "// App User")]
public class User : IReturn<User>
{
    [EmitCSharp("[IsNotEmpty]","[IsEmail]")]
    [EmitCode(Lang.Swift | Lang.Dart, new[]{ "@isNotEmpty()", "@isEmail()" })]
    public string Email { get; set; }
}
```

Which will generate `[EmitCsharp]` code in C# DTOs:

```csharp
[Validate]
// App User
public partial class User
    : IReturn<User>
{
    [IsNotEmpty]
    [IsEmail]
    public virtual string Email { get; set; }
}
```

Whilst the generic `[EmitCode]` attribute lets you emit the same code in multiple languages with the same syntax.

We'll go through and cover each of the above options to see how they affect the generated DTOs:

### GlobalNamespace

Specify which namespace the generated C# DTOs should use:

```csharp
namespace Acme 
{
    //...
}
```

### MakePartial

Adds the `partial` modifier to all types, letting you extend generated DTOs with your own class separate from the generated types:

```csharp
public partial class GetAnswers { ... }
```

### MakeVirtual

Adds the `virtual` modifier to all properties:

```csharp
public partial class GetAnswers {
    ...
    public virtual int QuestionId { get; set; }
}
```

### MakeDataContractsExtensible

Add .NET's DataContract's [ExtensionDataObject](http://msdn.microsoft.com/en-us/library/system.runtime.serialization.extensiondataobject(v=vs.110).aspx) to all DTO's:

```csharp
public partial class GetAnswers
    : IReturn<GetAnswerResponse>, IExtensibleDataObject
{
    ...
    public virtual ExtensionDataObject ExtensionData { get; set; }
}
```

### AddNullableAnnotations

Generate DTOs with nullable reference types, e.g:

```csharp
public class Data
{
    public int Value { get; set; }
    public int? OptionalValue { get; set; }
    public string Text { get; set; }
    public string? OptionalText { get; set; }
    public List<string> Texts { get; set; }
    public List<string>? OptionalTexts { get; set; }
}
```

Will generate DTOs, preserving properties with nullable reference type annotations:

```csharp
public class Data
{
    public virtual int Value { get; set; }
    public virtual int? OptionalValue { get; set; }
    public virtual string Text { get; set; }
    public virtual string? OptionalText { get; set; }
    public virtual List<string> Texts { get; set; } = [];
    public virtual List<string>? OptionalTexts { get; set; }
}
```

Optionally if your DTOs do not have nullable reference annotations enabled but you would still like to generate DTOs with them included, you can mark properties as required with the `[Required]` attribute, e.g:

```csharp
public class Data
{
    [Required]
    public string? Text { get; set; }
    [Required]
    public List<string>? Texts { get; set; }
}
```

Where it will generate otherwise optional properties as non-nullable reference types:

```csharp
public class Data
{
    [Required]
    public virtual string Text { get; set; }

    [Required]
    public virtual List<string> Texts { get; set; } = [];
}
```

### AddReturnMarker

When true, annotates Request DTOs with an `IReturn<TResponse>` marker referencing the Response type ServiceStack infers your Service to return:

```csharp
public class GetAnswers
    : IReturn<GetAnswersResponse> { ... }
``` 

> Original DTO doesn't require a return marker as response type can be inferred from Services return type or when using the `%Response` DTO Naming convention

### AddDescriptionAsComments

Converts any textual Description in `[Description]` attributes as C# Doc comments which allows your API to add intellisense in client projects:

```csharp
///<summary>
///Get a list of Answers for a Question
///</summary>
public class GetAnswers { ... }
```

### AddDataContractAttributes

Decorates all DTO types with `[DataContract]` and properties with `[DataMember]` as well as adding default XML namespaces for all C# namespaces used:

```csharp
[assembly: ContractNamespace("http://schemas.servicestack.net/types", 
           ClrNamespace="StackApis.ServiceModel.Types")]
[assembly: ContractNamespace("http://schemas.servicestack.net/types", 
           ClrNamespace="StackApis.ServiceModel")]
...

[DataContract]
public partial class GetAnswers
{
    [DataMember]
    public virtual int QuestionId { get; set; }
}
```

### AddIndexesToDataMembers

Populates a `DataMember` Order index for all properties:

```csharp
[DataContract]
public partial class GetAnswers
{
    [DataMember(Order=1)]
    public virtual int QuestionId { get; set; }
}
```

> Requires AddDataContractAttributes=true

### AddGeneratedCodeAttributes

Emit `[GeneratedCode]` attribute on all generated Types:

```csharp
[GeneratedCode]
public partial class GetAnswers { ... }
```

### AddResponseStatus

Automatically add a `ResponseStatus` property on all Response DTOs, regardless if it wasn't already defined:

```csharp
public class GetAnswersResponse
{
    ...
    public ResponseStatus ResponseStatus { get; set; }
}
```

### AddImplicitVersion

Usage: 
```
/* Options:
AddImplicitVersion: 1
```

Lets you specify the Version number to be automatically populated in all Request DTOs sent from the client: 

```csharp
public partial class GetAnswers
    : IReturn<GetAnswersResponse>
{
    public virtual int Version { get; set; }

    public GetAnswers()
    {
        Version = 1;
    }
    ...
}
```

This lets you know what Version of the Service Contract that existing clients are using making it easy to implement ServiceStack's [recommended versioning strategy](http://stackoverflow.com/a/12413091/85785). 

### InitializeCollections

Usage: 
```
/* Options:
InitializeCollections: True
```

Lets you automatically initialize collections in Request DTOs:

```csharp
public class SearchQuestions
{
    public SearchQuestions()
    {
        Tags = new List<string>{};
    }

    public List<string> Tags { get; set; }
    ...
}
```

Initialized collections lets you take advantage of C#'s collection initializers for a nicer client API:

```csharp
var response = client.Get(new SearchQuestions { 
    Tags = { "redis", "ormlite" }
});
```

### IncludeTypes
Is used as a Whitelist to specify only the types you would like to have code-generated:

```
/* Options:
IncludeTypes: GetTechnology,GetTechnologyResponse
```

Will only generate `GetTechnology` and `GetTechnologyResponse` DTO's:

```csharp
public class GetTechnology { ... }
public class GetTechnologyResponse { ... }
```

#### Include Generic Types

Use .NET's Type Name to include Generic Types, i.e. the Type name separated by the backtick followed by the number of generic arguments, e.g:

```
IncludeTypes: IReturn`1,MyPair`2
```

#### Include Request DTO and its dependent types

You can include a Request DTO and all its dependent types with a `.*` suffix on the Request DTO, e.g:

```
/* Options:
IncludeTypes: GetTechnology.*
```

Which will include the `GetTechnology` Request DTO, the `GetTechnologyResponse` Response DTO and all Types that they both reference.

#### Include All Types within a C# namespace

If your DTOs are grouped into different namespaces they can be all included using the `/*` suffix, e.g:

```
/* Options:
IncludeTypes: MyApp.ServiceModel.Admin/*
```

This will include all DTOs within the `MyApp.ServiceModel.Admin` C# namespace. 

#### Include All Services in a Tag Group

Services [grouped by Tag](/api-design#group-services-by-tag) can be used in the `IncludeTypes` where tags can be specified using braces in the format `{tag}` or `{tag1,tag2,tag3}`, e.g:

```
/* Options:
IncludeTypes: {web,mobile}
```

Or individually:

```
/* Options:
IncludeTypes: {web},{mobile}
```

### ExcludeTypes
Is used as a Blacklist to specify which types you would like excluded from being generated:

```
/* Options:
ExcludeTypes: GetTechnology,GetTechnologyResponse
```

Will exclude `GetTechnology` and `GetTechnologyResponse` DTOs from being generated.

### AddNamespaces

Include additional C# namespaces, e.g:

```
/* Options:
AddNamespaces: System.Drawing,MyApp
```

Where it will generate the specified namespaces in the generated Types:

```csharp
using System.Drawing;
using MyApp;
```

### AddDefaultXmlNamespace

This lets you change the default DataContract XML namespace used for all C# namespaces:

```csharp
[assembly: ContractNamespace("http://my.types.net", 
           ClrNamespace="StackApis.ServiceModel.Types")]
[assembly: ContractNamespace("http://my.types.net", 
           ClrNamespace="StackApis.ServiceModel")]
```

> Requires AddDataContractAttributes=true


# TypeScript Add ServiceStack Reference
Source: https://docs.servicestack.net/typescript-add-servicestack-reference

![ServiceStack and TypeScript Banner](https://raw.githubusercontent.com/ServiceStack/Assets/master/img/release-notes/servicestack-heart-typescript.png)

ServiceStack's **Add ServiceStack Reference** feature allows clients to generate Native Types from directly within VS.NET using [ServiceStackVS VS.NET Extension](/create-your-first-webservice) - providing a simple way to give clients typed access to your ServiceStack Services.

## Install

::include ref-servicestack-client.md::

### First class development experience

[TypeScript](https://www.typescriptlang.org/) has become a core part of our overall recommended solution 
for Web Apps that's integrated into all ServiceStackVS's 
[React and Aurelia Single Page App VS.NET Templates](https://github.com/ServiceStack/ServiceStackVS) 
offering a seamless development experience with access to advanced ES6 features like modules, classes 
and arrow functions whilst still being able to target most web browsers with its down-level ES5 support. 
TypeScript also goes beyond ES6 with optional Type Annotations enabling better tooling support and compiler 
type feedback than what's possible in vanilla ES6 - invaluable when scaling large JavaScript codebases.

### Ideal Typed Message-based API

The TypeScript `JsonServiceClient` available in the 
[@servicestack/client npm package](https://www.npmjs.com/package/@servicestack/client) enables the same 
productive, typed API development experience available in our other 1st-class supported client platforms. 

ServiceStack embeds additional type hints in each Request DTO in order to achieve the ideal typed, 
message-based API. You can see an example of this is below which shows how to create a C# Gist in 
[Gislyn](http://gistlyn.com) after adding a ServiceStack Reference to `gistlyn.com` and installing the 
[@servicestack/client](https://www.npmjs.com/package/@servicestack/client) npm package: 

```ts
import { JsonServiceClient } from 'servicestack-client';
import { StoreGist, GithubFile } from './Gistlyn.dtos';

var client = new JsonServiceClient("http://gistlyn.com");

var request = new StoreGist();
var file = new GithubFile();
file.filename = "main.cs";
file.content = 'var greeting = "Hi, from TypeScript!";';
request.files = { [file.filename]: file };

try {
    var r = await client.post(request); // r:StoreGistResponse
    console.log(`New C# Gist was created with id: ${r.gist}`);
    location.href = `http://gistlyn.com?gist=${r.gist}`;
} catch (e) {
    console.log("Failed to create Gist: ", e.responseStatus);
}
```

Where the `r` param in the returned `then()` Promise callback is typed to `StoreGistResponse` DTO Type.

### Supports JavaScript only Environments

Despite generating Typed TypeScript DTOs, the generic `JsonServiceClient` and generated TypeScript DTOs can also be utilized in
JavaScript-Only development environments like [React Native](https://youtu.be/T3KTDPdovOw) or in the [Nuxt Templates](/templates/nuxt)
which doesn't use TypeScript in its build, but can be easily integrated by adding an npm script to using the 
[dotnet tools](/dotnet-tool) to generate the DTOs and the global `typescript` npm tool to compile it into the module we want,
which in React Native projects would look like:

```json
"scripts": {
    "dtos": "cd src/shared && x typescript && tsc -m ES6 dtos.ts",
}
```


### @servicestack/client API

The public TypeScript Definition containing the public API for all functionality contained in any of the above `@servicestack/client` libraries is available from [index.d.ts](https://github.com/ServiceStack/servicestack-client/blob/master/src/index.d.ts). 

Here are direct links to the 2 primary API Clients:

 - [JsonServiceClient](https://github.com/ServiceStack/servicestack-client/blob/4d17350f77c6461965f3bf0a5451a4e60e35f992/src/index.d.ts#L288)
 - [ServerEventsClient](https://github.com/ServiceStack/servicestack-client/blob/4d17350f77c6461965f3bf0a5451a4e60e35f992/src/index.d.ts#L167)

### TypeScript Ambient Interface Definitions or Concrete Types

You can get both concrete types and interface definitions for your Services at the following routes:

  - [/types/typescript](https://techstacks.io/types/typescript) - for generating concrete types
  - [/types/typescript.d](https://techstacks.io/types/typescript.d) - for generating ambient interface definitions

## Simple command-line utilities for TypeScript

The [dotnet tools](/dotnet-tool) include built in support for generating TypeScript references from the command-line:

### Installation

:::sh
dotnet tool install --global x 
:::

::include npx-get-dtos.md::

### Adding a ServiceStack Reference

To Add a TypeScript ServiceStack Reference just call `x typescript` with the URL of a remote ServiceStack instance:

:::sh
`x typescript https://techstacks.io`
:::

Result:

```
Saved to: dtos.ts
```

Calling `x typescript` with just a URL will save the DTOs using the Host name, you can override this by specifying a FileName as the 2nd argument:

:::sh
`x typescript https://techstacks.io Tech`
:::

Result:

```
Saved to: Tech.dtos.ts
```

### Updating a ServiceStack Reference

To Update an existing ServiceStack Reference, call `x typescript` with the Filename:

:::sh
x typescript dtos.ts
:::

Result:

```
Updated: dtos.ts
```

Which will update the File with the latest TypeScript Server DTOs from [techstacks.io](https://techstacks.io). You can also customize how DTOs are generated by uncommenting the [TypeScript DTO Customization Options](/typescript-add-servicestack-reference#dto-customization-options) and updating them again.

### Updating all TypeScript DTOs

Calling `x typescript` without any arguments will update all TypeScript DTOs in the current directory:

:::sh
x typescript
:::

Result:

```
Updated: Tech.dtos.ts
Updated: dtos.ts
```

### npm tools

The `x` dotnet tools require .NET Core installed, a pure npm-based alternative is to install the [@servicestack/cli](https://github.com/ServiceStack/servicestack-cli)
 npm package containing the `typescript-ref` (or wrist-friendly `ts-ref` alias) commands which can be used instead of `x typescript`.

## Add TypeScript Reference

The easiest way to 
[Add a ServiceStack Reference](/add-servicestack-reference) 
to your project is to **right-click** on a folder to bring up 
[ServiceStackVS's](/create-your-first-webservice)
VS.NET context-menu item, then click on `Add -> TypeScript Reference...`. This opens a dialog where you can 
add the url of the ServiceStack instance you want to typed DTO's for, as well as the name of the DTO source 
file that's added to your project.

![Add ServiceStack Reference](https://raw.githubusercontent.com/ServiceStack/Assets/master/img/servicestackvs/add-typescript-reference-js.png)

After clicking OK, the servers DTO's are added to the project, yielding an instant typed API:

![TypeScript native types](https://raw.githubusercontent.com/ServiceStack/Assets/master/img/servicestackvs/add-typescript-reference-dtos.png)


### Change Default Server Configuration

The above defaults are also overridable on the ServiceStack Server by modifying the default config on the `NativeTypesFeature` Plugin, e.g:

```csharp
var nativeTypes = this.GetPlugin<NativeTypesFeature>();
nativeTypes.MetadataTypesConfig.MakeVirtual = false;
...
```

### Customize DTO Type generation

Additional TypeScript specific customization can be statically configured like `PreTypeFilter`, `InnerTypeFilter` & `PostTypeFilter` (available in all languages) can be used to inject custom code in the generated DTOs output. 

Use the `PreTypeFilter` to generate source code before and after a Type definition, e.g. this will append the `[Validate]` attribute on non enum & interface types:

```csharp
TypeScriptGenerator.PreTypeFilter = (sb, type) => {
    if (!type.IsEnum.GetValueOrDefault() && !type.IsInterface.GetValueOrDefault())
    {
        sb.AppendLine("@Validate()");
    }
};
```

The `InnerTypeFilter` gets invoked just after the Type Definition which can be used to generate common members for all Types and interfaces, e.g:

```csharp
TypeScriptGenerator.InnerTypeFilter = (sb, type) => {
    sb.AppendLine("id:string = `${Math.random()}`.substring(2);");
};
```

There's also `PrePropertyFilter` & `PostPropertyFilter` for generating source before and after properties, e.g:

```csharp
TypeScriptGenerator.PrePropertyFilter = (sb , prop, type) => {
    if (prop.Name == "Id")
    {
        sb.AppendLine("@IsInt()");
    }
};
```

### Emit custom code

To enable greater flexibility when generating complex Typed DTOs, you can use `[Emit{Language}]` attributes to generate code before each type or property.

These attributes can be used to generate different attributes or annotations to enable client validation for different validation libraries in different languages, e.g:

```csharp
[EmitTypeScript("@Validate()")]
[EmitCode(Lang.TypeScript | Lang.Swift | Lang.Dart, "// App User")]
public class User : IReturn<User>
{
    [EmitTypeScript("@IsNotEmpty()", "@IsEmail()")]
    [EmitCode(Lang.Swift | Lang.Dart, new[]{ "@isNotEmpty()", "@isEmail()" })]
    public string Email { get; set; }
}
```

Which will generate `[EmitTypeScript]` code in TypeScript DTOs:

```typescript
@Validate()
// App User
export class User implements IReturn<User>
{
    @IsNotEmpty()
    @IsEmail()
    public email: string;

    public constructor(init?: Partial<User>) { (Object as any).assign(this, init); }
    public createResponse() { return new User(); }
    public getTypeName() { return 'User'; }
}
```

Whilst the generic `[EmitCode]` attribute lets you emit the same code in multiple languages with the same syntax.

### Update ServiceStack Reference

If your server has been updated and you want to update the client DTOs, simply **right-click** on the DTO file 
within VS.NET and select **Update ServiceStack Reference** for **ServiceStackVS** to download a fresh update. 

### TypeScript Reference Example

Lets walk through a simple example to see how we can use ServiceStack's TypeScript DTO annotations in our 
JavaScript clients. Firstly we'll need to add a TypeScript Reference to the remote ServiceStack Service by 
**right-clicking** on your project and clicking on `Add > TypeScript Reference...` 
(as seen in the above screenshot).

This will import the remote Services dtos into your local project which looks similar to:

```ts
/* Options:
Date: 2025-06-04 09:47:09
Version: 8.71
Tip: To override a DTO option, remove "//" prefix before updating
BaseUrl: https://techstacks.io

//GlobalNamespace: 
//MakePropertiesOptional: False
//AddServiceStackTypes: True
//AddResponseStatus: False
//AddImplicitVersion: 
//AddDescriptionAsComments: True
//IncludeTypes: 
//ExcludeTypes: 
//DefaultImports: 
*/

// @Route("/technology/{Slug}")
export class GetTechnology implements IReturn<GetTechnologyResponse>, IRegisterStats, IGet
{
    public slug: string;

    public constructor(init?: Partial<GetTechnology>) { (Object as any).assign(this, init); }
    public getTypeName() { return 'GetTechnology'; }
    public getMethod() { return 'GET'; }
    public createResponse() { return new GetTechnologyResponse(); }
}

export class GetTechnologyResponse
{
    public created: string;
    public technology: Technology;
    public technologyStacks: TechnologyStack[];
    public responseStatus: ResponseStatus;

    public constructor(init?: Partial<GetTechnologyResponse>) { (Object as any).assign(this, init); }
}
```

In keeping with idiomatic style of local `.ts` sources, generated types are not wrapped within a module 
by default. This lets you reference the types you want directly using normal import destructuring syntax:

```ts
import { GetTechnology, GetTechnologyResponse } from './dtos';
```

Or import all Types into your preferred variable namespace with:

```ts
import * as dtos from './dtos';

const request = new dtos.GetTechnology();
```

Or if preferred, you can instead have the types declared in a module by specifying a `GlobalNamespace`:

```ts
/* Options:
...

GlobalNamespace: dtos
*/
```

Looking at the types we'll notice the DTO's are plain TypeScript Types with any .NET attributes 
added in comments using AtScript's proposed 
[meta-data annotations format](https://docs.google.com/document/d/11YUzC-1d0V1-Q3V0fQ7KSit97HnZoKVygDxpWzEYW0U/mobilebasic?viewopt=127). 
This lets you view helpful documentation about your DTO's like the different custom routes available 
for each Request DTO.

By default DTO properties are optional but can be made a required field by annotating the .NET property 
with the `[Required]` attribute or by uncommenting `MakePropertiesOptional: False` in the header comments 
which instead defaults to using required properties.

Properties always reflect to match the remote servers JSON Serialization configuration, 
i.e. will use **camelCase** properties when the `AppHost` is configured with:

```csharp
JsConfig.Init(new Config { TextCase = TextCase.CamelCase });
```

### Making Typed API Requests

Making API Requests in TypeScript is the same as all other
[ServiceStack's Service Clients](/clients-overview)
by sending a populated Request DTO using a `JsonServiceClient` which returns typed Response DTO.

So the only things we need to make any API Request is the `JsonServiceClient` from the `@servicestack/client` 
package and any DTO's we're using from generated TypeScript ServiceStack Reference, e.g:

```ts
import { JsonServiceClient } from '@servicestack/client';
import { GetTechnology } from './dtos';

const client = new JsonServiceClient("https://techstacks.io");

const request = new GetTechnology();
request.Slug = "ServiceStack";

var r = await client.get(request);  // typed to GetTechnologyResponse
cont tech = r.Technology;           // typed to Technology

console.log(`${tech.Name} by ${tech.VendorName} (${tech.ProductUrl})`);
console.log(`${tech.Name} TechStacks:`, r.TechnologyStacks);
```

### Partial Constructors

All TypeScript Reference DTOs also includes support for **Partial Constructors**
making them much nicer to populate using object initializer syntax we're used to in C#, so instead of:

```ts
const request = new Authenticate();
request.provider = 'credentials'
request.userName = this.userName;
request.password = this.password;
request.rememberMe = this.rememberMe;
const response = await client.post(request);
```

You can populate DTOs with object literal syntax without any loss of TypeScript's Type Safety benefits:

```ts
const response = await client.post(new Authenticate({
    provider: 'credentials',
    userName: this.userName,
    password: this.password,
    rememberMe: this.rememberMe,
}));
```

### Sending additional arguments with Typed API Requests

Many AutoQuery Services utilize [implicit conventions](/autoquery/rdbms#implicit-conventions) to 
query fields that aren't explicitly defined on AutoQuery Request DTOs, these can be queried by specifying
additional arguments with the typed Request DTO, e.g:

```ts
const request = new FindTechStacks();

var r = client.get(request, { VendorName: "ServiceStack" }); // typed to QueryResponse<TechnologyStack>
```

### Making API Requests with URLs

In addition to making Typed API Requests you can also call Services using relative or absolute urls, e.g:

```ts
client.get<GetTechnologyResponse>("/technology/ServiceStack")

client.get<GetTechnologyResponse>("https://techstacks.io/technology/ServiceStack")

// https://techstacks.io/technology?Slug=ServiceStack
client.get<GetTechnologyResponse>("/technology", { Slug: "ServiceStack" }) 
```

as well as POST Request DTOs to custom urls:

```ts
client.postToUrl("/custom-path", request, { Slug: "ServiceStack" });

client.putToUrl("http://example.org/custom-path", request);
```

### Uploading Files 

We can populate custom requests by either programmatically constructing the 
[FormData](https://developer.mozilla.org/en-US/docs/Web/API/FormData) object, which also benefits from native integration
in browsers where it can be populated directly from an HTML Form:

```ts
let client = new JsonServiceClient(BaseUrl)
let formData = new FormData(document.forms[0])
let api = await client.apiForm(new MultipartRequest(), formData)
```

Where `apiForm` can be used to submit `FormData` requests for normal API Requests, or `apiFormVoid` for `IReturnVoid` API requests.

### TypeScript Speech to Text

Here's an example calling [AI Server's](/ai-server/) `SpeechToText` API:

```js
// Create FormData and append the file
const formData = new FormData()
const audioFile = fs.readFileSync('audio.wav')
const blob = new Blob([audioFile], { type: 'audio/wav' })

// Explicitly set the field name as 'audio'
formData.append('audio', blob, 'audio.wav')

const api = await client.apiForm(new SpeechToText(), formData)
```

### Raw Data Responses

The `JsonServiceClient` also supports Raw Data responses like `string` and `byte[]` which also get a Typed API 
once declared on Request DTOs using the `IReturn<T>` marker:

```csharp
public class ReturnString : IReturn<string> {}
public class ReturnBytes : IReturn<byte[]> {}
```

Which can then be accessed as normal, with their Response typed to a JavaScript `string` or `Uint8Array` for 
raw `byte[]` responses:

```ts
let str:string = await client.get(new ReturnString());

let data:Uint8Array = await client.get(new ReturnBytes());
```

### Access Request / Response Headers

You can use [JsonServiceClient](https://github.com/ServiceStack/servicestack-client/blob/master/src/index.d.ts) instance 
`requestFilter` and `responseFilter` to inspect the underlying 
[fetch](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API) API's:

```ts
export declare class JsonServiceClient {
    //...
    requestFilter: (req: IRequestInit) => void;
    responseFilter: (res: Response) => void;
}
```

To inspect the underlying W3C 
[fetch](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API) 
API's [Request](https://developer.mozilla.org/en-US/docs/Web/API/Request) and 
[Response](https://developer.mozilla.org/en-US/docs/Web/API/Response) objects, e.g:

```js
let client = new JsonServiceClient()
client.responseFilter = res => {
    console.log(res.headers)
}

var response = await client.get(new MyRequest())
```

### TypeScript Nullable properties

The default TypeScript generated for a C# DTO like:

```csharp
public class Data
{
    [Required]
    public int Value { get; set; }
    public int? OptionalValue { get; set; }
    public string Text { get; set; }
}
```

Will render the DTO with optional properties:

```csharp
export class Data
{
    // @Required()
    public value: number;

    public optionalValue?: number;
    public text?: string;

    public constructor(init?: Partial<Data>) { (Object as any).assign(this, init); }
}
```

This behavior can be changed to emit nullable properties instead with:

```csharp
TypeScriptGenerator.UseNullableProperties = true;
```

Where it will instead emit nullable properties:

```ts
export class Data
{
    public value: number|null;
    public optionalValue: number|null;
    public text: string|null;

    public constructor(init?: Partial<Data>) { (Object as any).assign(this, init); }
}
```

If finer-grained customization is needed to control which type and property should be nullable, you can 
use the customizable `TypeScriptGenerator` filters (which `UseNullableProperties` defaults to):

```csharp
TypeScriptGenerator.IsPropertyOptional = (generator, type, prop) => false;

TypeScriptGenerator.PropertyTypeFilter = (gen, type, prop) => 
    gen.GetPropertyType(prop, out var isNullable) + "|null";
```

### Authenticating using Basic Auth

Basic Auth support is implemented in `JsonServiceClient` and follows the same API made available in the C# 
Service Clients where the `userName/password` properties can be set individually, e.g:

```ts
var client = new JsonServiceClient(baseUrl);
client.userName = user;
client.password = pass;

const response = await client.get(new SecureRequest());
```

Or use `client.setCredentials()` to have them set both together.

### Authenticating using Credentials

Alternatively you can authenticate using userName/password credentials by 
[adding a TypeScript Reference](/typescript-add-servicestack-reference#add-typescript-reference) 
to your remote ServiceStack Instance and sending a populated `Authenticate` Request DTO, e.g:

```ts
let request = new Authenticate();
request.provider = "credentials";
request.userName = userName;
request.password = password;
request.rememberMe = true;

const response = await client.post(request);
```

This will populate the `JsonServiceClient` with 
[Session Cookies](/auth/sessions#cookie-session-ids) 
which will transparently be sent on subsequent requests to make authenticated requests.

### Authenticating using JWT

Use the `bearerToken` property to Authenticate with a [ServiceStack JWT Provider](/auth/jwt-authprovider) using a JWT Token:

```ts
client.bearerToken = jwtToken;
```

Alternatively you can use a [Refresh Token](/auth/jwt-authprovider#refresh-tokens) instead:

```ts
client.refreshToken = refreshToken;
```

### Authenticating using an API Key

Use the `bearerToken` property to Authenticate with an [API Key](/auth/api-key-authprovider):

```ts
client.bearerToken = apiKey;
```

### Transparently handle 401 Unauthorized Responses

If the server returns a 401 Unauthorized Response either because the client was Unauthenticated or the 
configured Bearer Token or API Key used had expired or was invalidated, you can use `onAuthenticationRequired`
callback to re-configure the client before automatically retrying the original request, e.g:

```ts
client.onAuthenticationRequired = async () => {
    const authClient = new JsonServiceClient(authBaseUrl);
    authClient.userName = userName;
    authClient.password = password;
    const response = await authClient.get(new Authenticate());
    client.bearerToken = response.bearerToken;
};

//Automatically retries requests returning 401 Responses with new bearerToken
var response = await client.get(new Secured());
```

### Automatically refresh Access Tokens

With the [Refresh Token support in JWT](/auth/jwt-authprovider#refresh-tokens) 
you can use the `refreshToken` property to instruct the Service Client to automatically fetch new 
JWT Tokens behind the scenes before automatically retrying failed requests due to invalid or expired JWTs, e.g:

```ts
//Authenticate to get new Refresh Token
const authClient = new JsonServiceClient(authBaseUrl);
authClient.userName = userName;
authClient.password = password;
const authResponse = await authClient.get(new Authenticate());

//Configure client with RefreshToken
client.refreshToken = authResponse.RefreshToken;

//Call authenticated Services and clients will automatically retrieve new JWT Tokens as needed
const response = await client.get(new Secured());
```

Use the `refreshTokenUri` property when refresh tokens need to be sent to a different ServiceStack Server, e.g:

```ts
client.refreshToken = refreshToken;
client.refreshTokenUri = authBaseUrl + "/access-token";
```

## DTO Customization Options 

In most cases you'll just use the generated TypeScript DTO's as-is, however you can further customize how
the DTO's are generated by overriding the default options.

The header in the generated DTO's show the different options TypeScript native types support with their 
defaults. Default values are shown with the comment prefix of `//`. To override a value, remove the `//` 
and specify the value to the right of the `:`. Any uncommented value will be sent to the server to override 
any server defaults.

The DTO comments allows for customizations for how DTOs are generated. The default options that were used 
to generate the DTO's are repeated in the header comments of the generated DTOs, options that are preceded 
by a TypeScript comment `//` are defaults from the server, any uncommented value will be sent to the server 
to override any server defaults.

```ts
/* Options:
Date: 2018-05-01 08:09:43
Version: 5.10
Tip: To override a DTO option, remove "//" prefix before updating
BaseUrl: https://techstacks.io

//GlobalNamespace: 
//MakePropertiesOptional: True
//AddServiceStackTypes: True
//AddResponseStatus: False
//AddImplicitVersion: 
//AddDescriptionAsComments: True
//IncludeTypes: 
//ExcludeTypes: 
//DefaultImports: 
*/
```

We'll go through and cover each of the above options to see how they affect the generated DTO's:

### Change Default Server Configuration

The above defaults are also overridable on the ServiceStack Server by modifying the default config on the 
`NativeTypesFeature` Plugin, e.g:

```csharp
//Server example in CSharp
var nativeTypes = this.GetPlugin<NativeTypesFeature>();
nativeTypes.MetadataTypesConfig.GlobalNamespace = "dtos";
...
```

We'll go through and cover each of the above options to see how they affect the generated DTO's:

### GlobalNamespace

Changes the name of the module that contain the generated TypeScript definitions:

```ts
declare module dtos
{
    ...
}
```

### ExportAsTypes

Changes whether types should be generated as ambient interface definitions or exported as concrete Types:

```ts
module dtos
{
    export interface IReturnVoid
    {
    }
    ...
}
```

### MakePropertiesOptional

Changes whether the default of whether each property is optional or not:

```ts
interface Answer
{
    AnswerId: number;
    Owner: User;
    IsAccepted: boolean;
    Score: number;
    LastActivityDate: number;
    LastEditDate: number;
    CreationDate: number;
    QuestionId: number;
}
```

### AddResponseStatus

Automatically add a `ResponseStatus` property on all Response DTO's, regardless if it wasn't already defined:

```ts
interface GetAnswers extends IReturn<GetAnswersResponse>
{
    ...
    ResponseStatus: ResponseStatus;
}
```

### AddImplicitVersion

Lets you specify the Version number to be automatically populated in all Request DTO's sent from the client: 

```ts
interface GetAnswers extends IReturn<GetAnswersResponse>
{
    Version: number; //1
    ...
}
```

This lets you know what Version of the Service Contract that existing clients are using making it easy 
to implement ServiceStack's [recommended versioning strategy](http://stackoverflow.com/a/12413091/85785). 

### IncludeTypes

Is used as a Whitelist to specify only the types you would like to have code-generated:

```
/* Options:
IncludeTypes: GetTechnology,GetTechnologyResponse
```

Will only generate `GetTechnology` and `GetTechnologyResponse` DTO's:

```csharp
export class class GetTechnology { ... }
export class class GetTechnologyResponse { ... }
```

#### Include Generic Types

Use .NET's Type Name to include Generic Types, i.e. the Type name separated by the backtick followed by the number of generic arguments, e.g:

```
IncludeTypes: IReturn`1,MyPair`2
```

#### Include Request DTO and its dependent types

You can include a Request DTO and all its dependent types with a `.*` suffix on the Request DTO, e.g:

```
/* Options:
IncludeTypes: GetTechnology.*
```

Which will include the `GetTechnology` Request DTO, the `GetTechnologyResponse` Response DTO and all Types that they both reference.

#### Include All Types within a C# namespace

If your DTOs are grouped into different namespaces they can be all included using the `/*` suffix, e.g:

```
/* Options:
IncludeTypes: MyApp.ServiceModel.Admin/*
```

This will include all DTOs within the `MyApp.ServiceModel.Admin` C# namespace. 

#### Include All Services in a Tag Group

Services [grouped by Tag](/api-design#group-services-by-tag) can be used in the `IncludeTypes` where tags can be specified using braces in the format `{tag}` or `{tag1,tag2,tag3}`, e.g:

```
/* Options:
IncludeTypes: {web,mobile}
```

Or individually:

```
/* Options:
IncludeTypes: {web},{mobile}
```

### ExcludeTypes
Is used as a Blacklist to specify which types you would like excluded from being generated:

```
/* Options:
ExcludeTypes: GetTechnology,GetTechnologyResponse
```

Will exclude `GetTechnology` and `GetTechnologyResponse` DTOs from being generated.

### DefaultImports

The `Symbol:module` short-hand syntax can be used for specifying additional imports in your generated TypeScript DTOs, e.g:

```ts
/* Options:
...
DefaultImports: Symbol:module,Zip:./ZipValidator
*/
```

Which will generate the popular import form of:

```ts
import { Symbol } from "module";
import { Zip } from "./ZipValidator";
```

## React Native JsonServiceClient

React Native Android JavaScript Example using VS Code:

<lite-youtube class="w-full mx-4 my-4" width="560" height="315" videoid="T3KTDPdovOw" style="background-image: url('https://img.youtube.com/vi/T3KTDPdovOw/maxresdefault.jpg')"></lite-youtube>

## TypeScript Interface Definitions

By checking **Only TypeScript Definitions** check-box on the dialog when Adding a TypeScript Reference
you can instead import Types as a
[TypeScript declaration file](http://www.typescriptlang.org/Handbook#writing-dts-files) (.d.ts).

TypeScript declarations are just pure static type annotations, i.e. they don't generate any code or 
otherwise have any effect on runtime behavior. This makes them useful as a non-invasive drop-in into 
existing JavaScript code where it's just used to provide type annotations on existing JavaScript objects, 
letting you continue using your existing data types and ajax libraries.

### Referencing TypeScript DTO's

Once added to your project, use VS.NET's JavaScript doc comments to reference the TypeScript definitions 
in your `.ts` scripts. The example below shows how to use the above TypeScript definitions to create a 
typed Request/Response utilizing jQuery's Ajax API to fire off a new Ajax request on every keystroke:

```xml
/// <reference path="dtos.d.ts"/>
...

<input type="text" id="txtHello" data-keyup="sayHello" /> 
<div id="result"></div>

<script>
bindHandlers({
    sayHello: function () {
        var request: dtos.Hello = {};
        request.title = "Dr";
        request.name = this.value;
        
        $.getJSON(createUrl("/hello/{Name}", request), request, 
            function (r: HelloResponse) {
                $("#result").html(r.result);
            });
    }
});
</script>
```

Here we're using the built-in `createUrl()` servicestack client API to create the url for the **GET** HTTP Request 
using the Route definition for the API you want to call and the Request DTO which results in:

```
/hello/World?title=Dr
```

We're also able to use the `HelloResponse` type definition to take advantage of typed DTO compile time safety in TypeScript code bases.

### Angular HTTP Client

Likewise you can use `createUrl()` to utilize Angular's built-in Rx-enabled HTTP Client with ServiceStack’s ambient TypeScript declarations when utilizing Angular's built-in dependencies is preferable.

ServiceStack’s ambient TypeScript interfaces are leveraged to enable a Typed that lets you reuse your APIs Route definitions (emitted in comments above each Request DTO) to provide a pleasant UX for making API calls using Angular's HTTP Client:

```ts
import { createUrl } from '@servicestack/client';
...

this.http.get<HelloResponse>(createUrl('/hello/{Name}', { name })).subscribe(r => {
    this.result = r.result;
});
```

### ss-utils.js 

Likewise if using [ss-utils.js](/ss-utils-js) you can use the `$.ss.createUrl()` API for the same functionality, e.g:

```js
$(document).bindHandlers({
    sayHello: function () {
        var request: dtos.Hello = {};
        request.title = "Dr";
        request.name = this.value;
        
        $.getJSON($.ss.createUrl("/hello/{Name}", request), request, 
            function (r: dtos.HelloResponse) {
                $("#result").html(r.result);
            });
    }
});
```

Which results in a HTTP GET request with the expected Url:

```
/hello/World?title=Dr
```

### [ServerEvents Client](/typescript-server-events-client)

The [TypeScript ServerEventClient](/typescript-server-events-client) is an idiomatic port of ServiceStack's 
[C# Server Events Client](/csharp-server-events-client) in native TypeScript providing a productive 
client to consume ServiceStack's [real-time Server Events](/server-events) that can be used in both 
TypeScript Web and node.js server applications.

```ts
const channels = ["home"];
const client = new ServerEventsClient("/", channels, {
    handlers: {
        onConnect: (sub:ServerEventConnect) => {  // Successful SSE connection
            console.log("You've connected! welcome " + sub.displayName);
        },
        onJoin: (msg:ServerEventJoin) => {        // User has joined subscribed channel
            console.log("Welcome, " + msg.displayName);
        },
        onLeave: (msg:ServerEventLeave) => {      // User has left subscribed channel
            console.log(user.displayName + " has left the building");
        },
        onUpdate: (msg:ServerEventUpdate) => {    // User's subscribed channels have changed
            console.log(user.displayName + " channels subscription were updated");
        },        
        onMessage: (msg:ServerEventMessage) => {} // Invoked for each other message
        //... Register custom handlers
        CustomMessage: (msg:CustomMessage) = {}   // Handle CustomMessage Request DTO
    },
    receivers: { 
        //... Register any receivers
        tv: {
            watch: function (id) {                 // Handle 'tv.watch {url}' messages 
                var el = document.querySelector("#tv");
                if (id.indexOf('youtu.be') >= 0) {
                    var v = splitOnLast(id, '/')[1];
                    el.innerHTML = templates.youtube.replace("{id}", v);
                } else {
                    el.innerHTML = templates.generic.replace("{id}", id);
                }
                el.style.display = 'block'; 
            },
            off: function () {                     // Hanndle 'tv.off' messages
                var el = document.querySelector("#tv");
                el.style.display = 'none';
                el.innerHTML = '';
            }
        }
    }
}).start();
```

When publishing a DTO Type for your Server Events message, your clients will be able to benefit from 
the generated DTOs in [TypeScript ServiceStack References](/typescript-add-servicestack-reference).

## ServiceStackIDEA plugin

<img align="right" src="https://raw.githubusercontent.com/ServiceStack/Assets/master/img/servicestackidea/supported-ides.png" />
ServiceStackIDEA is a plugin for JetBrains IntelliJ based IDEs to simplify development of client applications for ServiceStack services with integrated support for Add ServiceStack Reference feature.

ServiceStackIDEA now supports many of the most popular JetBrains IDEs including:

 - WebStorm, RubyMine, PhpStorm & PyCharm
   - TypeScript
 - IntelliJ
   - Java, Kotlin and TypeScript

### TypeScript Support

![](https://raw.githubusercontent.com/ServiceStack/Assets/master/img/servicestackidea/webstorm-add-typescript.png)

By right clicking on any folder in your Project explorer, you can add a TypeScript reference by simply providing any based URL of your ServiceStack server.

![](https://raw.githubusercontent.com/ServiceStack/Assets/7474c03bdb0ea1982db2e7be57567ad1b8a4ad38/img/servicestackidea/add-typescript-ref.png)

Once this file as been added to your project, you can update your service DTOs by right clicking `Update ServiceStack Reference` or using the light bulb action (`Alt+Enter` by default).

![](https://raw.githubusercontent.com/ServiceStack/Assets/master/img/servicestackidea/webstorm-update-typescript.png)

This now means you can integrate with a ServiceStack service easily from your favorite JetBrains IDE when working with TypeScript!

#### Install ServiceStack IDEA from the Plugin repository

The ServiceStack IDEA is now available to install directly from within a supported IDE Plugins Repository, to Install Go to: 

 1. `File -> Settings...` Main Menu Item
 2. Select **Plugins** on left menu then click **Browse repositories...** at bottom
 3. Search for **ServiceStack** and click **Install plugin**
 4. Restart to load the installed ServiceStack IDEA plugin

![](https://raw.githubusercontent.com/ServiceStack/Assets/master/img/servicestackidea/android-plugin-download.gif)


## Troubleshooting

### Enabling TypeScript async/await 

To make API requests using TypeScript's async/await feature you'll need to create a TypeScript `tsconfig.json` config file that imports ES6 promises and W3C fetch definitions with:

```json
{
  "compilerOptions": {
    "target": "es5",
    "module": "commonjs",
    "lib": [ "es2015", "dom" ]
  }
}
```


# ES6 Class Add ServiceStack Reference
Source: https://docs.servicestack.net/javascript-add-servicestack-reference

In addition to [TypeScript](/typescript-add-servicestack-reference) support for generating typed Data Transfer Objects (DTOs), JavaScript is now supported in the form of [JSDoc](https://jsdoc.app) annotated typed ES6 classes that can be referenced natively from [JavaScript Modules](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules).

### Reference directly in JavaScript Modules

Unlike TypeScript, the JavaScript ES6 class DTOs can be referenced directly in a browser as-is, removing the need to keep your DTOs in sync with extra tooling by direct referencing them in a JavaScript Module:

```html
<script type="module">
import { Hello } from '/types/mjs'
</script>
```

Then to make typed API Requests from web pages, you need only need to reference an ES Module (.mjs) build of the dependency-free [@servicestack/client](https://github.com/ServiceStack/servicestack-client) library which can be sourced directly from a npm CDN:

```html
<script type="module">
import { JsonServiceClient } from 'https://unpkg.com/@servicestack/client@2/dist/servicestack-client.min.mjs'
import { Hello } from '/types/mjs'

const client = new JsonServiceClient()

const api = client.api(new Hello({ name:'World' }))
if (api.succeeded) {
    console.log(api.response)
}
</script>
```

### Import Maps

Although we recommend using an [importmap](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script/type/importmap) 
to specify where to load **@servicestack/client** from, e.g:

```html
<script async src="https://ga.jspm.io/npm:es-module-shims@1.6.3/dist/es-module-shims.js"></script><!--safari-->
<script type="importmap">
{
    "imports": {
        "@servicestack/client":"https://unpkg.com/@servicestack/client@2/dist/servicestack-client.min.mjs"
    }
}
</script>
```

### ImportMap in Razor Pages or MVC

Razor Pages or MVC projects can use `@Html.ImportMap()` in **_Layout.cshtml** to use different builds for development and production, e.g:

```csharp
@if (Context.Request.Headers.UserAgent.Any(x => x.Contains("Safari") && !x.Contains("Chrome")))
{
    <script async src="https://ga.jspm.io/npm:es-module-shims@1.6.3/dist/es-module-shims.js"></script>
}
@Html.ImportMap(new()
{
    ["@servicestack/client"] = ("/js/servicestack-client.mjs", "/js/servicestack-client.min.mjs"),
})
```

### Usage

This lets us reference the **@servicestack/client** package name in our source code instead of its physical location:
    
```html
<input type="text" id="txtName">
<div id="result"></div>
```

```html
<script type="module">
import { JsonServiceClient, $1, on } from '@servicestack/client'
import { Hello } from '/types/mjs'

const client = new JsonServiceClient()
on('#txtName', {
    async keyup(el) {
        const api = await client.api(new Hello({ name:el.target.value }))
        $1('#result').innerHTML = api.response.result
    }
})
</script>
```

### Enable static analysis and intelli-sense 

For better IDE intelli-sense during development, save the annotated Typed DTOs to disk with the [x dotnet tool](/dotnet-tool):

:::sh
x mjs
:::

Then reference it instead to enable IDE static analysis when calling Typed APIs from JavaScript:

```js
import { Hello } from '/js/dtos.mjs'
client.api(new Hello({ name }))
```
    
To also enable static analysis for **@servicestack/client**, install the dependency-free library as a dev dependency:
    
:::sh
npm install -D @servicestack/client
:::

Where only its TypeScript definitions are used by the IDE during development to enable its type-checking and intelli-sense.

::include npx-get-dtos.md::

### Rich intelli-sense support

Where you'll be able to benefit from rich intelli-sense support in smart IDEs like [Rider](https://www.jetbrains.com/rider/) for 
both the client library:

![](/img/pages/mix/init-rider-ts-client.png)

As well as your App's server generated DTOs:

![](/img/pages/release-notes/v6.6/mjs-intellisense.png)

## Add ServiceStack Reference

A new ServiceStack reference containing the APIs typed DTOs can be added using the **BaseUrl** of the ServiceStack App, e.g:

:::sh
`x mjs https://localhost:5001`
:::

### Update ServiceStack References

All existing ServiceStack References can later be updated with:

:::sh
x mjs
:::


## DTO Customization Options

In most cases you'll just use the generated JavaScript DTO's as-is, however you can further customize how
the DTOs are generated by overriding the default options.

The header in the generated DTOs show the different options JavaScript types support with their
defaults. Default values are shown with the comment prefix of `//`. To override a value, remove the `//`
and specify the value to the right of the `:`. Any uncommented value will be sent to the server to override
any server defaults.

The DTO comments allows for customizations for how DTOs are generated. The default options that were used
to generate the DTOs are repeated in the header comments of the generated DTOs, options that are preceded
by a TypeScript comment `//` are defaults from the server, any uncommented value will be sent to the server
to override any server defaults.

```js
/* Options:
Date: 2025-06-04 09:52:13
Version: 8.80
Tip: To override a DTO option, remove "//" prefix before updating
BaseUrl: https://blazor-vue.web-templates.io

//AddServiceStackTypes: True
//AddDocAnnotations: True
//AddDescriptionAsComments: True
//IncludeTypes: 
//ExcludeTypes: 
//DefaultImports: 
*/
```

We'll go through and cover each of the above options to see how they affect the generated DTO's:

### Change Default Server Configuration

The above defaults are also overridable on the ServiceStack Server by modifying the `NativeTypesFeature` Plugin, e.g:

```csharp
//Server example in CSharp
var nativeTypes = this.GetPlugin<NativeTypesFeature>();
nativeTypes.MetadataTypesConfig.AddDescriptionAsComments = false;
...
```

We'll go through and cover each of the above options to see how they affect the generated DTO's:

### IncludeTypes

Is used as a Whitelist to specify only the types you would like to have code-generated:

```
/* Options:
IncludeTypes: Hello, HelloResponse
```

Will only generate `Hello` and `HelloResponse` DTOs:

```csharp
export class Hello {
    /** @param {{name?:string}} [init] */
    constructor(init) { Object.assign(this, init) }
    /** @type {string} */
    name;
    getTypeName() { return 'Hello' }
    getMethod() { return 'POST' }
    createResponse() { return new HelloResponse() }
}

export class HelloResponse {
    /** @param {{result?:string,responseStatus?:ResponseStatus}} [init] */
    constructor(init) { Object.assign(this, init) }
    /** @type {string} */
    result;
    /** @type {ResponseStatus} */
    responseStatus;
}
```

#### Include Generic Types

Use .NET's Type Name to include Generic Types, i.e. the Type name separated by the backtick followed by the number of generic arguments, e.g:

```
IncludeTypes: IReturn`1,MyPair`2
```

#### Include Request DTO and its dependent types

You can include a Request DTO and all its dependent types with a `.*` suffix on the Request DTO, e.g:

```
/* Options:
IncludeTypes: GetTechnology.*
```

Which will include the `GetTechnology` Request DTO, the `GetTechnologyResponse` Response DTO and all Types that they both reference.

#### Include All Types within a C# namespace

If your DTOs are grouped into different namespaces they can be all included using the `/*` suffix, e.g:

```
/* Options:
IncludeTypes: MyApp.ServiceModel.Admin/*
```

This will include all DTOs within the `MyApp.ServiceModel.Admin` C# namespace.

#### Include All Services in a Tag Group

Services [grouped by Tag](/api-design#group-services-by-tag) can be used in the `IncludeTypes` where tags can be specified using braces in the format `{tag}` or `{tag1,tag2,tag3}`, e.g:

```
/* Options:
IncludeTypes: {web,mobile}
```

Or individually:

```
/* Options:
IncludeTypes: {web},{mobile}
```

### ExcludeTypes
Is used as a Blacklist to specify which types you would like excluded from being generated:

```
/* Options:
ExcludeTypes: GetTechnology,GetTechnologyResponse
```

Will exclude `GetTechnology` and `GetTechnologyResponse` DTOs from being generated.

### Cache

When using `/types/mjs` directly from a `script` tag, the server will cache the result by default when not running in [DebugMode](/debugging#debugmode).

This caching process can be disabled if required by using **?cache=false**.


# Python Add ServiceStack Reference
Source: https://docs.servicestack.net/python-add-servicestack-reference

![ServiceStack and Python Banner](./img/pages/servicestack-reference/python-reference.png)

ServiceStack's **Add ServiceStack Reference** feature allows clients to generate Native Types from directly within PyCharm using [ServiceStack IntelliJ Plugin](https://plugins.jetbrains.com/plugin/7749-servicestack/) - providing a simple way to give clients typed access to your ServiceStack Services.

<lite-youtube class="w-full mx-4 my-4" width="560" height="315" videoid="WjbhfH45i5k" style="background-image: url('https://img.youtube.com/vi/WjbhfH45i5k/maxresdefault.jpg')"></lite-youtube>

### First class development experience

[Python](https://python.org) is one of the worlds most popular programming languages thanks to its ease of use and comprehensive libraries which sees it excels in many industries from education where it's often the first language taught in school to data science, machine learning and AI where it's often the dominant language used. To maximize the experience for calling ServiceStack APIs within these environments ServiceStack now supports Python as a 1st class Add ServiceStack Reference supported language which gives Python developers an end-to-end typed API for consuming ServiceStack APIs, complete with IDE integration in [PyCharm](https://www.jetbrains.com/pycharm/) as well as [built-in support in x dotnet tool](/dotnet-tool#addupdate-servicestack-references) to generate Python DTOs for a remote ServiceStack instance from a single command-line.

### Ideal idiomatic Typed Message-based API

To maximize the utility of Python DTOs and enable richer tooling support, Python DTOs are generated as [dataclasses](https://docs.python.org/3/library/dataclasses.html) with support for [JSON serialization](https://pypi.org/project/dataclasses-json/) and annotated with Python 3 [type hints](https://docs.python.org/3/library/typing.html) - that's invaluable when scaling large Python code-bases and greatly improves discoverability of a remote API. DTOs are also enriched with interface markers through Python's multiple inheritance support which enables its optimal end-to-end typed API:

The Python DTOs and `JsonServiceClient` library follow Python's [PEP 8's naming conventions](https://www.python.org/dev/peps/pep-0008/) so they'll naturally fit into existing Python code bases. Here's a sample of [techstacks.io](https://techstacks.io) generated Python DTOs containing string and int Enums, an example AutoQuery and a standard Request & Response DTO showcasing the rich typing annotations and naming conventions used:

```python
class TechnologyTier(str, Enum):
    PROGRAMMING_LANGUAGE = 'ProgrammingLanguage'
    CLIENT = 'Client'
    HTTP = 'Http'
    SERVER = 'Server'
    DATA = 'Data'
    SOFTWARE_INFRASTRUCTURE = 'SoftwareInfrastructure'
    OPERATING_SYSTEM = 'OperatingSystem'
    HARDWARE_INFRASTRUCTURE = 'HardwareInfrastructure'
    THIRD_PARTY_SERVICES = 'ThirdPartyServices'

class Frequency(IntEnum):
    DAILY = 1
    WEEKLY = 7
    MONTHLY = 30
    QUARTERLY = 90

# @Route("/technology/search")
@dataclass_json(letter_case=LetterCase.CAMEL, undefined=Undefined.EXCLUDE)
@dataclass
class FindTechnologies(QueryDb2[Technology, TechnologyView], IReturn[QueryResponse[TechnologyView]], IGet):
    ids: Optional[List[int]] = None
    name: Optional[str] = None
    vendor_name: Optional[str] = None
    name_contains: Optional[str] = None
    vendor_name_contains: Optional[str] = None
    description_contains: Optional[str] = None

# @Route("/orgs/{Id}", "PUT")
@dataclass_json(letter_case=LetterCase.CAMEL, undefined=Undefined.EXCLUDE)
@dataclass
class UpdateOrganization(IReturn[UpdateOrganizationResponse], IPut):
    id: int = 0
    slug: Optional[str] = None
    name: Optional[str] = None
    description: Optional[str] = None
    color: Optional[str] = None
    text_color: Optional[str] = None
    link_color: Optional[str] = None
    background_color: Optional[str] = None
    background_url: Optional[str] = None
    logo_url: Optional[str] = None
    hero_url: Optional[str] = None
    lang: Optional[str] = None
    delete_posts_with_report_count: int = 0
    disable_invites: Optional[bool] = None
    default_post_type: Optional[str] = None
    default_subscription_post_types: Optional[List[str]] = None
    post_types: Optional[List[str]] = None
    moderator_post_types: Optional[List[str]] = None
    technology_ids: Optional[List[int]] = None

@dataclass_json(letter_case=LetterCase.CAMEL, undefined=Undefined.EXCLUDE)
@dataclass
class UpdateOrganizationResponse:
    response_status: Optional[ResponseStatus] = None
```

The smart Python `JsonServiceClient` available in the [servicestack](https://pypi.org/project/servicestack/) pip and conda packages enabling the same 
productive, typed API development experience available in our other 1st-class supported client platforms. 

Using [dataclasses](https://docs.python.org/3/library/dataclasses.html) enables DTOs to be populated using a single constructor expression utilizing named parameters which together with the generic `JsonServiceClient` enables end-to-end typed API Requests in a single LOC:

```python
from .dtos import *
from servicestack import JsonServiceClient

client = JsonServiceClient("https://test.servicestack.net")

response: HelloResponse = client.get(Hello(name="World"))
```

::: info
The `HelloResponse` optional type hint doesn't change runtime behavior but enables static analysis tools and IDEs like PyCharm to provide rich intelli-sense and development time feedback
:::

## Installation

The only requirements for Python apps to perform typed API Requests are the generated Python DTOs and the generic `JsonServiceClient` which can be installed globally or in a virtual Python environment using [Python's pip](https://pypi.org/project/pip/):

:::sh
pip install servicestack
:::

Or if preferred can be installed with [conda](https://conda.io):

:::sh
conda install conda-build.
:::

 - Add conda-forge as channel using `conda config --add channels conda-forge`
 - On root directory run `conda build .`

### PyCharm ServiceStack Plugin

Python developers of [PyCharm](https://www.jetbrains.com/pycharm/) Professional and [FREE Community Edition](https://www.jetbrains.com/pycharm/features/#chooseYourEdition) can get a simplified development experience for consuming ServiceStack Services by installing the [ServiceStack Plugin](https://plugins.jetbrains.com/plugin/7749-servicestack) from the JetBrains Marketplace:

[![](./img/pages/servicestack-reference/pycharm-servicestack-plugin.png)](https://plugins.jetbrains.com/plugin/7749-servicestack)

Where you'll be able to right-click on a directory and click on **ServiceStack Reference** on the context menu:

![](./img/pages/servicestack-reference/pycharm-add-servicestack-reference.png)

To launch the **Add Python ServiceStack Reference** dialog where you can enter the remote URL of the ServiceStack endpoint you wish to call to generate the Typed Python DTOs for all APIs which by default will saved to `dtos.py`:

![](./img/pages/servicestack-reference/pycharm-add-servicestack-reference-dialog.png)

Then just import the DTOs and `JsonServiceClient` to be able to consume any of the remote ServiceStack APIs:

```python
from .dtos import *
from servicestack import JsonServiceClient

client = JsonServiceClient("https://techstacks.io")

response = client.send(FindTechnologies(
    ids=[1, 2, 4, 6],
    vendor_name="Google",
    take=10))
```

If any of the the remote APIs change their DTOs can be updated by right-clicking on `dtos.py` and clicking **Update ServiceStack Reference**:

![](./img/pages/servicestack-reference/pycharm-update-servicestack-reference.png)

### Simple command-line utility for Python

Developers using other Python IDEs and Text Editors like VS Code can utilize the cross-platform [`x` command line utility](/dotnet-tool) for generating Python DTOs from the command-line.

To install first install the [latest .NET SDK](https://dotnet.microsoft.com/download) for your OS then install the [`x` dotnet tool](/dotnet-tool) with:

:::sh
dotnet tool install --global x 
:::

::include npx-get-dtos.md::

### Adding a ServiceStack Reference

To Add a Python ServiceStack Reference just call `x python` with the URL of a remote ServiceStack instance:

:::sh
x python https://techstacks.io
:::

Result:

```
Saved to: dtos.py
```

Calling `x python` with just a URL will save the DTOs using the Host name, you can override this by specifying a FileName as the 2nd argument:

:::sh
x python https://techstacks.io Tech
:::

Result:

```
Saved to: Tech.dtos.py
```

### Updating a ServiceStack Reference

To Update an existing ServiceStack Reference, call `x python` with the Filename:

:::sh
x python dtos.py
:::

Result:

```
Updated: dtos.py
```

Which will update the File with the latest Python Server DTOs from [techstacks.io](https://techstacks.io). You can also customize how DTOs are generated by uncommenting the [Python DTO Customization Options](/#dto-customization-options) and updating them again.

### Updating all Python DTOs

Calling `x python` without any arguments will update all Python DTOs in the current directory:

:::sh
x python
:::

Result:

```
Updated: Tech.dtos.py
Updated: dtos.py
```

### Smart Generic JsonServiceClient

The generic `JsonServiceClient` is a 1st class client with the same rich featureset of the smart ServiceClients in other [1st class supported languages](/add-servicestack-reference#supported-languages) sporting a terse, typed flexible API with support for additional untyped params, custom URLs and HTTP Methods, dynamic response types including consuming API responses in raw text and binary data formats. Clients can be decorated to support generic functionality using instance and static Request, Response and Exception Filters.

It includes built-in support for a number of [ServiceStack Auth options](/auth/authentication-and-authorization) including [HTTP Basic Auth](https://en.wikipedia.org/wiki/Basic_access_authentication) and stateless Bearer Token Auth Providers like [API Key](/auth/api-key-authprovider) and [JWT Auth](/auth/jwt-authprovider) as well as [stateful Sessions](/auth/sessions) used by the popular **credentials** Auth Provider and an `on_authentication_required` callback for enabling custom authentication methods. The built-in auth options include auto-retry support for transparently authenticating and retrying authentication required requests as well as [Refresh Token Cookie](/auth/jwt-authprovider#refresh-token-cookies-supported-in-all-service-clients) support where it will transparently fetch new JWT Bearer Tokens automatically behind-the-scenes for friction-less stateless JWT support.

A snapshot of these above features is captured in the high-level public API below:

```python
class JsonServiceClient:
    base_url: str
    reply_base_url: str
    oneway_base_url: str
    headers: Optional[Dict[str, str]]
    bearer_token: Optional[str]
    refresh_token: Optional[str]
    refresh_token_uri: Optional[str]
    username: Optional[str]
    password: Optional[str]

    on_authentication_required: Callable[[], None]

    global_request_filter: Callable[[SendContext], None]  # static
    request_filter: Callable[[SendContext], None]

    global_response_filter: Callable[[Response], None]  # static
    response_filter: Callable[[Response], None]

    exception_filter: Callable[[Response, Exception], None]
    global_exception_filter: Callable[[Response, Exception], None]

    def __init__(self, base_url)

    def set_credentials(self, username, password)
    @property def token_cookie(self)
    @property def refresh_token_cookie(self)

    def get(self, request: IReturn[T], args: Dict[str, Any] = None) -> T
    def post(self, request: IReturn[T], body: Any = None, args: Dict[str, Any] = None) -> T
    def put(self, request: IReturn[T], body: Any = None, args: Dict[str, Any] = None) -> T
    def patch(self, request: IReturn[T], body: Any = None, args: Dict[str, Any] = None) -> T
    def delete(self, request: IReturn[T], args: Dict[str, Any] = None) -> T
    def options(self, request: IReturn[T], args: Dict[str, Any] = None) -> T
    def head(self, request: IReturn[T], args: Dict[str, Any] = None) -> T
    def send(self, request, method: Any = None, body: Any = None, args: Dict[str, Any] = None)

    def get_url(self, path: str, response_as: Type, args: Dict[str, Any] = None)
    def delete_url(self, path: str, response_as: Type, args: Dict[str, Any] = None)
    def options_url(self, path: str, response_as: Type, args: Dict[str, Any] = None)
    def head_url(self, path: str, response_as: Type, args: Dict[str, Any] = None)
    def post_url(self, path: str, body: Any = None, response_as: Type = None, args: Dict[str, Any] = None)
    def put_url(self, path: str, body: Any = None, response_as: Type = None, args: Dict[str, Any] = None)
    def patch_url(self, path: str, body: Any = None, response_as: Type = None, args: Dict[str, Any] = None)
    def send_url(self, path: str, method: str = None, response_as: Type = None, body: Any = None,
                 args: Dict[str, Any] = None)

    def send_all(self, request_dtos: List[IReturn[T]])  # Auto Batch Reply Requests
    def send_all_oneway(self, request_dtos: list)       # Auto Batch Oneway Requests
```

### Change Default Server Configuration

The above defaults are also overridable on the ServiceStack Server by modifying the default config on the `NativeTypesFeature` Plugin, e.g:

```csharp
var nativeTypes = this.GetPlugin<NativeTypesFeature>();
nativeTypes.MetadataTypesConfig.AddResponseStatus = true;
...
```

Python specific functionality can be added by `PythonGenerator`

```python
PythonGenerator.DefaultImports.Add("requests");
```

### Customize DTO Type generation

Additional Python specific customization can be statically configured like `PreTypeFilter`, `InnerTypeFilter` & `PostTypeFilter` (available in all languages) can be used to inject custom code in the generated DTOs output. 

Use the `PreTypeFilter` to generate source code before and after a Type definition, e.g. this will append the `Decorator` class decorator on non enum & interface types:

```csharp
PythonGenerator.PreTypeFilter = (sb, type) => {
    if (!type.IsEnum.GetValueOrDefault() && !type.IsInterface.GetValueOrDefault())
    {
        sb.AppendLine("@Decorator");
    }
};
```

The `InnerTypeFilter` gets invoked just after the Type Definition which can be used to generate common members for all Types and interfaces, e.g:

```csharp
PythonGenerator.InnerTypeFilter = (sb, type) => {
    sb.AppendLine("id:str = str(random.random())[2:]");
};
```

There's also `PrePropertyFilter` & `PostPropertyFilter` for generating source before and after properties, e.g:

```csharp
PythonGenerator.PrePropertyFilter = (sb , prop, type) => {
    if (prop.Name == "Id")
    {
        sb.AppendLine("@IsInt");
    }
};
```

### Emit custom code

To enable greater flexibility when generating complex Typed DTOs, you can use `[Emit{Language}]` attributes to generate code before each type or property.

These attributes can be used to generate different attributes or annotations to enable client validation for different validation libraries in different languages, e.g:

```csharp
[EmitCode(Lang.Python, "# App User")]
[EmitPython("@Validate")]
public class User : IReturn<User>
{
    [EmitPython("@IsNotEmpty", "@IsEmail")]
    [EmitCode(Lang.Swift | Lang.Dart, new[]{ "@isNotEmpty()", "@isEmail()" })]
    public string Email { get; set; }
}
```

Which will generate `[EmitPython]` code in Python DTOs:

```python
# App User
@Validate
@dataclass_json(letter_case=LetterCase.CAMEL, undefined=Undefined.EXCLUDE)
@dataclass
class User:
    @IsNotEmpty
    @IsEmail
    email: Optional[str] = None
```

Whilst the generic `[EmitCode]` attribute lets you emit the same code in multiple languages with the same syntax.

### Python Reference Example

Lets walk through a simple example to see how we can use ServiceStack's Python DTO annotations in our Python JsonServiceClient. Firstly we'll need to add a Python Reference to the remote ServiceStack Service by **right-clicking** on a project folder and clicking on `ServiceStack Reference...` (as seen in the above screenshot).

This will import the remote Services dtos into your local project which looks similar to:

```python
""" Options:
Date: 2025-06-04 09:49:40
Version: 8.71
Tip: To override a DTO option, remove "#" prefix before updating
BaseUrl: https://techstacks.io

#GlobalNamespace: 
#AddServiceStackTypes: True
#AddResponseStatus: False
#AddImplicitVersion: 
#AddDescriptionAsComments: True
#IncludeTypes: 
#ExcludeTypes: 
#DefaultImports: datetime,decimal,marshmallow.fields:*,servicestack:*,typing:*,dataclasses:dataclass/field,dataclasses_json:dataclass_json/LetterCase/Undefined/config,enum:Enum/IntEnum
#DataClass: 
#DataClassJson: 
"""

@dataclass_json(letter_case=LetterCase.CAMEL, undefined=Undefined.EXCLUDE)
@dataclass
class GetTechnologyResponse:
    created: datetime.datetime = datetime.datetime(1, 1, 1)
    technology: Optional[Technology] = None
    technology_stacks: Optional[List[TechnologyStack]] = None
    response_status: Optional[ResponseStatus] = None

# @Route("/technology/{Slug}")
@dataclass_json(letter_case=LetterCase.CAMEL, undefined=Undefined.EXCLUDE)
@dataclass
class GetTechnology(IReturn[GetTechnologyResponse], IRegisterStats, IGet):
    slug: Optional[str] = None
```

In keeping with idiomatic style of local `.py` sources, generated types are not wrapped within a module by default. This lets you reference the types you want directly using normal import destructuring syntax:

```python
from .dtos import GetTechnology, GetTechnologyResponse
```

Or import all Types into your preferred variable namespace with:

```python
from .dtos import *

request = GetTechnology()
```

### Making Typed API Requests

Making API Requests in Python is the same as all other [ServiceStack's Service Clients](/clients-overview) by sending a populated Request DTO using a `JsonServiceClient` which returns typed Response DTO.

So the only things we need to make any API Request is the `JsonServiceClient` from the `servicestack` package and any DTO's we're using from generated Python ServiceStack Reference, e.g:

```python
from .dtos import GetTechnology, GetTechnologyResponse
from servicestack import JsonServiceClient

client = JsonServiceClient("https://techstacks.io")

request = GetTechnology()
request.slug = "ServiceStack"

r: GetTechnologyResponse = client.get(request)  # typed to GetTechnologyResponse
tech = r.technology                             # typed to Technology

print(f"{tech.name} by {tech.vendor_name} ({tech.product_url})")
print(f"`{tech.name} TechStacks: {r.technology_stacks}")
```

### Constructors Initializer

All Python Reference dataclass DTOs also implements **__init__** making them much nicer to populate using a constructor expression with named params syntax we're used to in C#, so instead of:

```python
request = Authenticate()
request.provider = "credentials"
request.user_name = user_name
request.password = password
request.remember_me = remember_me
response = client.post(request)
```

You can populate DTOs with a single constructor expression without any loss of Python's Typing benefits:

```python
response = client.post(Authenticate(
    provider='credentials',
    user_name=user_name,
    password=password,
    remember_me=remember_me))
```

### Sending additional arguments with Typed API Requests

Many AutoQuery Services utilize [implicit conventions](/autoquery/rdbms#implicit-conventions) to query fields that aren't explicitly defined on AutoQuery Request DTOs, these can be queried by specifying additional arguments with the typed Request DTO, e.g:

```python
request = FindTechStacks()

r:QueryResponse[TechnologyStackView] = client.get(request, args={"vendorName": "ServiceStack"})
```

### Making API Requests with URLs

In addition to making Typed API Requests you can also call Services using relative or absolute urls, e.g:

```python
client.get("/technology/ServiceStack", response_as=GetTechnologyResponse)

client.get("https://techstacks.io/technology/ServiceStack", response_as=GetTechnologyResponse)

# https://techstacks.io/technology?Slug=ServiceStack
args = {"slug":"ServiceStack"}
client.get("/technology", args=args, response_as=GetTechnologyResponse) 
```

as well as POST Request DTOs to custom urls:

```python
client.post_url("/custom-path", request, args={"slug":"ServiceStack"})

client.post_url("http://example.org/custom-path", request)
```

### Raw Data Responses

The `JsonServiceClient` also supports Raw Data responses like `string` and `byte[]` which also get a Typed API once declared on Request DTOs using the `IReturn<T>` marker:

```csharp
public class ReturnString : IReturn<string> {}
public class ReturnBytes : IReturn<byte[]> {}
```

Which can then be accessed as normal, with their Response typed to a JavaScript `str` or `bytes` for raw `byte[]` responses:

```python
str:str = client.get(ReturnString())

data:bytes = client.get(ReturnBytes())
```

### Authenticating using Basic Auth

Basic Auth support is implemented in `JsonServiceClient` and follows the same API made available in the C# Service Clients where the `userName/password` properties can be set individually, e.g:

```python
client = JsonServiceClient(baseUrl)
client.username = user
client.password = pass

response = client.get(SecureRequest())
```

Or use `client.set_credentials()` to have them set both together.

### Authenticating using Credentials

Alternatively you can authenticate using userName/password credentials by 
[adding a Python Reference](#add-python-reference) 
to your remote ServiceStack Instance and sending a populated `Authenticate` Request DTO, e.g:

```python
request = Authenticate()
request.provider = "credentials"
request.user_name = user_name
request.password = password
request.remember_me = true

response:AuthenticateResponse = client.post(request)
```

This will populate the `JsonServiceClient` with [Session Cookies](/auth/sessions#cookie-session-ids) 
which will transparently be sent on subsequent requests to make authenticated requests.

### Authenticating using JWT

Use the `bearer_token` property to Authenticate with a [ServiceStack JWT Provider](/auth/jwt-authprovider) using a JWT Token:

```python
client.bearer_token = jwt
```

Alternatively you can use just a [Refresh Token](/auth/jwt-authprovider#refresh-tokens) instead:

```python
client.refresh_token = refresh_token
```

Where the client will automatically fetch a new JWT Bearer Token using the Refresh Token for authenticated requests.

### Authenticating using an API Key

Use the `bearer_token` property to Authenticate with an [API Key](/auth/api-key-authprovider):

```python
client.bearer_token = api_key
```

### Transparently handle 401 Unauthorized Responses

If the server returns a 401 Unauthorized Response either because the client was Unauthenticated or the 
configured Bearer Token or API Key used had expired or was invalidated, you can use `onAuthenticationRequired`
callback to re-configure the client before automatically retrying the original request, e.g:

```python
auth_client = JsonServiceClient(AUTH_URL)

client.on_authentication_required = lambda c=client, a=auth_client: [
    a.set_credentials(username, password),
    client.set_bearer_token(cast(AuthenticateResponse, a.get(Authenticate())).bearer_token)
]

# Automatically retries requests returning 401 Responses with new bearerToken
response = client.get(Secured())
```

### Automatically refresh Access Tokens

With the [Refresh Token support in JWT](/auth/jwt-authprovider#refresh-tokens) 
you can use the `refresh_token` property to instruct the Service Client to automatically fetch new JWT Tokens behind the scenes before automatically retrying failed requests due to invalid or expired JWTs, e.g:

```python
# Authenticate to get new Refresh Token
auth_client = JsonServiceClient(AUTH_URL)
auth_client.username = username
auth_client.password = password
auth_response = auth_client.get(Authenticate())

# Configure client with RefreshToken
client.refresh_token = auth_response.refresh_token

# Call authenticated Services and clients will automatically retrieve new JWT Tokens as needed
response = client.get(Secured())
```

Use the `refresh_token_uri` property when refresh tokens need to be sent to a different ServiceStack Server, e.g:

```python
client.refresh_token = refresh_token
client.refresh_token_uri = AUTH_URL + "/access-token"
```

### Uploading Files

The `post_file_with_request` method can be used to upload a file with an API Request.

### Python Speech to Text

Here's an example calling [AI Server's](/ai-server/) `SpeechToText` API:

```python
with open("files/audio.wav", "rb") as audio:
  response = client.post_file_with_request(SpeechToText(), 
    UploadFile(field_name="audio", file_name="audio.wav", content_type="audio/wav", stream=audio))
```

To upload multiple files use `post_files_with_request`.

## DTO Customization Options 

In most cases you'll just use the generated Python DTO's as-is, however you can further customize how the DTO's are generated by overriding the default options.

The header in the generated DTO's show the different options Python native types support with their defaults. Default values are shown with the comment prefix of `//`. To override a value, remove the `#` and specify the value to the right of the `:`. Any uncommented value will be sent to the server to override any server defaults.

The DTO comments allows for customizations for how DTOs are generated. The default options that were used to generate the DTO's are repeated in the header comments of the generated DTOs, options that are preceded by a Python comment `#` are defaults from the server, any uncommented value will be sent to the server 
to override any server defaults.

```python
""" Options:
Date: 2021-08-15 08:26:46
Version: 5.111
Tip: To override a DTO option, remove "#" prefix before updating
BaseUrl: https://techstacks.io

#GlobalNamespace: 
#MakePropertiesOptional: False
#AddServiceStackTypes: True
#AddResponseStatus: False
#AddImplicitVersion: 
#AddDescriptionAsComments: True
#IncludeTypes: 
#ExcludeTypes: 
#DefaultImports: datetime,decimal,marshmallow.fields:*,servicestack:*,typing:*,dataclasses:dataclass/field,dataclasses_json:dataclass_json/LetterCase/Undefined/config,enum:Enum/IntEnum
#DataClass: 
#DataClassJson: 
"""
```

We'll go through and cover each of the above options to see how they affect the generated DTO's:

### Change Default Server Configuration

The above defaults are also overridable on the ServiceStack Server by modifying the default config on the `NativeTypesFeature` Plugin, e.g:

```csharp
//Server example in C#
var nativeTypes = this.GetPlugin<NativeTypesFeature>();
nativeTypes.MetadataTypesConfig.AddResponseStatus = true;
...
```

We'll go through and cover each of the above options to see how they affect the generated DTO's:

### GlobalNamespace

As Python lacks the concept of namespaces this just emits a comment with the namespace name:

```python
# module dtos
```

### AddResponseStatus

Automatically add a `response_status` property on all Response DTO's, regardless if it wasn't already defined:

```python
class GetTechnologyResponse:
    ...
    response_status: Optional[ResponseStatus] = None
```

### AddImplicitVersion

Lets you specify the Version number to be automatically populated in all Request DTO's sent from the client: 

```python
class GetTechnology(IReturn[GetTechnologyResponse], IRegisterStats, IGet):
    version: int = 1
    ...
```

This lets you know what Version of the Service Contract that existing clients are using making it easy to implement ServiceStack's [recommended versioning strategy](http://stackoverflow.com/a/12413091/85785). 

### IncludeTypes

Is used as a Whitelist to specify only the types you would like to have code-generated:

```
""" Options:
IncludeTypes: GetTechnology,GetTechnologyResponse
```

Will only generate `GetTechnology` and `GetTechnologyResponse` DTO's:

```python
class GetTechnologyResponse:
    ...
class GetTechnology:
    ...
```

#### Include Generic Types

Use .NET's Type Name to include Generic Types, i.e. the Type name separated by the backtick followed by the number of generic arguments, e.g:

```
IncludeTypes: IReturn`1,MyPair`2
```

#### Include Request DTO and its dependent types

You can include a Request DTO and all its dependent types with a `.*` suffix on the Request DTO, e.g:

```
""" Options:
IncludeTypes: GetTechnology.*
```

Which will include the `GetTechnology` Request DTO, the `GetTechnologyResponse` Response DTO and all Types that they both reference.

#### Include All Types within a C# namespace

If your DTOs are grouped into different namespaces they can be all included using the `/*` suffix, e.g:

```
""" Options:
IncludeTypes: MyApp.ServiceModel.Admin/*
```

This will include all DTOs within the `MyApp.ServiceModel.Admin` C# namespace. 

#### Include All Services in a Tag Group

Services [grouped by Tag](/api-design#group-services-by-tag) can be used in the `IncludeTypes` where tags can be specified using braces in the format `{tag}` or `{tag1,tag2,tag3}`, e.g:

```
""" Options:
IncludeTypes: {web,mobile}
```

Or individually:

```
""" Options:
IncludeTypes: {web},{mobile}
```

### ExcludeTypes
Is used as a Blacklist to specify which types you would like excluded from being generated:

```
""" Options:
ExcludeTypes: GetTechnology,GetTechnologyResponse
```

Will exclude `GetTechnology` and `GetTechnologyResponse` DTOs from being generated.

### DefaultImports

The `module:Symbols` short-hand syntax can be used for specifying additional imports in your generated Python DTO. There are 3 different syntaxes for specifying different Python imports:

```python
""" Options:
...
DefaultImports: datetime,typing:*,enum:Enum/IntEnum
"""
```

Which will generate the popular import form of:

```python
import datetime
from typing import *
from enum import Enum, IntEnum
```

### DataClass

Change what `dataclass` decorator is used, e.g:

```python
""" Options:
...
DataClass: init=False
"""
```

Will decorate every DTO with:

```python
@dataclass(init=False)
class GetTechnology(IReturn[GetTechnologyResponse], IRegisterStats, IGet):
    slug: Optional[str] = None
```


### DataClassJson

Change what `dataclass_json` decorator is used, e.g:

```python
""" Options:
...
DataClassJson: letter_case=LetterCase.PASCAL
"""
```

Will decorate every DTO with:

```python
@dataclass_json(letter_case=LetterCase.PASCAL)
class GetTechnology(IReturn[GetTechnologyResponse], IRegisterStats, IGet):
    slug: Optional[str] = None
```

Which will result in each type being serialized with PascalCase.

## Customize Serialization

The `servicestack` client lib allows for flexible serialization customization where you can change how different .NET Types are serialized and deserialized into native Python types.

To illustrate this we'll walk through how serialization of properties containing binary data to Base64 is implemented.

First we specify the Python DTO generator to emit `bytes` type hint for the popular .NET binary data types:

```csharp
PythonGenerator.TypeAliases[typeof(byte[]).Name] = "bytes";
PythonGenerator.TypeAliases[typeof(Stream).Name] = "bytes";
```

In the Python app we can then specify the serializers and deserializers to use for deserializing properties with the `bytes` data type which converts binary data to/from Base64:

```python
from servicestack import TypeConverters

def to_bytearray(value: Optional[bytes]):
    if value is None:
        return None
    return base64.b64encode(value).decode('ascii')

def from_bytearray(base64str: Optional[str]):
    return base64.b64decode(base64str)

TypeConverters.serializers[bytes] = to_bytearray
TypeConverters.deserializers[bytes] = from_bytearray
```

## Inspect Utils

To help clients with inspecting API Responses the `servicestack` library also includes a number of helpful utils to quickly visualizing API outputs.

For a basic indented object graph you can use `dump` to capture and `printdump` to print the output of any API Response, e.g:

```python
from dataclasses import dataclass
from dataclasses_json import dataclass_json, Undefined
from typing import Optional
from servicestack import printdump, printtable

@dataclass_json(undefined=Undefined.EXCLUDE)
@dataclass
class GithubRepo:
    name: str
    description: Optional[str] = None
    homepage: Optional[str] = None
    lang: Optional[str] = field(metadata=config(field_name="language"),default=None)
    watchers: Optional[int] = 0
    forks: Optional[int] = 0

response = requests.get(f'https://api.github.com/orgs/python/repos')
orgRepos = GithubRepo.schema().loads(response.text, many=True)
orgRepos.sort(key=operator.attrgetter('watchers'), reverse=True)

print(f'Top 3 {orgName} Repos:')
printdump(orgRepos[0:3])
```

Output:

```
Top 3 python Repos:
[
    {
        name: mypy,
        description: Optional static typing for Python 3 and 2 (PEP 484),
        homepage: http://www.mypy-lang.org/,
        lang: Python,
        watchers: 9638,
        forks: 1564
    },
    {
        name: peps,
        description: Python Enhancement Proposals,
        homepage: https://www.python.org/dev/peps/,
        lang: Python,
        watchers: 2459,
        forks: 921
    },
    {
        name: typeshed,
        description: Collection of library stubs for Python, with static types,
        homepage: ,
        lang: Python,
        watchers: 1942,
        forks: 972
    }
]
```

For tabular resultsets you can use `table` to capture and `printtable` to print API resultsets in a human-friendly markdown table with an optional `headers` parameter to specify the order and columns to display, e.g:

```python
print(f'\nTop 10 {orgName} Repos:')
printtable(orgRepos[0:10],headers=['name','lang','watchers','forks'])
```

Output:

```
Top 10 python Repos:
+--------------+-----------+------------+---------+
| name         | lang      |   watchers |   forks |
|--------------+-----------+------------+---------|
| mypy         | Python    |       9638 |    1564 |
| peps         | Python    |       2459 |     921 |
| typeshed     | Python    |       1942 |     972 |
| pythondotorg | Python    |       1038 |     432 |
| asyncio      |           |        945 |     178 |
| typing       | Python    |        840 |     130 |
| raspberryio  | Python    |        217 |      38 |
| typed_ast    | C         |        171 |      43 |
| planet       | Python    |        100 |     145 |
| psf-salt     | SaltStack |         87 |      50 |
+--------------+-----------+------------+---------+
```

Alternatively you can use `htmldump` to generate API responses in a HTML UI which is especially useful in [Python Jupyter Notebooks](/jupyter-notebooks-python) to easily visualize API responses, e.g:

[![](./img/pages/apps/jupyterlab-mybinder-techstacks.png)](https://github.com/ServiceStack/jupyter-notebooks/blob/main/techstacks.io-FindTechnologies.ipynb)


# PHP Add ServiceStack Reference
Source: https://docs.servicestack.net/php-add-servicestack-reference

![ServiceStack and PHP Banner](/img/pages/servicestack-reference/php-reference.png)

ServiceStack's **Add ServiceStack Reference** feature allows clients to generate Native Types from directly within PhpStorm using [ServiceStack IntelliJ Plugin](https://plugins.jetbrains.com/plugin/7749-servicestack/) - providing a simple way to give clients typed access to your ServiceStack Services.

<div class="flex justify-center">
    <lite-youtube class="w-full mx-4 my-4" width="560" height="315" videoid="ZLVdaJ38vwc" style="background-image: url('https://img.youtube.com/vi/ZLVdaJ38vwc/maxresdefault.jpg')"></lite-youtube>
</div>

### First class development experience

[PHP](https://www.php.net) is one of the worlds most popular programming languages thanks to its ease of use, 
platform independence, large standard library, flexibility and fast development experience which sees it excels as
a popular language for web development and for development of popular CMS products like WordPress, Drupal and Joomla
thanks to its flexibility, embeddability and ease of customization.

To maximize the experience for calling ServiceStack APIs within these environments ServiceStack now supports PHP as a 
1st class Add ServiceStack Reference supported language which gives PHP developers an end-to-end typed API for consuming 
ServiceStack APIs, complete with IDE integration in [PhpStorm](https://www.jetbrains.com/phpstorm/) as well as 
[built-in support in x dotnet tool](/dotnet-tool#addupdate-servicestack-references) 
to generate Typed and annotated PHP DTOs for a remote ServiceStack instance from a single command-line.

### Ideal idiomatic Typed Message-based API

To maximize the utility of PHP DTOs and enable richer tooling support and greater development experience, PHP DTOs are generated as 
Typed [JsonSerializable](https://www.php.net/manual/en/class.jsonserializable.php) classes with 
[promoted constructors](https://www.php.net/manual/en/language.oop5.decon.php#language.oop5.decon.constructor.promotion)
and annotated with [PHPDoc Types](https://phpstan.org/writing-php-code/phpdoc-types) - that's invaluable when scaling 
large PHP code-bases and greatly improves discoverability of a remote API. DTOs are also enriched with interface markers 
and Annotations which enables its optimal end-to-end typed API:

The PHP DTOs and `JsonServiceClient` library follow 
[PHP naming conventions](https://infinum.com/handbook/wordpress/coding-standards/php-coding-standards/naming) 
so they'll naturally fit into existing PHP code bases. Here's a sample of [techstacks.io](https://techstacks.io) 
generated PHP DTOs containing string and int Enums, an example AutoQuery and a standard Request & Response DTO showcasing 
the rich typing annotations and naming conventions used:

```php
enum TechnologyTier : string
{
    case ProgrammingLanguage = 'ProgrammingLanguage';
    case Client = 'Client';
    case Http = 'Http';
    case Server = 'Server';
    case Data = 'Data';
    case SoftwareInfrastructure = 'SoftwareInfrastructure';
    case OperatingSystem = 'OperatingSystem';
    case HardwareInfrastructure = 'HardwareInfrastructure';
    case ThirdPartyServices = 'ThirdPartyServices';
}

enum Frequency : int
{
    case Daily = 1;
    case Weekly = 7;
    case Monthly = 30;
    case Quarterly = 90;
}

// @Route("/technology/search")
#[Returns('QueryResponse')]
/**
 * @template QueryDb of Technology
 * @template QueryDb1 of TechnologyView
 */
class FindTechnologies extends QueryDb implements IReturn, IGet, JsonSerializable
{
    public function __construct(
        /** @var array<int>|null */
        public ?array $ids=null,
        /** @var string|null */
        public ?string $name=null,
        /** @var string|null */
        public ?string $vendorName=null,
        /** @var string|null */
        public ?string $nameContains=null,
        /** @var string|null */
        public ?string $vendorNameContains=null,
        /** @var string|null */
        public ?string $descriptionContains=null
    ) {
    }

    /** @throws Exception */
    public function fromMap($o): void {
        parent::fromMap($o);
        if (isset($o['ids'])) $this->ids = JsonConverters::fromArray('int', $o['ids']);
        if (isset($o['name'])) $this->name = $o['name'];
        if (isset($o['vendorName'])) $this->vendorName = $o['vendorName'];
        if (isset($o['nameContains'])) $this->nameContains = $o['nameContains'];
        if (isset($o['vendorNameContains'])) $this->vendorNameContains = $o['vendorNameContains'];
        if (isset($o['descriptionContains'])) $this->descriptionContains = $o['descriptionContains'];
    }
    
    /** @throws Exception */
    public function jsonSerialize(): mixed
    {
        $o = parent::jsonSerialize();
        if (isset($this->ids)) $o['ids'] = JsonConverters::toArray('int', $this->ids);
        if (isset($this->name)) $o['name'] = $this->name;
        if (isset($this->vendorName)) $o['vendorName'] = $this->vendorName;
        if (isset($this->nameContains)) $o['nameContains'] = $this->nameContains;
        if (isset($this->vendorNameContains)) $o['vendorNameContains'] = $this->vendorNameContains;
        if (isset($this->descriptionContains)) $o['descriptionContains'] = $this->descriptionContains;
        return empty($o) ? new class(){} : $o;
    }
    public function getTypeName(): string { return 'FindTechnologies'; }
    public function getMethod(): string { return 'GET'; }
    public function createResponse(): mixed { return QueryResponse::create(genericArgs:['TechnologyView']); }
}

// @Route("/orgs/{Id}", "DELETE")
class DeleteOrganization implements IReturnVoid, IDelete, JsonSerializable
{
    public function __construct(
        /** @var int */
        public int $id=0
    ) {
    }

    /** @throws Exception */
    public function fromMap($o): void {
        if (isset($o['id'])) $this->id = $o['id'];
    }
    
    /** @throws Exception */
    public function jsonSerialize(): mixed
    {
        $o = [];
        if (isset($this->id)) $o['id'] = $this->id;
        return empty($o) ? new class(){} : $o;
    }
    public function getTypeName(): string { return 'DeleteOrganization'; }
    public function getMethod(): string { return 'DELETE'; }
    public function createResponse(): void {}
}
```

The smart PHP `JsonServiceClient` available in the [servicestack/client](https://packagist.org/packages/servicestack/client) 
packagist package enables the same productive, typed API development experience available in our other 1st-class supported 
client platforms. 

Using promoted constructors enables DTOs to be populated using a single constructor expression utilizing named parameters 
which together with the generic `JsonServiceClient` enables end-to-end typed API Requests in a single LOC:

```php
use Servicestack\JsonServiceClient;
use dtos\Hello;

$client = new JsonServiceClient("https://test.servicestack.net");

/** @var HelloResponse $response */
$response = client->get(new Hello(name:"World"));
```

> The `HelloResponse` optional type hint doesn't change runtime behavior but enables static analysis tools and IDEs like PyCharm to provide rich intelli-sense and development time feedback.

## Installation

Ensure you have [PHP](https://www.php.net/manual/en/install.php) and [Composer](https://getcomposer.org/doc/00-intro.md) installed.

The only requirements for PHP apps to perform typed API Requests are the generated PHP DTOs and the generic `JsonServiceClient` 
which can be installed in Composer projects with:

```bash
$ composer require servicestack/client
```

Or by adding the package to your `composer.json` then installing the dependencies:

```json
{
  "require": {
    "servicestack/client": "^1.0"
  }
}
```

### PhpStorm ServiceStack Plugin

PHP developers of [PhpStorm](https://www.jetbrains.com/phpstorm/) can get a simplified development experience for consuming 
ServiceStack Services by installing the [ServiceStack Plugin](https://plugins.jetbrains.com/plugin/7749-servicestack) from the JetBrains Marketplace:

[![](/img/pages/servicestack-reference/phpstorm-servicestack-plugin.webp)](https://plugins.jetbrains.com/plugin/7749-servicestack)

Where you'll be able to right-click on a directory and click on **ServiceStack Reference** on the context menu:

![](/img/pages/servicestack-reference/phpstorm-add-servicestack-reference.webp)

To launch the **Add PHP ServiceStack Reference** dialog where you can enter the remote URL of the ServiceStack endpoint you wish to call to generate the Typed PHP DTOs for all APIs which by default will saved to `dtos.php`:

![](/img/pages/servicestack-reference/phpstorm-add-servicestack-reference-dialog.webp)

Then just import the DTOs and `JsonServiceClient` to be able to consume any of the remote ServiceStack APIs:

```php
<?php

require_once __DIR__ . '/vendor/autoload.php'; // Autoload files using Composer autoload
require_once 'dtos.php';

use dtos\FindTechnologies;
use Servicestack\JsonServiceClient;

$client = JsonServiceClient::create("https://techstacks.io");

$response = $client->send(new FindTechnologies(
    ids: [1,2,4,6],
    vendorName: "Google"));

print_r($response);
```

If any of the the remote APIs change their DTOs can be updated by right-clicking on `dtos.php` and clicking **Update ServiceStack Reference**:

![](/img/pages/servicestack-reference/phpstorm-update-servicestack-reference.webp)

### Simple command-line utility for PHP

Developers using other PHP IDEs and Text Editors like VS Code can utilize the cross-platform [`x` command line utility](/dotnet-tool) for generating PHP DTOs from the command-line.

To install first install the [latest .NET SDK](https://dotnet.microsoft.com/download) for your OS then install the [`x` dotnet tool](/dotnet-tool) with:

```bash
$ dotnet tool install --global x 
```

::include npx-get-dtos.md::

### Adding a ServiceStack Reference

To Add a PHP ServiceStack Reference just call `x php` with the URL of a remote ServiceStack instance:

```bash
$ x php https://techstacks.io
```

Result:

    Saved to: dtos.php

Calling `x php` with just a URL will save the DTOs using the Host name, you can override this by specifying a FileName as the 2nd argument:

    $ x php https://techstacks.io Tech

Result:

    Saved to: Tech.dtos.php

### Updating a ServiceStack Reference

To Update an existing ServiceStack Reference, call `x php` with the Filename:

    $ x php dtos.php

Result:

    Updated: dtos.php

Which will update the File with the latest PHP Server DTOs from [techstacks.io](https://techstacks.io). 
You can also customize how DTOs are generated by uncommenting the [PHP DTO Customization Options](/#dto-customization-options) and updating them again.

### Updating all PHP DTOs

Calling `x php` without any arguments will update all PHP DTOs in the current directory:

```bash
$ x php
```

Result:

    Updated: Tech.dtos.php
    Updated: dtos.php

### Smart Generic JsonServiceClient

The generic `JsonServiceClient` is a 1st class client with the same rich feature-set of the smart ServiceClients in other 
[1st class supported languages](/add-servicestack-reference#supported-languages) sporting a terse, 
typed flexible API with support for additional untyped params, custom URLs and HTTP Methods, dynamic response types including 
consuming API responses in raw text and binary data formats. Clients can be decorated to support generic functionality 
using instance and static Request, Response and Exception Filters.

It includes built-in support for a number of [ServiceStack Auth options](/authentication-and-authorization) 
including [HTTP Basic Auth](https://en.wikipedia.org/wiki/Basic_access_authentication) and stateless Bearer Token Auth Providers like 
[API Key](/api-key-authprovider) and [JWT Auth](/jwt-authprovider) as well as 
[stateful Sessions](/sessions) used by the popular **credentials** Auth Provider and an 
`onAuthenticationRequired` callback for enabling custom authentication methods. 

The built-in auth options include auto-retry support for transparently authenticating and retrying authentication required 
requests as well as [Refresh Token Cookie](/jwt-authprovider#refresh-token-cookies-supported-in-all-service-clients) 
support where it will transparently fetch new JWT Bearer Tokens automatically behind-the-scenes for friction-less stateless JWT support.

A snapshot of these above features is captured in the high-level public API below:

```php
class JsonServiceClient
{
    public static ?RequestFilter $globalRequestFilter;
    public ?RequestFilter $requestFilter;
    public static ?ResponseFilter $globalResponseFilter;
    public ?ResponseFilter $responseFilter;
    public static ?ExceptionFilter $globalExceptionFilter;
    public ?ExceptionFilter $exceptionFilter;
    public ?Callback $onAuthenticationRequired;

    public string $baseUrl;
    public string $replyBaseUrl;
    public string $oneWayBaseUrl;
    public ?string $userName;
    public ?string $password;
    public ?string $bearerToken;
    public ?string $refreshToken;
    public ?string $refreshTokenUri;
    public bool $useTokenCookie;
    public array $headers = [];
    public array $cookies = [];

    public function __construct(string $baseUrl);

    public function setCredentials(?string $userName = null, ?string $password = null) : void;
    public function getTokenCookie();
    public function getRefreshTokenCookie();

    public function get(IReturn|IReturnVoid|string $request, ?array $args = null): mixed;
    public function post(IReturn|IReturnVoid|string $request, mixed $body = null, ?array $args = null): mixed;
    public function put(IReturn|IReturnVoid|string $request, mixed $body = null, ?array $args = null): mixed;
    public function patch(IReturn|IReturnVoid|string $request, mixed $body = null, ?array $args = null): mixed;
    public function delete(IReturn|IReturnVoid|string $request, ?array $args = null): mixed;
    public function options(IReturn|IReturnVoid|string $request, ?array $args = null): mixed;
    public function head(IReturn|IReturnVoid|string $request, ?array $args = null): mixed;
    public function send(IReturn|IReturnVoid|null $request, ?string $method = null, mixed $body = null, 
        ?array $args = null): mixed;

    public function getUrl(string $path, mixed $responseAs = null, mixed $args = null): mixed;
    public function postUrl(string $path, mixed $responseAs = null, mixed $body = null, ?array $args = null): mixed;
    public function putUrl(string $path, mixed $responseAs = null, mixed $body = null, ?array $args = null): mixed;
    public function patchUrl(string $path, mixed $responseAs = null, mixed $body = null, ?array $args = null): mixed;
    public function deleteUrl(string $path, mixed $responseAs = null, mixed $args = null): mixed;
    public function optionsUrl(string $path, mixed $responseAs = null, mixed $args = null): mixed;
    public function headUrl(string $path, mixed $responseAs = null, mixed $args = null): mixed;
    public function sendUrl(string $path, ?string $method = null, mixed $responseAs = null, mixed $body = null, 
        mixed $args = null): mixed;

    public function postFileWithRequest(IReturn|IReturnVoid|string $request, UploadFile $file): mixed;
    public function postFileWithRequestUrl(string $requestUri, mixed $request, UploadFile $file): mixed;
    public function postFilesWithRequest(IReturn|IReturnVoid|string $request, UploadFile|array $files): mixed;
    public function postFilesWithRequestUrl(string $requestUri, mixed $request, UploadFile|array $files): mixed;

    public function sendAll(array $requestDtos): mixed;       # Auto Batch Reply Requests
    public function sendAllOneWay(array $requestDtos): void;  # Auto Batch Oneway Requests
```

### Change Default Server Configuration

The above defaults are also overridable on the ServiceStack Server by modifying the default config on the `NativeTypesFeature` Plugin, e.g:

```csharp
var nativeTypes = this.GetPlugin<NativeTypesFeature>();
nativeTypes.MetadataTypesConfig.AddResponseStatus = true;
...
```

PHP specific functionality can be added by `PhpGenerator`

```csharp
PhpGenerator.ServiceStackImports.Add("MyNamespace\\Type");
```

### Customize DTO Type generation

Additional PHP specific customization can be statically configured like `PreTypeFilter`, `InnerTypeFilter` & `PostTypeFilter` 
(available in all languages) can be used to inject custom code in the generated DTOs output. 

Use the `PreTypeFilter` to generate source code before and after a Type definition, e.g. this will append a custom `MyAnnotation` 
annotation on non enum & interface types:

```csharp
PhpGenerator.PreTypeFilter = (sb, type) => {
    if (!type.IsEnum.GetValueOrDefault() && !type.IsInterface.GetValueOrDefault())
    {
        sb.AppendLine("#[MyAnnotation]");
    }
};
```

The `InnerTypeFilter` gets invoked just after the Type Definition which can be used to generate common members for all Types and interfaces, e.g:

```csharp
PhpGenerator.InnerTypeFilter = (sb, type) => {
    sb.AppendLine("public ?int $id;");
    sb.AppendLine("public function getId(): int { return $this->id ?? ($this->id=rand()); }");
};
```

There's also `PrePropertyFilter` & `PostPropertyFilter` for generating source before and after properties, e.g:

```csharp
PhpGenerator.PrePropertyFilter = (sb , prop, type) => {
    if (prop.Name == "Id")
    {
        sb.AppendLine("#[IsInt]");
    }
};
```

### Emit custom code

To enable greater flexibility when generating complex Typed DTOs, you can use `[Emit{Language}]` attributes to generate code before each type or property.

These attributes can be used to generate different attributes or annotations to enable client validation for different validation libraries in different languages, e.g:

```csharp
[EmitCode(Lang.Php, "// App User")]
[EmitPhp("#[Validate]")]
public class User : IReturn<User>
{
    [EmitPhp("#[IsNotEmpty]", "#[IsEmail]")]
    [EmitCode(Lang.Swift | Lang.Dart, new[]{ "@isNotEmpty()", "@isEmail()" })]
    public string Email { get; set; }
}
```

Which will generate `[EmitPhp]` code in PHP DTOs:

```php
// App User
#[Validate]
class User implements JsonSerializable 
{
    public function __construct(
        #[IsNotEmpty]
        #[IsEmail]
        /** @var string|null */
        public ?string email=null
    ) {
    }
    //...
}
```

Whilst the generic `[EmitCode]` attribute lets you emit the same code in multiple languages with the same syntax.

### PHP Reference Example

Lets walk through a simple example to see how we can use ServiceStack's PHP DTO annotations in our PHP `JsonServiceClient`. 

Firstly we'll need to add a PHP Reference to the remote ServiceStack Service by **right-clicking** on a project folder and clicking on `ServiceStack Reference...` (as seen in the above screenshot).

This will import the remote Services dtos into your local project which looks similar to:

```php
<?php namespace dtos;
/* Options:
Date: 2025-06-04 09:50:43
Version: 8.71
Tip: To override a DTO option, remove "//" prefix before updating
BaseUrl: https://techstacks.io

//GlobalNamespace: dtos
//MakePropertiesOptional: False
//AddServiceStackTypes: True
//AddResponseStatus: False
//AddImplicitVersion: 
//AddDescriptionAsComments: True
//IncludeTypes: 
//ExcludeTypes: 
//DefaultImports: 
*/

// @Route("/technology/{Slug}")
#[Returns('GetTechnologyResponse')]
class GetTechnology implements IReturn, IRegisterStats, IGet, JsonSerializable
{
    public function __construct(
        /** @var string|null */
        public ?string $slug=null
    ) {
    }

    /** @throws Exception */
    public function fromMap($o): void {
        if (isset($o['slug'])) $this->slug = $o['slug'];
    }
    
    /** @throws Exception */
    public function jsonSerialize(): mixed
    {
        $o = [];
        if (isset($this->slug)) $o['slug'] = $this->slug;
        return empty($o) ? new class(){} : $o;
    }
    public function getTypeName(): string { return 'GetTechnology'; }
    public function getMethod(): string { return 'GET'; }
    public function createResponse(): mixed { return new GetTechnologyResponse(); }
}

class GetTechnologyResponse implements JsonSerializable
{
    public function __construct(
        /** @var DateTime */
        public DateTime $created=new DateTime(),
        /** @var Technology|null */
        public ?Technology $technology=null,
        /** @var array<TechnologyStack>|null */
        public ?array $technologyStacks=null,
        /** @var ResponseStatus|null */
        public ?ResponseStatus $responseStatus=null
    ) {
    }

    /** @throws Exception */
    public function fromMap($o): void {
        if (isset($o['created'])) $this->created = JsonConverters::from('DateTime', $o['created']);
        if (isset($o['technology'])) $this->technology = JsonConverters::from('Technology', $o['technology']);
        if (isset($o['technologyStacks'])) $this->technologyStacks = JsonConverters::fromArray('TechnologyStack', $o['technologyStacks']);
        if (isset($o['responseStatus'])) $this->responseStatus = JsonConverters::from('ResponseStatus', $o['responseStatus']);
    }
    
    /** @throws Exception */
    public function jsonSerialize(): mixed
    {
        $o = [];
        if (isset($this->created)) $o['created'] = JsonConverters::to('DateTime', $this->created);
        if (isset($this->technology)) $o['technology'] = JsonConverters::to('Technology', $this->technology);
        if (isset($this->technologyStacks)) $o['technologyStacks'] = JsonConverters::toArray('TechnologyStack', $this->technologyStacks);
        if (isset($this->responseStatus)) $o['responseStatus'] = JsonConverters::to('ResponseStatus', $this->responseStatus);
        return empty($o) ? new class(){} : $o;
    }
}
```

By default the generated PHP DTOs use the default `dtos` namespace which you can reference as individual classes:

```php
use dtos\GetTechnology;
use dtos\GetTechnologyResponse;
```

Or combined within a single line with:

```php
use dtos\{GetTechnology,GetTechnologyResponse};

$request = new GetTechnology();
```

### Making Typed API Requests

Making API Requests in PHP is the same as all other [ServiceStack's Service Clients](/clients-overview) 
by sending a populated Request DTO using a `JsonServiceClient` which returns typed Response DTO.

So the only things we need to make any API Request is the `JsonServiceClient` from the `servicestack/client` package and any 
DTO's we're using from generated PHP ServiceStack Reference, e.g:

```php
<?php

require_once __DIR__ . '/vendor/autoload.php'; // Autoload files using Composer autoload
require_once 'dtos.php';

use dtos\GetTechnology;
use dtos\GetTechnologyResponse;
use Servicestack\JsonServiceClient;

$client = JsonServiceClient::create("https://techstacks.io");

/** @var GetTechnologyResponse $response */
$response = $client->get(new GetTechnology(slug:"ServiceStack"));

$tech = $response->technology; // typed to Technology

echo "$tech->name by $tech->vendorName from $tech->productUrl\n";
echo "$tech->name TechStacks:\n";
print_r($response->technologyStacks);
```

### PHPDoc Typed Annotations

Whilst PHP is a dynamic language with limited support for static typing and generics included in the PHP language itself,
you can get many of the static type and intelli-sense benefits of a typed language by using 
[PHPDoc type hints](https://phpstan.org/writing-php-code/phpdoc-types) to annotate the APIs Typed Responses which lights
up static analysis and intelli-sense benefits in smart IDEs like PhpStorm:

```php
/** @var GetTechnologyResponse $response */
$response = $client->get(new GetTechnology(slug:"ServiceStack"));
echo $response->technology->name . PHP_EOL; //intelli-sense

/** @var QueryResponse<TechnologyView> $response */
$response = $client->get(new FindTechnologies(ids:[2,4,8]));

/** @var TechnologyView[] $results */
$results = $response->results;
echo $results[0]->name . PHP_EOL; //intelli-sense
```

### Constructors Initializer

All PHP Reference DTOs also implements promoted constructors making them much nicer to populate using a 
constructor expression with named params syntax we're used to in C#, so instead of:

```php
$request = new Authenticate();
$request->provider = "credentials";
$request->userName = $userName;
$request->password = $password;
$request->rememberMe = true;
$response = $client->post($request);
```

You can populate DTOs with a single constructor expression without any loss of PHP's Typing benefits:

```php
$response = $client->post(new Authenticate(
    provider: "credentials",
    userName: "test",
    password: "test",
    rememberMe: true));
```

### Sending additional arguments with Typed API Requests

Many AutoQuery Services utilize [implicit conventions](/autoquery-rdbms#implicit-conventions) 
to query fields that aren't explicitly defined on AutoQuery Request DTOs, these can be queried by specifying additional arguments 
with the typed Request DTO, e.g:

```php
/** @var QueryResponse<TechnologyView> $response */
$response = $client->get(new FindTechnologies(), args:["vendorName" => "ServiceStack"]);
```

### Making API Requests with URLs

In addition to making Typed API Requests you can also call Services using relative or absolute urls, e.g:

```php
$client->getUrl("/technology/ServiceStack", responseAs:new GetTechnologyResponse());

$client->getUrl("https://techstacks.io/technology/ServiceStack", 
    responseAs:new GetTechnologyResponse());

// https://techstacks.io/technology?Slug=ServiceStack
$args = ["slug" => "ServiceStack"]
client.getUrl("/technology", args:$args, responseAs:new GetTechnologyResponse()); 
```

as well as POST Request DTOs to custom urls:

```php
$client->postUrl("/custom-path", $request, args:["slug" => "ServiceStack"]);

$client->postUrl("http://example.org/custom-path", $request);
```

### Uploading Files

The `post_file_with_request` method can be used to upload a file with an API Request.

### PHP Speech to Text

```php
$audioFile = __DIR__ . '/files/audio.wav';

/** @var GenerationResponse $response */
$response = $client->postFileWithRequest(new SpeechToText(),
    new UploadFile(
        filePath: $audioFile,
        fileName: 'audio.wav',
        fieldName: 'audio',
        contentType: 'audio/wav'
    ));
```

To upload multiple files use `postFilesWithRequest`.

### Raw Data Responses

The `JsonServiceClient` also supports Raw Data responses like `string` and `byte[]` which also get a Typed API once 
declared on Request DTOs using the `IReturn<T>` marker:

```csharp
public class ReturnString : IReturn<string> {}
public class ReturnBytes : IReturn<byte[]> {}
```

Which can then be accessed as normal, with their Response typed to a PHP `string` or `ByteArray` for raw `byte[]` responses:

```php
/** @var string $str */ 
$str = client.get(new ReturnString());

/** @var ByteArray $data */ 
$data = client->get(new ReturnBytes());
```

### Authenticating using Basic Auth

Basic Auth support is implemented in `JsonServiceClient` and follows the same API made available in the C# Service Clients where the `userName/password` properties can be set individually, e.g:

```php
$client = new JsonServiceClient($baseUrl);
$client->username = user;
$client->password = pass;

$response = client->get(new SecureRequest());
```

Or use `$client->setCredentials()` to have them set both together.

### Authenticating using Credentials

Alternatively you can authenticate using userName/password credentials by 
[adding a PHP Reference](#add-php-reference) 
to your remote ServiceStack Instance and sending a populated `Authenticate` Request DTO, e.g:

```php
$request = new Authenticate();
$request->provider = "credentials";
$request->userName = $userName;
$request->password = $password;
$request->remember_me = true;

$response = client->post(request);
```

This will populate the `JsonServiceClient` with [Session Cookies](/sessions#cookie-session-ids) 
which will transparently be sent on subsequent requests to make authenticated requests.

### Authenticating using JWT

Use the `bearerToken` property to Authenticate with a [ServiceStack JWT Provider](/jwt-authprovider) 
using a JWT Token:

```php
$client->bearerToken = $jwt;
```

Alternatively you can use just a [Refresh Token](/jwt-authprovider#refresh-tokens) instead:

```php
$client->refreshYoken = $refreshToken;
```

Where the client will automatically fetch a new JWT Bearer Token using the Refresh Token for authenticated requests.

### Authenticating using an API Key

Use the `bearerToken` property to Authenticate with an [API Key](/api-key-authprovider):

```php
$client->bearerToken = $apiKey;
```

### Transparently handle 401 Unauthorized Responses

If the server returns a 401 Unauthorized Response either because the client was Unauthenticated or the 
configured Bearer Token or API Key used had expired or was invalidated, you can use `onAuthenticationRequired`
callback to re-configure the client before automatically retrying the original request, e.g:

```php
$client = new JsonServiceClient(BASE_URL);
$authClient = new JsonServiceClient(AUTH_URL);

$client->onAuthenticationRequired = new class($client, $authClient) implements Callback {
    public function __construct(public JsonServiceClient $client, public JsonServiceClient $authClient) {}
    public function call(): void {
        $this->authClient->setCredentials("test", "test");
        $this->client->bearerToken = $this->authClient->get(new Authenticate())->getRefreshTokenCookie();
    }
};

// Automatically retries requests returning 401 Responses with new bearerToken
$response = client->get(new Secured());
```

### Automatically refresh Access Tokens

With the [Refresh Token support in JWT](/jwt-authprovider#refresh-tokens) 
you can use the `refresh_token` property to instruct the Service Client to automatically fetch new JWT Tokens behind 
the scenes before automatically retrying failed requests due to invalid or expired JWTs, e.g:

```php
// Authenticate to get new Refresh Token
$authClient = new JsonServiceClient(AUTH_URL);
$authClient.userName = $userName;
$authClient.password = $password;
$authResponse = $authClient->get(new Authenticate());

// Configure client with RefreshToken
$client->refreshToken = $authResponse->refreshToken;

// Call authenticated Services and clients will automatically retrieve new JWT Tokens as needed
$response = client->get(new Secured());
```

Use the `refreshTokenUri` property when refresh tokens need to be sent to a different ServiceStack Server, e.g:

```php
$client->refreshToken = $refreshToken;
$client->refreshTokenUri = AUTH_URL . "/access-token";
```

## DTO Customization Options 

In most cases you'll just use the generated PHP DTO's as-is, however you can further customize how the DTO's are generated 
by overriding the default options.

The header in the generated DTO's show the different options PHP native types support with their defaults. 
Default values are shown with the comment prefix of `//`. To override a value, remove the `//` and specify the value to 
the right of the `:`. Any uncommented value will be sent to the server to override any server defaults.

The DTO comments allows for customizations for how DTOs are generated. The default options that were used to generate the 
DTO's are repeated in the header comments of the generated DTOs, options that are preceded by a PHP comment `//` are defaults 
from the server, any uncommented value will be sent to the server to override any server defaults.

```php
<?php namespace dtos;
/* Options:
Date: 2023-10-14 08:05:09
Version: 6.111
Tip: To override a DTO option, remove "//" prefix before updating
BaseUrl: https://techstacks.io

//GlobalNamespace: dtos
//MakePropertiesOptional: False
//AddServiceStackTypes: True
//AddResponseStatus: False
//AddImplicitVersion: 
//AddDescriptionAsComments: True
//IncludeTypes: 
//ExcludeTypes: 
//DefaultImports: 
*/
```

We'll go through and cover each of the above options to see how they affect the generated DTO's:

### Change Default Server Configuration

The above defaults are also overridable on the ServiceStack Server by modifying the default config on the 
`NativeTypesFeature` Plugin, e.g:

```csharp
//Server example in C#
var nativeTypes = this.GetPlugin<NativeTypesFeature>();
nativeTypes.MetadataTypesConfig.AddResponseStatus = true;
...
```

We'll go through and cover each of the above options to see how they affect the generated DTO's:

### GlobalNamespace

This lets you specify which namespace you want the DTOs to be generated in: 

```php
<?php namespace dtos;
```

### AddResponseStatus

Automatically add a `$responseStatus` property on all Response DTOs, regardless if it wasn't already defined:

```php
class GetTechnologyResponse implements JsonSerializable
{
    ...
    /** @var ResponseStatus|null */
    public ?ResponseStatus $responseStatus=null
}
```

### AddImplicitVersion

Lets you specify the Version number to be automatically populated in all Request DTOs sent from the client: 

```php
class GetTechnology implements IReturn, IRegisterStats, IGet, JsonSerializable
{
    public int $version = 1;
    ...
}
```

This lets you know what Version of the Service Contract that existing clients are using making it easy to 
implement ServiceStack's [recommended versioning strategy](http://stackoverflow.com/a/12413091/85785). 

### IncludeTypes

Is used as a Whitelist to specify only the types you would like to have code-generated:

```
/* Options:
IncludeTypes: GetTechnology,GetTechnologyResponse
```

Will only generate `GetTechnology` and `GetTechnologyResponse` DTOs:

```php
class GetTechnology implements IReturn, IRegisterStats, IGet, JsonSerializable

// ...
class GetTechnologyResponse implements JsonSerializable
// ...
```

#### Include Generic Types

Use .NET's Type Name to include Generic Types, i.e. the Type name separated by the backtick followed by the number of 
generic arguments, e.g:

```
IncludeTypes: IReturn`1,MyPair`2
```

#### Include Request DTO and its dependent types

You can include a Request DTO and all its dependent types with a `.*` suffix on the Request DTO, e.g:

```
/* Options:
IncludeTypes: GetTechnology.*
```

Which will include the `GetTechnology` Request DTO, the `GetTechnologyResponse` Response DTO and all Types that they both reference.

#### Include All Types within a C# namespace

If your DTOs are grouped into different namespaces they can be all included using the `/*` suffix, e.g:

```
/* Options:
IncludeTypes: MyApp.ServiceModel.Admin/*
```

This will include all DTOs within the `MyApp.ServiceModel.Admin` C# namespace. 

#### Include All Services in a Tag Group

Services [grouped by Tag](/api-design#group-services-by-tag) can be used in the `IncludeTypes` 
where tags can be specified using braces in the format `{tag}` or `{tag1,tag2,tag3}`, e.g:

```
/* Options:
IncludeTypes: {web,mobile}
```

Or individually:

```
/* Options:
IncludeTypes: {web},{mobile}
```

### ExcludeTypes
Is used as a Blacklist to specify which types you would like excluded from being generated:

```
/* Options:
ExcludeTypes: GetTechnology,GetTechnologyResponse
```

Will exclude `GetTechnology` and `GetTechnologyResponse` DTOs from being generated.

### DefaultImports

Use `DefaultImports` for specifying additional imports in your generated PHP DTOs.

```php
/* Options:
...
DefaultImports: MyType
*/
```

Which will include the type in the generated DTOs:

```php
use MyType;
```

## Customize Serialization

The `servicestack/client` client lib allows for flexible serialization customization where you can change how different 
.NET Types are serialized and deserialized into native PHP types.

To illustrate this we'll walk through how serialization of properties containing binary data to Base64 is implemented.

First we specify the PHP DTO generator to emit `ByteArray` type hint for the popular .NET binary data types:

```csharp
PhpGenerator.TypeAliases[typeof(byte[]).Name] = "ByteArray";
PhpGenerator.TypeAliases[typeof(Stream).Name] = "ByteArray";
```

In the PHP app we can then specify the serializers and deserializers to use for deserializing properties with the `ByteArray` 
data type which converts binary data to/from Base64:

```php
use JsonSerializable;

class ByteArray implements JsonSerializable
{
    public ?string $data;

    public function __construct(?string $data=null)
    {
        $this->data = isset($data) ? base64_decode($data) : null;
    }

    public function jsonSerialize(): mixed
    {
        return base64_encode($this->data);
    }
}
```

## Inspect Utils

To help clients with inspecting API Responses the `servicestack/client` library also includes a number of helpful utils 
to quickly visualizing API outputs.

For a basic indented object graph you can use `Inspect::dump` to capture and `Inspect::printDump` to print the output 
of any API Response, e.g:

```php
$orgName = "php";

$opts = [
    "http" => [
        "header" => "User-Agent: gist.cafe\r\n"
    ]
];
$context = stream_context_create($opts);
$json = file_get_contents("https://api.github.com/orgs/{$orgName}/repos", false, $context);
$orgRepos = array_map(function($x) {
    $x = get_object_vars($x);
    return [
        "name"        => $x["name"],
        "description" => $x["description"],
        "url"         => $x["url"],
        "lang"        => $x["language"],
        "watchers"    => $x["watchers"],
        "forks"       => $x["forks"],
    ];
}, json_decode($json));
usort($orgRepos, function($a,$b) { return $b["watchers"] - $a["watchers"]; });

echo  "Top 3 {$orgName} GitHub Repos:\n";
Inspect::printDump(array_slice($orgRepos, 0, 3));

echo  "\nTop 10 {$orgName} GitHub Repos:\n";
Inspect::printDumpTable(array_map(function($x) {
    return [
        "name"        => $x["name"],
        "lang"        => $x["lang"],
        "watchers"    => $x["watchers"],
        "forks"       => $x["forks"],
    ];
}, array_slice($orgRepos, 0, 10)));
```

Output:

```
Top 3 php GitHub Repos:
[
    {
        name: php-src,
        description: The PHP Interpreter,
        url: https://api.github.com/repos/php/php-src,
        lang: C,
        watchers: 36122,
        forks: 7653
    },
    {
        name: web-php,
        description: The www.php.net site,
        url: https://api.github.com/repos/php/web-php,
        lang: PHP,
        watchers: 785,
        forks: 532
    },
    {
        name: php-gtk-src,
        description: The PHP GTK Bindings,
        url: https://api.github.com/repos/php/php-gtk-src,
        lang: C++,
        watchers: 201,
        forks: 59
    }
]
```

For tabular result-sets you can use `Inspect::table` to capture and `Inspect::printTable` to print API result-sets in a 
human-friendly markdown table, e.g:

```php
echo "\nTop 10 $orgName Repos:\n"
Inspect::printTable(array_slice($orgRepos, 0, 10));
```

Output:

```
Top 10 php GitHub Repos:
+------------------------------------------------+
|      name      |    lang    | watchers | forks |
|------------------------------------------------|
| php-src        | C          |    36122 |  7653 |
| web-php        | PHP        |      785 |   532 |
| php-gtk-src    | C++        |      201 |    59 |
| web-qa         | PHP        |       68 |    39 |
| phd            | PHP        |       68 |    44 |
| web-bugs       | PHP        |       58 |    68 |
| presentations  | HTML       |       45 |    27 |
| web-doc-editor | JavaScript |       43 |    37 |
| systems        | C          |       41 |    27 |
| web-wiki       | PHP        |       35 |    29 |
+------------------------------------------------+
```


# Swift Add ServiceStack Reference
Source: https://docs.servicestack.net/swift-add-servicestack-reference

![Swift iOS, XCode and macOS Banner](/img/pages/servicestack-reference/swift-logo-banner.jpg)

## Swift

ServiceStack's **Add ServiceStack Reference** feature lets iOS/macOS developers easily generate an native 
typed Swift API for your ServiceStack Services using the `x` dotnet command-line tool.

## Simple command-line utils for ServiceStack

The [x dotnet tool](/dotnet-tool) provides a simple command-line UX to easily Add and Update Swift ServiceStack References.

Prerequisites: Install [.NET Core](https://dotnet.microsoft.com/download).

```bash
$ dotnet tool install --global x 
```

This will make the `x` dotnet tool available in your `$PATH` which can now be used from within a **Terminal window** at your Xcode project folder.

::include npx-get-dtos.md::

### Reference ServiceStack.Swift

To use the latest `JsonServiceClient` you'll need to add a reference to ServiceStack Swift library using your preferred package manager:

### Xcode

From Xcode 12 the Swift Package Manager is built into Xcode.

Go to **File** > **Swift Packages** > **Add Package Dependency**:

![](/img/pages/dev/xcode-swift-add-package.png)

Add a reference to the ServiceStack.Swift GitHub repo:

https://github.com/ServiceStack/ServiceStack.Swift

![](/img/pages/dev/xcode-add-servicestack-swift.png)

After adding the dependency [ServiceStack.Swift](https://github.com/ServiceStack/ServiceStack.Swift) will be added to your project:

![](/img/pages/dev/xcode-servicestack-swift-added.png)

#### CocoaPods

In your [Podfile](https://guides.cocoapods.org/syntax/podfile.html):

```ruby
use_frameworks!

# Pods for Project
pod "ServiceStack", '~> 6.0.5'
```

#### SwiftPM

```swift
dependencies: [
    .package(url: "https://github.com/ServiceStack/ServiceStack.Swift.git", from: "6.0.5")
],
```

### Simple Usage Example

Async usage example:

```swift
import ServiceStack

let response = try await client.getAsync(AppOverview())
print(response.topTechnologies.count) //= 100
```

Sync usage example:

```swift
import ServiceStack

let client = JsonServiceClient(baseUrl: "https://techstacks.io")
let response = client.get(AppOverview())
```

### Add a new ServiceStack Reference

To Add a new ServiceStack Reference, call `x swift` with the Base URL to a remote ServiceStack instance:

```bash
$ x swift {BaseUrl}
$ x swift {BaseUrl} {FileName}
```

Where if no FileName is provided, it's inferred from the host name of the remote URL, e.g:

```bash
$ x swift https://techstacks.io
```

Downloads the Typed Swift DTOs for [techstacks.io](https://techstacks.io) and saves them to `dtos.swift`. 

Alternatively you can have it saved to a different FileName with:

```bash
$ x swift https://techstacks.io TechStacks
```

Which instead saves the DTOs to `dtos.swift`.

`x swift` also downloads [ServiceStack's Swift Client](https://github.com/ServiceStack/ServiceStack.Swift) 
and saves it to `JsonServiceClient.swift` which together with the Server DTOs contains all the dependencies 
required to consume Typed Web Services in Swift.

#### Update an existing ServiceStack Reference

The easiest way to update all your Swift Server DTOs is to just call `x swift` without any arguments:

```bash
$ x swift
```

This will go through and update all your `*.dtos.swift` Service References.

To Update a specific ServiceStack Reference, call `x swift` with the Filename:

```bash
$ x swift {FileName.dtos.swift}
```

As an example, you can Update the Server DTOs added in the previous command with:

```bash
$ x swift dtos.swift
```

Which also includes any 
[Customization Options](/swift-add-servicestack-reference#swift-configuration) 
that were manually added.

## Swift Server Configuration

The Swift defaults are overridable on the ServiceStack Server by modifying the default config on the 
`NativeTypesFeature` Plugin, e.g:

```csharp
var typesConfig = this.GetPlugin<NativeTypesFeature>().MetadataTypesConfig;
typesConfig.AddResponseStatus = true;
```

More Swift-specific configuration is available on the `SwiftGenerator` class itself, e.g:

```csharp
SwiftGenerator.DefaultImports.Add("UIKit");
```

## Swift Configuration

The header comments in the generated DTO's allows for further customization of how the DTO's are generated which can then be updated with any custom Options provided using the **Update ServiceStack Reference** Menu Item in XCode. Options that are preceded by a Swift single line comment `//` are defaults from the server that can be overridden, e.g:

```swift
/* Options:
Date: 2025-06-04 09:51:09
SwiftVersion: 6.0
Version: 8.80
Tip: To override a DTO option, remove "//" prefix before updating
BaseUrl: https://blazor-vue.web-templates.io

//BaseClass: 
//AddModelExtensions: True
//AddServiceStackTypes: True
//MakePropertiesOptional: True
//IncludeTypes: 
//ExcludeTypes: 
//ExcludeGenericBaseTypes: False
//AddResponseStatus: False
//AddImplicitVersion: 
//AddDescriptionAsComments: True
//InitializeCollections: False
//TreatTypesAsStrings: 
//DefaultImports: Foundation,ServiceStack
*/
```

To override a value, remove the `//` and specify the value to the right of the `:`. Any value uncommented will be sent to the server to override any server defaults.

We'll go through and cover each of the above options to see how they affect the generated DTO's:

### BaseClass
Specify a base class that's inherited by all Swift DTO's, e.g. to enable [Key-Value Observing (KVO)](https://developer.apple.com/library/ios/documentation/Cocoa/Conceptual/KeyValueObserving/KeyValueObserving.html) in the generated DTO models have all types inherit from `NSObject`:

```
/* Options:
BaseClass: NSObject
```

Will change all DTO types to inherit from `NSObject`:

```swift
public class UserInfo : NSObject { ... }
```

### AddModelExtensions
Remove the the code-generated type extensions required to support typed JSON serialization of the Swift types and leave only the clean Swift DTO Type definitions.

```
/* Options:
AddModelExtensions: False
```

### AddServiceStackTypes
Don't generate the types for built-in ServiceStack classes and Services like `ResponseStatus` and `Authenticate`, etc.

```
/* Options:
AddServiceStackTypes: False
```

### IncludeTypes
Is used as a Whitelist that can be used to specify only the types you would like to have code-generated:

```
/* Options:
IncludeTypes: GetTechnology,GetTechnologyResponse
```

Will only generate `GetTechnology` and `GetTechnologyResponse` DTO's:

```swift
public class GetTechnology { ... }
public class GetTechnologyResponse { ... }
```

#### Include Request DTO and its dependent types

You can include a Request DTO and all its dependent types with a `.*` suffix on the Request DTO, e.g:

```
/* Options:
IncludeTypes: GetTechnology.*
```

Which will include the `GetTechnology` Request DTO, the `GetTechnologyResponse` Response DTO and all Types that they both reference.

#### Include All Types within a C# namespace

If your DTOs are grouped into different namespaces they can be all included using the `/*` suffix, e.g:

```
/* Options:
IncludeTypes: MyApp.ServiceModel.Admin/*
```

This will include all DTOs within the `MyApp.ServiceModel.Admin` C# namespace. 

#### Include All Services in a Tag Group

Services [grouped by Tag](/api-design#group-services-by-tag) can be used in the `IncludeTypes` where tags can be specified using braces in the format `{tag}` or `{tag1,tag2,tag3}`, e.g:

```
/* Options:
IncludeTypes: {web,mobile}
```

Or individually:

```
/* Options:
IncludeTypes: {web},{mobile}
```

### ExcludeTypes
Is used as a Blacklist where you can specify which types you would like to exclude from being generated:

```
/* Options:
ExcludeTypes: GetTechnology,GetTechnologyResponse
```

Will exclude `GetTechnology` and `GetTechnologyResponse` DTO's from being generated.

### ExcludeGenericBaseTypes

Work around a [regression added in Swift 1.2](https://github.com/ServiceStack/ServiceStack/blob/master/docs/2015/release-notes.md#swift-native-types-upgraded-to-swift-12) where the Swift compiler segfaults trying to compile Extensions to Types with a Generic Base Class. You can omit the problematic Generic Base Types from being generated with:

```swift
ExcludeGenericBaseTypes: True
```

Any types that were omitted from the generated DTO's will be emitted in comments, using the format:

```swift
//Excluded: {TypeName}
```

### AddResponseStatus
Automatically add a `ResponseStatus` property on all Response DTO's, regardless if it wasn't already defined:

```
/* Options:
AddResponseStatus: True
```

Will add a `ResponseStatus` property to all Response DTO's:

```swift
public class GetAllTechnologiesResponse
{
    ...
    public var responseStatus:ResponseStatus
}
```

### AddImplicitVersion
Lets you specify the Version number to be automatically populated in all Request DTO's sent from the client: 

```
/* Options:
AddImplicitVersion: 1
```

Will add an initialized `version` property to all Request DTO's:

```swift
public class GetAllTechnologies : IReturn
{
    ...
    public var version:Int = 1
}
```

This lets you know what Version of the Service Contract that existing clients are using making it easy to implement ServiceStack's [recommended versioning strategy](http://stackoverflow.com/a/12413091/85785). 

### InitializeCollections
Whether enumerables should be initialized with an empty collection (default) or changed to use an Optional type:

```
/* Options:
InitializeCollections: False
```

Changes Collection Definitions to be declared as Optional Types instead of being initialized with an empty collection:

```swift
public class ResponseStatus
{
    public var errors:[ResponseError]?
}
```

### DefaultImports
Add additional import statements to the generated DTO's:

```
/* Options:
DefaultImports: UIKit,Foundation
```

Will import the `UIKit` and `Foundation` frameworks:

```swift
import UIKit;
import Foundation;
```

### Swift style enums

You can override code-generation to emit Swift Style **camelCase** enums in your AppHost with:

```csharp
SwiftGenerator.EnumNameStrategy = SwiftGenerator.SwiftStyleEnums;
```

## Swift Client Usage

### [JsonServiceClient.swift](https://github.com/ServiceStack/ServiceStack.Swift/blob/master/dist/JsonServiceClient.swift)

The same ideal, high-level API available in [.NET's ServiceClients](/csharp-client) have been translated into idiomatic Swift as seen with its `ServiceClient` protocol definition below:

```swift
public protocol ServiceClient {
    func get<T: IReturn>(_ request: T) throws -> T.Return where T: Codable
    func get<T: IReturnVoid>(_ request: T) throws -> Void where T: Codable
    func get<T: IReturn>(_ request: T, query: [String: String]) throws -> T.Return where T: Codable
    func get<T: Codable>(_ relativeUrl: String) throws -> T
    func getAsync<T: IReturn>(_ request: T) async throws -> T.Return where T: Codable
    func getAsync<T: IReturnVoid>(_ request: T) async throws -> Void where T: Codable
    func getAsync<T: IReturn>(_ request: T, query: [String: String]) async throws -> T.Return where T: Codable
    func getAsync<T: Codable>(_ relativeUrl: String) async throws -> T

    func post<T: IReturn>(_ request: T) throws -> T.Return where T: Codable
    func post<T: IReturnVoid>(_ request: T) throws -> Void where T: Codable
    func post<Response: Codable, Request: Codable>(_ relativeUrl: String, request: Request?) throws -> Response
    func postAsync<T: IReturn>(_ request: T) async throws -> T.Return where T: Codable
    func postAsync<T: IReturnVoid>(_ request: T) async throws -> Void where T: Codable
    func postAsync<Response: Codable, Request: Codable>(_ relativeUrl: String, request: Request?) async throws -> Response

    func put<T: IReturn>(_ request: T) throws -> T.Return where T: Codable
    func put<T: IReturnVoid>(_ request: T) throws -> Void where T: Codable
    func put<Response: Codable, Request: Codable>(_ relativeUrl: String, request: Request?) throws -> Response
    func putAsync<T: IReturn>(_ request: T) async throws -> T.Return where T: Codable
    func putAsync<T: IReturnVoid>(_ request: T) async throws -> Void where T: Codable
    func putAsync<Response: Codable, Request: Codable>(_ relativeUrl: String, request: Request?) async throws -> Response

    func delete<T: IReturn>(_ request: T) throws -> T.Return where T: Codable
    func delete<T: IReturnVoid>(_ request: T) throws -> Void where T: Codable
    func delete<T: IReturn>(_ request: T, query: [String: String]) throws -> T.Return where T: Codable
    func delete<T: Codable>(_ relativeUrl: String) throws -> T
    func deleteAsync<T: IReturn>(_ request: T) async throws -> T.Return where T: Codable
    func deleteAsync<T: IReturnVoid>(_ request: T) async throws -> Void where T: Codable
    func deleteAsync<T: IReturn>(_ request: T, query: [String: String]) async throws -> T.Return where T: Codable
    func deleteAsync<T: Codable>(_ relativeUrl: String) async throws -> T

    func patch<T: IReturn>(_ request: T) throws -> T.Return where T: Codable
    func patch<T: IReturnVoid>(_ request: T) throws -> Void where T: Codable
    func patch<Response: Codable, Request: Codable>(_ relativeUrl: String, request: Request?) throws -> Response
    func patchAsync<T: IReturn>(_ request: T) async throws -> T.Return where T: Codable
    func patchAsync<T: IReturnVoid>(_ request: T) async throws -> Void where T: Codable
    func patchAsync<Response: Codable, Request: Codable>(_ relativeUrl: String, request: Request?) async throws -> Response

    func send<T: IReturn>(_ request: T) throws -> T.Return where T: Codable
    func send<T: IReturnVoid>(_ request: T) throws -> Void where T: Codable
    func send<T: Codable>(intoResponse: T, request: URLRequest) throws -> T
    func sendAsync<T: Codable>(intoResponse: T, request: URLRequest) async throws -> T

    func postFileWithRequest<T: IReturn & Codable>(request:T, file:UploadFile) throws -> T.Return
    func postFileWithRequestAsync<T: IReturn & Codable>(request:T, file:UploadFile) async throws -> T.Return
    func postFileWithRequest<T: IReturn>(_ relativeUrl: String, request:T, fileName:String, data:Data, mimeType:String?, fieldName:String?) throws -> T.Return
    func postFileWithRequestAsync<T: IReturn>(_ relativeUrl: String, request:T, fileName:String, data:Data, mimeType:String?, fieldName:String?) async throws -> T.Return
    func postFileWithRequest<T: IReturn>(url:URL, request:T, fileName:String, data:Data, mimeType:String?, fieldName:String?) throws -> T.Return
    func postFileWithRequestAsync<T: IReturn>(url:URL, request:T, fileName:String, data:Data, mimeType:String?, fieldName:String?) async throws -> T.Return
    func postFilesWithRequest<T: IReturn & Codable>(request:T, files:[UploadFile]) throws -> T.Return
    func postFilesWithRequestAsync<T: IReturn & Codable>(request:T, files:[UploadFile]) async throws -> T.Return
    func postFilesWithRequest<T: IReturn>(url:URL, request:T, files:[UploadFile]) throws -> T.Return
    func postFilesWithRequestAsync<T: IReturn>(url:URL, request:T, files:[UploadFile]) async throws -> T.Return
    
    func putFileWithRequest<T: IReturn & Codable>(request:T, file:UploadFile) throws -> T.Return
    func putFileWithRequestAsync<T: IReturn & Codable>(request:T, file:UploadFile) async throws -> T.Return
    func putFileWithRequest<T: IReturn>(_ relativeUrl: String, request:T, fileName:String, data:Data, mimeType:String?, fieldName:String?) throws -> T.Return
    func putFileWithRequestAsync<T: IReturn>(_ relativeUrl: String, request:T, fileName:String, data:Data, mimeType:String?, fieldName:String?) async throws -> T.Return
    func putFileWithRequest<T: IReturn>(url:URL, request:T, fileName:String, data:Data, mimeType:String?, fieldName:String?) throws -> T.Return
    func putFileWithRequestAsync<T: IReturn>(url:URL, request:T, fileName:String, data:Data, mimeType:String?, fieldName:String?) async throws -> T.Return
    func putFilesWithRequest<T: IReturn & Codable>(request:T, files:[UploadFile]) throws -> T.Return
    func putFilesWithRequestAsync<T: IReturn & Codable>(request:T, files:[UploadFile]) async throws -> T.Return
    func putFilesWithRequest<T: IReturn>(url:URL, request:T, files:[UploadFile]) throws -> T.Return
    func putFilesWithRequestAsync<T: IReturn>(url:URL, request:T, files:[UploadFile]) async throws -> T.Return
    
    func sendFileWithRequest<T: IReturn>(_ req:inout URLRequest, request:T, fileName:String, data:Data, mimeType:String?, fieldName:String?) throws -> T.Return
    func sendFileWithRequestAsync<T: IReturn>(_ req:inout URLRequest, request:T, fileName:String, data:Data, mimeType:String?, fieldName:String?) async throws -> T.Return
    func sendFilesWithRequest<T: IReturn>(_ req:inout URLRequest, request:T, files:[UploadFile]) throws -> T.Return
    func sendFilesWithRequestAsync<T: IReturn>(_ req:inout URLRequest, request:T, files:[UploadFile]) async throws -> T.Return

    func getData(url: String) throws -> (Data, HTTPURLResponse)?
    func getDataAsync(url: String) async throws -> (Data, HTTPURLResponse)?
    func getData(request: URLRequest, retryIf:((HTTPURLResponse) -> Bool)?) throws -> (Data, HTTPURLResponse)?
    func getDataAsync(request: URLRequest, retryIf:((HTTPURLResponse) async throws -> Bool)?) async throws -> (Data, HTTPURLResponse)?

    func getCookies() -> [String:String]
    func getTokenCookie() -> String?
    func getRefreshTokenCookie() -> String?
}
```

> Generic type constraints omitted for readability

The minor differences are primarily due to differences in Swift which instead of throwing Exceptions uses error codes and `Optional` return types and its lack of any asynchrony language support led us to embed a lightweight and [well-documented Promises](http://promisekit.org/introduction/) implementation in [PromiseKit](https://github.com/mxcl/PromiseKit) which closely matches the `Task<T>` type used in .NET Async API's.

### JsonServiceClient Usage

If you've ever had to make HTTP requests using Objective-C's `NSURLConnection` or `NSURLSession` static classes in iOS or macOS, you'll appreciate the typing benefits and productivity offered by the higher-level API's in `JsonServiceClient` - which enable the same ideal client API's we've enjoyed in ServiceStack's .NET Clients, in Swift Apps! 

::: info Tip
A nice benefit of using JsonServiceClient over static classes is that Service calls can be easily substituted and mocked with the above `ServiceClient` protocol, making it easy to test or stub out the external Gateway calls whilst the back-end is under development.
:::

To illustrate its usage we'll go through some client code to consume [TechStacks](https://github.com/ServiceStackApps/TechStacks) Services after adding a **ServiceStack Reference** to `http://techstaks.io`:

```swift
var client = JsonServiceClient(baseUrl: "https://techstacks.io")
var response = client.get(AppOverview())
```

Essentially usage is the same as it is in .NET ServiceClients - where it just needs the `baseUrl` of the remote ServiceStack instance, which can then be used to consume remote Services by sending typed Request DTO's that respond in kind with the expected Response DTO.

### Async API Usage

Whilst the sync API's are easy to use their usage should be limited in background threads so they're not blocking the Apps UI whilst waiting for responses. Most of the time when calling services from the Main UI thread you'll want to use the non-blocking async API's, which for the same API looks like:

```swift
let response = try await client.getAsync(AppOverview())
Inspect.printDump(response)
```

Swift also lets you continue marking it up with explicit Type Information and optional syntax as preferred, e.g: 

```swift
let response:AppOverviewResponse = try await client.getAsync(AppOverview())
Inspect.printDump(response)
```

Which is very similar to how we'd make async `Task<T>` calls in C# when not using its async/await language syntax sugar. 

::: info
Async callbacks are called back on the main thread, ideal for use in iOS Apps. This behavior is also configurable in the Promise's callback API.
:::

### Typed Error Handling

As Swift doesn't provide `try/catch` Exception Handling, Error handling is a little different in Swift which for most failable API's just returns a `nil` Optional to indicate when the operation didn't succeed. When more information about the error is required, API's will typically accept an additional `NSError` pointer argument to populate with more information about the error. Any additional metadata can be attached to NSError's `userInfo` Dictionary. We also follow this same approach to provide our structured error handling in `JsonServiceClient`.

To illustrate exception handling we'll connect to ServiceStack's Test Services and call the `ThrowType` Service to intentionally throw the error specified, e.g:

#### Sync Error Handling

Handling a Single C# Exception:

```swift
var client = JsonServiceClient(baseUrl: "https://test.servicestack.net")

var request = ThrowType()
request.type = "NotFound"
request.message = "custom message"

do {
    let response = client.post(request)
} catch var error as NSError {
    error.code //= 404
    //Convert into typed ResponseStatus
    var status:ResponseStatus = error.convertUserInfo() 
    status.message //= not here
    status.stackTrace //= Server Stack Trace
}
```

Handling a Validation Exception with multiple field validation errors:

```swift
let client = JsonServiceClient(baseUrl: "https://test.servicestack.net")

let request = ThrowValidation()
request.email = "invalidemail"

do {
    let response = try client.post(request)
} catch let responseError as NSError {    
    let status:ResponseStatus = responseError.convertUserInfo()!
    status.errors.count //= 3
    let field1 = status.errors[0]
    
    field1.errorCode! //= InclusiveBetween
    field1.fieldName! //= Age
    field1.message!   //= 'Age' must be between 1 and 120. You entered 0.
}
```

#### Async Error Handling

To handle errors in Async API's we just add a callback on `.error()` API on the returned Promise, e.g:

```swift
let request = ThrowValidation()
request.email = "invalidemail"

do {
_ = try await client.postAsync(request)
} catch let responseError as NSError {    
    let status:ResponseStatus = responseError.convertUserInfo()!
    status.errors.count //= 3
    let field1 = status.errors[0]
    
    field1.errorCode! //= InclusiveBetween
    field1.fieldName! //= Age
    field1.message!   //= 'Age' must be between 1 and 120. You entered 0.
}
```

### JsonServiceClient Error Handlers

Just like in .NET, we can also attach Global or instance error handlers to be able to generically handle all Service Client errors with a custom handler, e.g:

```swift
client.onError = {(e:NSError) in ... }
JsonServiceClient.Global.onError = {(e:NSError) in ... }
```

### Swift HTTP Marker Interfaces

The new `send*` API's take advantage of the HTTP Verb Interface Markers described below to send the Request DTO using the 
annotated HTTP Method, e.g:

```swift
public class HelloByGet : IReturn, IGet 
{
    public typealias Return = HelloResponse
    public var name:String?
}
public class HelloByPut : IReturn, IPut 
{
    public typealias Return = HelloResponse
    public var name:String?
}

let response = try client.send(HelloByGet())  //GET

client.sendAsync(HelloByPut())                //PUT
    .done { }
```

### Custom Routes

As Swift doesn't support Attributes any exported .NET Attributes are emitted in comments on the Request DTO they apply to, e.g:

```swift
// @Route("/technology/{Slug}")
public class GetTechnology : IReturn { ... }
```

This also means that the Custom Routes aren't used when making Service Requests and instead just uses ServiceStack's built-in [pre-defined routes](/routing#pre-defined-routes). 

But when preferred `JsonServiceClient` can also be used to call Services using Custom Routes, e.g:

```swift
var response:GetTechnologyResponse? = client.get("/technology/servicestack")
```

::: info
the explicit type definition on the return type is required here as Swift uses it as part of the generic method invocation.
:::

### Uploading Files

The `postFileWithRequestAsync` method can be used to upload a file with an API Request.

For example you can request a [Speech to Text](/ai-server/speech-to-text) 
transcription by sending an audio file to the `SpeechToText` API using the new `postFilesWithRequest` method:

### Calling AI Server to transcribe an Audio Recording

```swift
let client = JsonServiceClient(baseUrl: "https://openai.servicestack.net")
client.bearerToken = apiKey

let request = SpeechToText()
request.refId = "uniqueUserIdForRequest"

let response = try client.postFilesWithRequest(request:request, 
    file:UploadFile(fileName:"audio.mp3", data:mp3Data, fieldName:"audio"))

Inspect.printDump(response)
``` 

### Async Upload Files with API Example

Alternatively use the new `postFileWithRequestAsync` method to call the API asynchronously
using [Swift 6 Concurrency](https://docs.swift.org/swift-book/documentation/the-swift-programming-language/concurrency/) 
new **async/await** feature:

```swift
let response = try await client.postFileWithRequestAsync(request:request, 
    file:UploadFile(fileName:"audio.mp3", data:mp3Data, fieldName:"audio"))
    
Inspect.printDump(response)
```

### Multiple file upload with API Request examples

Whilst the `postFilesWithRequest` methods can be used to upload multiple files with an API Request. e.g:

```swift
let request = WatermarkVideo()
request.position = .BottomRight

let response = try client.postFilesWithRequest(request: request,
    files: [
        UploadFile(fileName: "video.mp4", data:videoData, fieldName:"video"),
        UploadFile(fileName: "watermark.jpg", data:watermarkData, fieldName:"watermark")
    ])
```

Async Example:

```swift
let response = try await client.postFilesWithRequestAsync(request: request,
    files: [
        UploadFile(fileName: "video.mp4", data:videoData, fieldName:"video"),
        UploadFile(fileName: "watermark.jpg", data:watermarkData, fieldName:"watermark")
    ])
```

### JsonServiceClient Options

Other options that can be configured on JsonServiceClient include:

```swift
client.onError = {(e:NSError) in ... }
client.timeout = ...
client.cachePolicy = NSURLRequestCachePolicy.ReloadIgnoringLocalCacheData
client.requestFilter = {(req:URLRequest) in ... }
client.responseFilter = {(res:URLResponse) in ... }

//static Global configuration
JsonServiceClient.Global.onError = {(e:NSError) in ... }
JsonServiceClient.Global.requestFilter = {(req:URLRequest) in ... }
JsonServiceClient.Global.responseFilter = {(res:URLResponse) in ... }
```

## [TechStacks iOS App](https://github.com/ServiceStackApps/TechStacksApp)

To illustrate the ease-of-use and utility of ServiceStack's new Swift support you can checkout the 
TechStacks native iOS App for [techstacks.io](https://techstacks.io) that has been recently published and is 
now available to download for free on the AppStore:

[![TechStacks on AppStore](https://raw.githubusercontent.com/ServiceStack/Assets/master/img/release-notes/techstacks-appstore.png)](https://itunes.apple.com/us/app/techstacks/id965680615?ls=1&mt=8)

The complete source code for the [TechStacks App is available on GitHub](https://github.com/ServiceStackApps/TechStacks) - providing a good example on how easy it is to take advantage of ServiceStack's Swift support to quickly build a rich and responsive Services-heavy native iOS App. 

All remote Service Calls used by the App are encapsulated into a single [AppData.swift](https://github.com/ServiceStackApps/TechStacksApp/blob/master/src/TechStacks/AppData.swift) class and only uses JsonServiceClient's non-blocking Async API's to ensure a Responsive UI is maintained throughout the App.

### MVC and Key-Value Observables (KVO)

If you've ever had to implement `INotifyPropertyChanged` in .NET, you'll find the built-in model binding capabilities in iOS/macOS a refreshing alternative thanks to Objective-C's underlying `NSObject` which automatically generates change notifications for its KV-compliant properties. UIKit and Cocoa frameworks both leverage this feature to enable its [Model-View-Controller Pattern](https://developer.apple.com/library/mac/documentation/General/Conceptual/DevPedia-CocoaCore/MVC.html). 

As keeping UI's updated with Async API callbacks can get unwieldy, we wanted to go through how we're taking advantage of NSObject's KVO support in Service Responses to simplify maintaining dynamic UI's.

### Enable Key-Value Observing in Swift DTO's

Firstly to enable KVO in your Swift DTO's we'll want to have each DTO inherit from `NSObject` which can be done by uncommenting `BaseObject` option in the header comments as seen below:

```
/* Options:
Date: 2015-02-19 22:43:04
Version: 1
BaseUrl: https://techstacks.io

BaseClass: NSObject
...
*/
```
and click the **Update ServiceStack Reference** Menu Option to fetch the updated DTO's.

Then to [enable Key-Value Observing](https://developer.apple.com/library/ios/documentation/Swift/Conceptual/BuildingCocoaApps/AdoptingCocoaDesignPatterns.html#//apple_ref/doc/uid/TP40014216-CH7-XID_8) just mark the response DTO variables with the `dynamic` modifier, e.g:

```swift
public dynamic var allTiers:[Option] = []
public dynamic var overview:AppOverviewResponse = AppOverviewResponse()
public dynamic var topTechnologies:[TechnologyInfo] = []
public dynamic var allTechnologies:[Technology] = []
public dynamic var allTechnologyStacks:[TechnologyStack] = []
```

Which is all that's needed to allow properties to be observed as they'll automatically issue change notifications when they're populated in the Service response async callbacks, e.g:

```swift
func loadOverview() -> Promise<AppOverviewResponse> {
    return client.getAsync(AppOverview())
        .done { r in
            self.overview = r
            self.allTiers = r.allTiers
            self.topTechnologies = r.topTechnologies
            return r
        }
}

func loadAllTechnologies() -> Promise<GetAllTechnologiesResponse> {
    return client.getAsync(GetAllTechnologies())
        .done { r in
            self.allTechnologies = r.results
            return r
        }
}

func loadAllTechStacks() -> Promise<GetAllTechnologyStacksResponse> {
    return client.getAsync(GetAllTechnologyStacks())
        .done { r in
            self.allTechnologyStacks = r.results
            return r
        }
}
```

### Observing Data Changes

In your [ViewController](https://github.com/ServiceStackApps/TechStacksApp/blob/0fca564e8c06fd1b71f81faee93a2e04c70a219b/src/TechStacks/HomeViewController.swift) have the datasources for your custom views binded to the desired data (which will initially be empty):

```swift
func pickerView(pickerView: UIPickerView, numberOfRowsInComponent component: Int) -> Int {
    return appData.allTiers.count
}
...
func tableView(tableView: UITableView, numberOfRowsInSection section: Int) -> Int {
    return appData.topTechnologies.count
}
```

Then in `viewDidLoad()` [start observing the properties](https://github.com/ServiceStack/ServiceStack.Swift/blob/67c5c092b92927702f33b6a0669e3aa1de0e2cdc/apps/TechStacks/TechStacks/HomeViewController.swift#L31) your UI Controls are bound to, e.g:

```swift
override func viewDidLoad() {
    ...
    self.appData.observe(self, properties: ["topTechnologies", "allTiers"])
    self.appData.loadOverview()
}
deinit { self.appData.unobserve(self) }
```

In the example code above we're using some custom [KVO helpers](https://github.com/ServiceStackApps/TechStacksApp/blob/0fca564e8c06fd1b71f81faee93a2e04c70a219b/src/TechStacks/AppData.swift#L159-L183) to keep the code required to a minimum.

With the observable bindings in place, the change notifications of your observed properties can be handled by overriding `observeValueForKeyPath()` which passes the name of the property that's changed in the `keyPath` argument that can be used to determine the UI Controls to refresh, e.g:

```swift
override func observeValueForKeyPath(keyPath:String, ofObject object:AnyObject, change:[NSObject:AnyObject],
  context: UnsafeMutablePointer<Void>) {
    switch keyPath {
    case "allTiers":
        self.technologyPicker.reloadAllComponents()
    case "topTechnologies":
        self.tblView.reloadData()
    default: break
    }
}
```

Now that everything's configured, the observables provide an alternative to manually updating UI elements within async callbacks, instead you can now fire-and-forget your async API's and rely on the pre-configured bindings to automatically update the appropriate UI Controls when their bounded properties are updated, e.g:

```swift
self.appData.loadOverview() //Ignore response and use configured KVO Bindings
```

### Images and Custom Binary Requests

In addition to greatly simplifying Web Service Requests, `JsonServiceClient` also makes it easy to fetch any custom HTTP response like Images and other Binary data using the generic `getData()` and `getDataAsync()` NSData API's. This is used in TechStacks to [maintain a cache of all loaded images](https://github.com/ServiceStackApps/TechStacksApp/blob/0fca564e8c06fd1b71f81faee93a2e04c70a219b/src/TechStacks/AppData.swift#L144), reducing number of HTTP requests and load times when navigating between screens:

```swift
var imageCache:[String:UIImage] = [:]

public func loadImageAsync(url:String) -> Promise<UIImage?> {
    if let image = imageCache[url] {
        return Promise<UIImage?> { (complete, reject) in complete(image) }
    }
    
    return client.getDataAsync(url)
        .done { (data:NSData) -> UIImage? in
            if let image = UIImage(data:data) {
                self.imageCache[url] = image
                return image
            }
            return nil
        }
}
```

## [TechStacks macOS Desktop App](https://github.com/ServiceStackApps/TechStacksDesktopApp)

As `JsonServiceClient.swift` has no external dependencies and only relies on core `Foundation` classes it 
can be used anywhere Swift can including macOS Cocoa Desktop and Command Line Apps and Frameworks.

Most of the API's used in TechStacks iOS App are standard typed Web Services calls. There is also a 
[TechStacks macOS Desktop](https://github.com/ServiceStackApps/TechStacksDesktopApp) 
available which showcases how easy it is to call ServiceStack's dynamic 
[AutoQuery Services](/autoquery/) and how much auto-querying functionality they can provide for free.

E.g. The TechStacks Desktop app is essentially powered with these 2 AutoQuery Services:

```csharp
[Query(QueryTerm.Or)] //change from filtering (default) to combinatory semantics
public class FindTechStacks : QueryBase<TechnologyStack> {}

[Query(QueryTerm.Or)]
public class FindTechnologies : QueryBase<Technology> {}
```

Basically just a Request DTO telling AutoQuery what Table we want to Query and that we want to [change the default Search behavior](/autoquery#changing-querying-behavior) to have **OR** semantics. We don't need to specify which properties we can query as the [implicit conventions](/autoquery#implicit-conventions) automatically infer it from the table being queried.

The TechStacks Desktop UI is then built around these 2 AutoQuery Services allowing querying against each field and utilizing a subset of the implicit conventions supported:

### Querying Technology Stacks

![TechStack Desktop Search Fields](https://raw.githubusercontent.com/ServiceStack/Assets/master/img/release-notes/techstacks-desktop-field.png)

### Querying Technologies

![TechStack Desktop Search Type](https://raw.githubusercontent.com/ServiceStack/Assets/master/img/release-notes/techstacks-desktop-type.png)

Like the TechStacks iOS App all Service Calls are maintained in a single [AppData.swift](https://github.com/ServiceStackApps/TechStacksDesktopApp/blob/master/src/TechStacksDesktop/AppData.swift) class and uses KVO bindings to update its UI which is populated from these 2 services below:

```swift
func searchTechStacks(query:String, field:String? = nil, operand:String? = nil)
  -> Promise<QueryResponse<TechnologyStack>> {
    self.search = query
    
    let queryString = query.count > 0 && field != nil && operand != nil
        ? [createAutoQueryParam(field!, operand!): query]
        : ["NameContains":query, "DescriptionContains":query]
    
    let request = FindTechStacks<TechnologyStack>()
    return client.getAsync(request, query:queryString)
        .done { (r:QueryResponse<TechnologyStack>) -> QueryResponse<TechnologyStack> in
            self.filteredTechStacks = r.results
            return r
        }
}

func searchTechnologies(query:String, field:String? = nil, operand:String? = nil)
  -> Promise<QueryResponse<Technology>> {
    self.search = query

    let queryString = query.count > 0 && field != nil && operand != nil
        ? [createAutoQueryParam(field!, operand!): query]
        : ["NameContains":query, "DescriptionContains":query]
    
    let request = FindTechnologies<Technology>()
    return client.getAsync(request, query:queryString)
        .done { (r:QueryResponse<Technology>) -> QueryResponse<Technology> in
            self.filteredTechnologies = r.results
            return r
        }
}

func createAutoQueryParam(field:String, _ operand:String) -> String {
    let template = autoQueryOperandsMap[operand]!
    let mergedField = template.replace("%", withString:field)
    return mergedField
}
```

Essentially employing the same strategy for both AutoQuery Services where it builds a query String parameter to send with the request. For incomplete queries, the default search queries both `NameContains` and `DescriptionContains` field conventions returning results where the Search Text is either in `Name` **OR** `Description` fields.

### [TechStacks Console App](https://github.com/ServiceStackApps/swift-techstacks-console)

In its quest to become a popular mainstream language, Swift includes a built-in Package Manager 
to simplify the maintenance, distribution and building of Swift code. Swift Package Manager can be used to
build native statically-linked modules or Console Apps but currently has no support for iOS, watchOS, 
or tvOS platforms.
 
Nevertheless it's simple console and text-based programming model provides a great way to quickly develop 
prototypes or Console-based Swift Apps like [swiftref](https://github.com/ServiceStack/swiftref) 
using your favorite text editor. To support this environment we've packaged ServiceStack's Swift Service 
clients into a **ServiceStackClient** package so it can be easily referenced in Swift PM projects.

Together with **Swift Add ServiceStack Reference** we now have a productive development workflow for 
building statically-linked native executables that consume Typed ServiceStack Services as seen in the new 
step-by-step guide below showing how to create a simple
[Swift TechStacks Console App](https://github.com/ServiceStackApps/swift-techstacks-console). 

## Swift Generated DTO Types

With Swift support our goal was to ensure a high-fidelity, idiomatic translation within the constraints of Swift language and built-in libraries, where the .NET Server DTO's are translated into clean Swift POSO's (Plain Old Swift Objects :) having their .NET built-in types mapped to their equivalent Swift data type. 

To see what this ended up looking like, we'll peel back behind the covers and look at a couple of the [Generated Swift Test Models](https://test.servicestack.net/types/swift) to see how they're translated in Swift:

```swift
public class AllTypes
{
    required public init(){}
    public var id:Int?
    public var nullableId:Int?
    public var byte:Int8?
    public var short:Int16?
    public var int:Int?
    public var long:Int64?
    public var uShort:UInt16?
    public var uInt:UInt32?
    public var uLong:UInt64?
    public var float:Float?
    public var double:Double?
    public var decimal:Double?
    public var string:String?
    public var dateTime:NSDate?
    public var timeSpan:NSTimeInterval?
    public var dateTimeOffset:NSDate?
    public var guid:String?
    public var char:Character?
    public var nullableDateTime:NSDate?
    public var nullableTimeSpan:NSTimeInterval?
    public var stringList:[String] = []
    public var stringArray:[String] = []
    public var stringMap:[String:String] = [:]
    public var intStringMap:[Int:String] = [:]
    public var subType:SubType?
}

public class AllCollectionTypes
{
    required public init(){}
    public var intArray:[Int] = []
    public var intList:[Int] = []
    public var stringArray:[String] = []
    public var stringList:[String] = []
    public var pocoArray:[Poco] = []
    public var pocoList:[Poco] = []
    public var pocoLookup:[String:[Poco]] = [:]
    public var pocoLookupMap:[String:[String:Poco]] = [:]
}

public enum EnumType : Int
{
    case Value1
    case Value2
}
```

As seen above, properties are essentially mapped to their optimal Swift equivalent. As DTO's can be partially complete all properties are `Optional` except for enumerables which default to an empty collection - making them easier to work with and despite their semantic differences, .NET enums are translated into typed Swift enums.

### Swift Code Generation

As we were already using code-gen to generate the Swift types we could extend it without impacting the Developer UX has been expanded to also include what's essentially an **explicit Reflection API** for each type with API's to support serializing to and from JSON. Thanks to Swift's rich support for extending types we were able to leverage its Type extensions so the implementation details could remain disconnected from the clean Swift type definitions allowing improved readability when inspecting the remote DTO schema's.

We can look at `AllCollectionTypes` to see an example of the code-gen that's generated for each type, essentially emitting explicit readable/writable closures for each property: 

```swift
extension AllCollectionTypes : JsonSerializable
{
    public static var typeName:String { return "AllCollectionTypes" }
    public static var metadata = Metadata.create([
            Type<AllCollectionTypes>.arrayProperty("intArray", get: { $0.intArray }, set: { $0.intArray = $1 }),
            Type<AllCollectionTypes>.arrayProperty("intList", get: { $0.intList }, set: { $0.intList = $1 }),
            Type<AllCollectionTypes>.arrayProperty("stringArray", get: { $0.stringArray }, set: { $0.stringArray = $1 }),
            Type<AllCollectionTypes>.arrayProperty("stringList", get: { $0.stringList }, set: { $0.stringList = $1 }),
            Type<AllCollectionTypes>.arrayProperty("pocoArray", get: { $0.pocoArray }, set: { $0.pocoArray = $1 }),
            Type<AllCollectionTypes>.arrayProperty("pocoList", get: { $0.pocoList }, set: { $0.pocoList = $1 }),
            Type<AllCollectionTypes>.objectProperty("pocoLookup", get: { $0.pocoLookup }, set: { $0.pocoLookup = $1 }),
            Type<AllCollectionTypes>.objectProperty("pocoLookupMap", get: { $0.pocoLookupMap }, set: { $0.pocoLookupMap = $1 }),
        ])
}
```

### Swift Native Types Limitations

Due to the semantic differences and limitations in Swift there are some limitations of what's not supported. Luckily these limitations are mostly [highly-discouraged bad practices](http://stackoverflow.com/a/10759250/85785) which is another reason not to use them. Specifically what's not supported:

#### No `object` or `Interface` properties
When emitting code we'll generate a comment when ignoring these properties, e.g:
```swift
//emptyInterface:IEmptyInterface ignored. Swift doesn't support interface properties
```

#### Base types must be marked abstract
As Swift doesn't support extension inheritance, when using inheritance in DTO's any Base types must be marked abstract.

#### All DTO Type Names must be unique
Required as there are no namespaces in Swift (Also required for F# and TypeScript). ServiceStack only requires Request DTO's to be unique, but our recommendation is for all DTO names to be unique.

#### IReturn not added for Array Responses
As Swift doesn't allow extending generic Arrays with public protocols, the `IReturn` marker that enables the typed ServiceClient API isn't available for Requests returning Array responses. You can workaround this limitation by wrapping the array in a Response DTO whilst we look at other solutions to support this in future.


# Java Add ServiceStack Reference
Source: https://docs.servicestack.net/java-add-servicestack-reference

![](https://raw.githubusercontent.com/ServiceStack/Assets/master/img/release-notes/android-studio-splash.png)

## [ServiceStack IDEA Android Studio Plugin](https://plugins.jetbrains.com/plugin/7749?pr=androidstudio)

Like the existing IDE integrations before it, the ServiceStack IDEA plugin provides Add ServiceStack Reference functionality to [Android Studio - the official Android IDE](https://developer.android.com/sdk/index.html). 

The **ServiceStackIDEA** plugin also includes support for **IntelliJ Maven projects** giving Java devs a productive and familiar development experience whether they're creating Android Apps or pure cross-platform Java clients.

Java Android Example using Android Studio

<lite-youtube class="w-full mx-4 my-4" width="560" height="315" videoid="xg677weFef4" style="background-image: url('https://img.youtube.com/vi/xg677weFef4/maxresdefault.jpg')"></lite-youtube>

### Install ServiceStack IDEA from the Plugin repository

The ServiceStack IDEA is now available to install directly from within IntelliJ or Android Studio IDE Plugins Repository, to Install Go to: 

 1. `File -> Settings...` Main Menu Item
 2. Select **Plugins** on left menu then click **Browse repositories...** at bottom
 3. Search for **ServiceStack** and click **Install plugin**
 4. Restart to load the installed ServiceStack IDEA plugin

![](https://raw.githubusercontent.com/ServiceStack/Assets/master/img/servicestackidea/android-plugin-download.gif)

### Download and Install ServiceStack IDEA Manually

The [ServiceStack AndroidStudio Plugin](https://plugins.jetbrains.com/plugin/7749?pr=androidstudio) can also be downloaded directly from the JetBrains plugins website at:

### [ServiceStackIDEA.zip](https://plugins.jetbrains.com/plugin/download?pr=androidstudio&updateId=19465)

After downloading the plugin above, install it in Android Studio by:

1. Click on `File -> Settings` in the Main Menu to open the **Settings Dialog**
2. Select **Plugins** settings screen
3. Click on **Install plugin from disk...** to open the **File Picker Dialog**
4. Browse and select the downloaded **ServiceStackIDEA.zip**
5. Click **OK** then Restart Android Studio

[![](https://github.com/ServiceStack/Assets/raw/34925d1b1b1b1856c451b0373139c939801d96ec/img/servicestackidea/android-plugin-install.gif)](https://plugins.jetbrains.com/plugin/7749?pr=androidstudio)

### [Installing ServiceStackEclipse Plugin on Eclipse](https://github.com/ServiceStack/ServiceStack.Java/tree/master/src/ServiceStackEclipse)

[![](https://raw.githubusercontent.com/ServiceStack/Assets/master/img/wikis/eclipse-header.png)](https://github.com/ServiceStack/ServiceStack.Java/tree/master/src/ServiceStackEclipse#eclipse-integration-with-servicestack)

See the [ServiceStack Eclipse Home Page](https://github.com/ServiceStack/ServiceStack.Java/tree/master/src/ServiceStackEclipse) for instructions on installing the **ServiceStackEclipse Plugin** from the Eclipse MarketPlace and how to Add and Update ServiceStack References directly from within the Eclipse IDE.

### Manually adding a dependency in Android Studio

Whilst the ServiceStack IDEA Plugin will automatically add the Gradle reference to your projects **build.gradle**, you can also manually add the reference by adding the **net.servicestack:android** dependency as seen below:

```
dependencies {
    implementation fileTree(dir: 'libs', include: ['*.jar'])
    implementation 'net.servicestack:android:1.1.0'
}
```

This also lets you to change which ServiceStack Client library version you want to use, the example above uses **1.0.48**.

### Add ServiceStack Reference

If you've previously used [Add ServiceStack Reference](/add-servicestack-reference) in any of the supported IDE's before, you'll be instantly familiar with Add ServiceStack Reference in Android Studio. The only additional field is **Package**, required in order to comply with Java's class definition rules. 

To add a ServiceStack Reference, right-click (or press `Ctrl+Alt+Shift+R`) on the **Package folder** in your Java sources where you want to add the POJO DTO's. This will bring up the **New >** Items Context Menu where you can click on the **ServiceStack Reference...** Menu Item to open the **Add ServiceStack Reference** Dialog: 

![Add ServiceStack Reference Java Context Menu](https://github.com/ServiceStack/Assets/raw/master/img/servicestackidea/android-context-menu.png)

The **Add ServiceStack Reference** Dialog will be partially populated with the selected **Package** with the package where the Dialog was launched from and the **File Name** defaulting to `dto.java` where the Plain Old Java Object (POJO) DTO's will be added to. All that's missing is the url of the remote ServiceStack instance you wish to generate the DTO's for, e.g: `https://techstacks.io`:

![](https://raw.githubusercontent.com/ServiceStack/Assets/master/img/servicestackidea/android-dialog.png)

Clicking **OK** will add the `dto.java` file to your project and modifies the current Project's **build.gradle** file dependencies list with the new **net.servicestack:android** dependency containing the Java JSON ServiceClients which is used together with the remote Servers DTO's to enable its typed Web Services API:

![](https://github.com/ServiceStack/Assets/raw/master/img/servicestackidea/android-dialog-example.gif)

::: info
As the Module's **build.gradle** file was modified you'll need to click on the **Sync Now** link in the top yellow banner to sync the **build.gradle** changes which will install or remove any modified dependencies
:::

### Update ServiceStack Reference

Like other Native Type languages, the generated DTO's can be further customized by modifying any of the options available in the header comments:

```
/* Options:
Date: 2025-06-04 09:52:41
Version: 8.80
Tip: To override a DTO option, remove "//" prefix before updating
BaseUrl: https://blazor-vue.web-templates.io

//Package: 
//GlobalNamespace: dtos
//AddPropertyAccessors: True
//SettersReturnThis: True
//AddServiceStackTypes: True
//AddResponseStatus: False
//AddDescriptionAsComments: True
//AddImplicitVersion: 
//IncludeTypes: 
//ExcludeTypes: 
//TreatTypesAsStrings: 
//DefaultImports: java.math.*,java.util.*,java.io.InputStream,net.servicestack.client.*,com.google.gson.annotations.*,com.google.gson.reflect.*
*/
...
```

For example the package name can be changed by uncommenting the **Package:** option with the new package name, then either right-click on the file to bring up the file context menu or use Android Studio's **Alt+Enter** keyboard shortcut then click on **Update ServiceStack Reference** to update the DTO's with any modified options:

![](https://github.com/ServiceStack/Assets/raw/master/img/servicestackidea/android-update-example.gif)

### JsonServiceClient API
The goal of Native Types is to provide a productive end-to-end typed API to facilitate  consuming remote services with minimal effort, friction and cognitive overhead. One way we achieve this is by promoting a consistent, forwards and backwards-compatible message-based API that's works conceptually similar on every platform where each language consumes remote services by sending  **Typed DTO's** using a reusable **Generic Service Client** and a consistent client library API.

To maximize knowledge sharing between different platforms, the Java ServiceClient API is modelled after the [.NET Service Clients API](/csharp-client) closely, as allowed within Java's language and idiomatic-style constraints. 

Thanks to C#/.NET being heavily inspired by Java, the resulting Java `JsonServiceClient` ends up bearing a close resemblance with .NET's Service Clients. The primary differences being due to language limitations like Java's generic type erasure and lack of language features like property initializers making Java slightly more verbose to work with, however as **Add ServiceStack Reference** is able to take advantage of code-gen we're able to mitigate most of these limitations to retain a familiar developer UX.

The [ServiceClient.java](https://github.com/ServiceStack/ServiceStack.Java/blob/master/src/AndroidClient/client/src/main/java/net/servicestack/client/ServiceClient.java) interface provides a good overview on the API available on the concrete [JsonServiceClient](https://github.com/ServiceStack/ServiceStack.Java/blob/master/src/AndroidClient/client/src/main/java/net/servicestack/client/JsonServiceClient.java) class:

```java
public interface ServiceClient {
    boolean getAlwaysSendBasicAuthHeaders();

    void setBearerToken(String value);
    String getBearerToken();
    void setTokenCookie(String value);

    void setRefreshToken(String bearerToken);
    String getRefreshToken();
    void setRefreshTokenCookie(String value);

    void setAlwaysSendBasicAuthHeaders(boolean value);
    void setCredentials(String userName, String password);

    <TResponse> TResponse send(IReturn<TResponse> request);
    void send(IReturnVoid request);

    <TResponse> TResponse get(IReturn<TResponse> request);
    void get(IReturnVoid request);
    <TResponse> TResponse get(IReturn<TResponse> request, Map<String,String> queryParams);
    <TResponse> TResponse get(String path, Class responseType);
    <TResponse> TResponse get(String path, Type responseType);
    HttpURLConnection get(String path);

    <TResponse> TResponse post(IReturn<TResponse> request);
    void post(IReturnVoid request);
    <TResponse> TResponse post(String path, Object request, Class responseType);
    <TResponse> TResponse post(String path, Object request, Type responseType);
    <TResponse> TResponse post(String path, byte[] requestBody, String contentType, Class responseType);
    <TResponse> TResponse post(String path, byte[] requestBody, String contentType, Type responseType);
    HttpURLConnection post(String path, byte[] requestBody, String contentType);

    <TResponse> TResponse put(IReturn<TResponse> request);
    void put(IReturnVoid request);
    <TResponse> TResponse put(String path, Object request, Class responseType);
    <TResponse> TResponse put(String path, Object request, Type responseType);
    <TResponse> TResponse put(String path, byte[] requestBody, String contentType, Class responseType);
    <TResponse> TResponse put(String path, byte[] requestBody, String contentType, Type responseType);
    HttpURLConnection put(String path, byte[] requestBody, String contentType);

    <TResponse> TResponse delete(IReturn<TResponse> request);
    void delete(IReturnVoid request);
    <TResponse> TResponse delete(IReturn<TResponse> request, Map<String,String> queryParams);
    <TResponse> TResponse delete(String path, Class responseType);
    <TResponse> TResponse delete(String path, Type responseType);
    HttpURLConnection delete(String path);

    void setCookie(String name, String value);
    void setCookie(String name, String value, Long expiresInSecs);
    void clearCookies();
    String getCookieValue(String name);
    String getTokenCookie();
    String getRefreshTokenCookie();

    <TResponse> TResponse postFileWithRequest(IReturn<TResponse> request, UploadFile file);
    <TResponse> TResponse postFileWithRequest(Object request, UploadFile file, Object responseType);
    <TResponse> TResponse postFileWithRequest(String path, Object request, UploadFile file, Object responseType);

    <TResponse> TResponse postFilesWithRequest(IReturn<TResponse> request, UploadFile[] files);
    <TResponse> TResponse postFilesWithRequest(Object request, UploadFile[] files, Object responseType);
    <TResponse> TResponse postFilesWithRequest(String path, Object request, UploadFile[] files, Object responseType);
}
```

The primary concession is due to Java's generic type erasure which forces the addition overloads that include a `Class` parameter for specifying the response type to deserialize into as well as a `Type` parameter overload which does the same for generic types. These overloads aren't required for API's that accept a Request DTO annotated with `IReturn<T>` interface marker as we're able to encode the Response Type in code-generated Request DTO classes.

### JsonServiceClient Usage

To get started you'll just need an instance of `JsonServiceClient` initialized with the **BaseUrl** of the remote ServiceStack instance you want to access, e.g:

```java
JsonServiceClient client = new JsonServiceClient("https://techstacks.io");
```

::: info
The JsonServiceClient is made available after the `net.servicestack:android` package is automatically added to your **build.gradle** when adding a ServiceStack reference.
:::

Typical usage of the Service Client is the same in .NET where you just need to send a populated Request DTO and the Service Client will return a populated Response DTO, e.g:

```java
AppOverviewResponse r = client.get(new AppOverview());

ArrayList<Option> allTiers = r.getAllTiers();
ArrayList<TechnologyInfo> topTech = r.getTopTechnologies();
```

As Java doesn't have type inference you'll need to specify the Type when declaring a variable. Whilst the public instance fields of the Request and Response DTO's are accessible directly, the convention in Java is to use the **property getters and setters** that are automatically generated for each DTO property as seen above.

### Custom Example Usage

We'll now go through some of the other API's to give you a flavour of what's available. When preferred you can also consume Services using a custom route by supplying a string containing the route and/or Query String. As no type info is available you'll need to specify the Response DTO class to deserialize the response into, e.g:

```java
OverviewResponse response = client.get("/overview", OverviewResponse.class);
```

The path can either be a relative or absolute url in which case the **BaseUrl** is ignored and the full absolute url is used instead, e.g:

```java
OverviewResponse response = client.get("https://techstacks.io/overview", OverviewResponse.class);
```

When initializing the Request DTO you can take advantage of the generated setters which by default return `this` allowing them to be created and chained in a single expression, e.g:

```java
GetTechnology request = new GetTechnology()
	.setSlug("servicestack");

GetTechnologyResponse response = client.get(request);
```

### AutoQuery Example Usage

You can also send requests composed of both a Typed DTO and untyped String Dictionary by providing a Java Map of additional args. This is typically used when querying [implicit conventions in AutoQuery services](/autoquery#implicit-conventions), e.g:

```java
QueryResponse<Technology> response = client.get(new FindTechnologies(),
	Utils.createMap("DescriptionContains","framework"));
```

The `Utils.createMap()` API is included in the [Utils.java](https://github.com/ServiceStack/ServiceStack.Java/blob/master/src/AndroidClient/client/src/main/java/net/servicestack/client/Utils.java) static class which contains a number of helpers to simplify common usage patterns and reduce the amount of boiler plate required for common tasks, e.g they can also simplify reading raw bytes or raw String from a HTTP Response. Here's how you can download an image bytes using a custom `JsonServiceClient` HTTP Request and load it into an Android Image `Bitmap`:

```java
HttpURLConnection httpRes = client.get("https://servicestack.net/img/logo.png");
byte[] imgBytes = Utils.readBytesToEnd(httpRes);
Bitmap img = BitmapFactory.decodeByteArray(imgBytes, 0, imgBytes.length);
```


### Integrated Basic Auth

HTTP Basic Auth is supported in `JsonServiceClient` following the implementation in .NET Service Client
where you can specify the users credentials and whether you always want to send Basic Auth with each request by:

```java
client.setCredentials(userName, password);
client.setAlwaysSendBasicAuthHeaders(true);

TestAuthResponse response = client.get(new TestAuth());
```

It also supports processing challenged 401 Auth HTTP responses where it will transparently replay the failed 
request with the Basic Auth Headers:

```java
client.setCredentials(userName, password);

TestAuthResponse response = client.get(new TestAuth());
```

Although this has the additional latency of waiting for a failed 401 response before sending an authenticated request.

### Cookies-enabled Service Client

The `JsonServiceClient` initializes a `CookieManager` in its constructor to enable any Cookies received to
be added on subsequent requests to allow you to make authenticated requests after authenticating, e.g:

```java
AuthenticateResponse authResponse = client.post(new Authenticate()
    .setProvider("credentials")
    .setUserName(userName)
    .setPassword(password));

TestAuthResponse response = client.get(new TestAuth());
``` 

### Uploading Files

The `postFileWithRequest` method can be used to upload a file with an API Request.

### Java Speech to Text

Here's an example calling [AI Server's](/ai-server/) `SpeechToText` API:

```java
byte[] audioBytes = Files.readAllBytes(Paths.get("audio.wav"));
var response = client.postFileWithRequest(request,
    new UploadFile("audio", "audio.wav", "audio/wav", audioBytes));
```

To upload multiple files use `postFilesWithRequest`.

### AndroidServiceClient
Unlike .NET, Java doesn't have an established Async story or any language support that simplifies execution and composition of Async tasks, as a result the Async story on Android is fairly fragmented with multiple options built-in for executing non-blocking tasks on different threads including:

 - Thread
 - Executor
 - HandlerThread
 - AsyncTask
 - Service
 - IntentService
 - AsyncQueryHandler
 - Loader

JayWay's Oredev presentation on [Efficient Android Threading](http://www.slideshare.net/andersgoransson/efficient-android-threading) provides a good overview of the different threading strategies above with their use-cases, features and pitfalls. Unfortunately none of the above options enable a Promise/Future-like API which would've been ideal in maintaining a consistent Task-based Async API across all ServiceStack Clients. Of all the above options the new Android [AsyncTask](http://developer.android.com/reference/android/os/AsyncTask.html) ended up the most suitable option, requiring the least effort for the typical Service Client use-case of executing non-blocking WebService Requests and having their results called back on the Main UI thread.

### AsyncResult
To enable an even simpler Async API decoupled from Android, we've introduced a higher-level [AsyncResult](https://github.com/ServiceStack/ServiceStack.Java/blob/master/src/AndroidClient/client/src/main/java/net/servicestack/client/AsyncResult.java) class which allows capturing of Async callbacks using an idiomatic anonymous Java class. `AsyncResult` is modelled after [jQuery.ajax](http://api.jquery.com/jquery.ajax/) and allows specifying **success()**, **error()** and **complete()** callbacks as needed.

### AsyncServiceClient API

Using AsyncResult lets us define a pure Java [AsyncServiceClient](https://github.com/ServiceStack/ServiceStack.Java/blob/master/src/AndroidClient/client/src/main/java/net/servicestack/client/AsyncServiceClient.java) interface that's decoupled from any specific threading implementation, i.e:

```java
public interface AsyncServiceClient {
    public <T> void getAsync(IReturn<T> request, final AsyncResult<T> asyncResult);
    public <T> void getAsync(IReturn<T> request, final Map<String, String> queryParams, final AsyncResult<T> asyncResult);
    public <T> void getAsync(String path, final Class responseType, final AsyncResult<T> asyncResult);
    public <T> void getAsync(String path, final Type responseType, final AsyncResult<T> asyncResult);
    public void getAsync(String path, final AsyncResult<byte[]> asyncResult);

    public <T> void postAsync(IReturn<T> request, final AsyncResult<T> asyncResult);
    public <T> void postAsync(String path, final Object request, final Class responseType, final AsyncResult<T> asyncResult);
    public <T> void postAsync(String path, final Object request, final Type responseType, final AsyncResult<T> asyncResult);
    public <T> void postAsync(String path, final byte[] requestBody, final String contentType, final Class responseType, final AsyncResult<T> asyncResult);
    public <T> void postAsync(String path, final byte[] requestBody, final String contentType, final Type responseType, final AsyncResult<T> asyncResult);
    public void postAsync(String path, final byte[] requestBody, final String contentType, final AsyncResult<byte[]> asyncResult);

    public <T> void putAsync(IReturn<T> request, final AsyncResult<T> asyncResult);
    public <T> void putAsync(String path, final Object request, final Class responseType, final AsyncResult<T> asyncResult);
    public <T> void putAsync(String path, final Object request, final Type responseType, final AsyncResult<T> asyncResult);
    public <T> void putAsync(String path, final byte[] requestBody, final String contentType, final Class responseType, final AsyncResult<T> asyncResult);
    public <T> void putAsync(String path, final byte[] requestBody, final String contentType, final Type responseType, final AsyncResult<T> asyncResult);
    public void putAsync(String path, final byte[] requestBody, final String contentType, final AsyncResult<byte[]> asyncResult);

    public <T> void deleteAsync(IReturn<T> request, final AsyncResult<T> asyncResult);
    public <T> void deleteAsync(IReturn<T> request, final Map<String, String> queryParams, final AsyncResult<T> asyncResult);
    public <T> void deleteAsync(String path, final Class responseType, final AsyncResult<T> asyncResult);
    public <T> void deleteAsync(String path, final Type responseType, final AsyncResult<T> asyncResult);
    public void deleteAsync(String path, final AsyncResult<byte[]> asyncResult);
}
```

The `AsyncServiceClient` interface is implemented by the `AndroidServiceClient` concrete class which behind-the-scenes uses an Android [AsyncTask](http://developer.android.com/reference/android/os/AsyncTask.html) to implement its Async API's. 

Whilst the `AndroidServiceClient` is contained in the **net.servicestack:android** dependency and only works in Android, the `JsonServiceClient` instead is contained in a seperate pure Java **net.servicestack:client** dependency which can be used independently to provide a typed Java API for consuming ServiceStack Services from any Java application.

### Async API Usage
To make use of Async API's in an Android App (which you'll want to do to keep web service requests off the Main UI thread), you'll instead need to use an instance of `AndroidServiceClient` which as it inherits `JsonServiceClient` can be used to perform both Sync and Async requests:

```java
AndroidServiceClient client = new AndroidServiceClient("https://techstacks.io");
```

Like other Service Clients, there's an equivalent Async API matching their Sync counterparts which differs by ending with an **Async** suffix which instead of returning a typed response, fires a **success(TResponse)** or **error(Exception)** callback with the typed response, e.g: 

```java
client.getAsync(new AppOverview(), new AsyncResult<AppOverviewResponse>(){
    @Override
    public void success(AppOverviewResponse r) {
        ArrayList<Option> allTiers = r.getAllTiers();
        ArrayList<TechnologyInfo> topTech = r.getTopTechnologies();
    }
});
```

Which just like the `JsonServiceClient` examples above also provide a number of flexible options to execute Custom Async Web Service Requests, e.g: 

```java
client.getAsync("/overview", OverviewResponse.class, new AsyncResult<OverviewResponse>(){
    @Override
    public void success(OverviewResponse response) {
    }
});
```

Example calling a Web Service with an absolute url:

```java
client.getAsync("https://techstacks.io/overview", OverviewResponse.class, new AsyncResult<OverviewResponse>() {
    @Override
    public void success(OverviewResponse response) {
    }
});
```

#### Async AutoQuery Example
Example calling an untyped AutoQuery Service with additional Dictionary String arguments:

```java
client.getAsync(request, Utils.createMap("DescriptionContains", "framework"),
    new AsyncResult<QueryResponse<Technology>>() {
        @Override
        public void success(QueryResponse<Technology> response) {
        }
    });
```

#### Download Raw Image Async Example
Example downloading raw Image bytes and loading it into an Android Image `Bitmap`:

```java
client.getAsync("https://servicestack.net/img/logo.png", new AsyncResult<byte[]>() {
    @Override
    public void success(byte[] imgBytes) {
        Bitmap img = BitmapFactory.decodeByteArray(imgBytes, 0, imgBytes.length);
    }
});
```

#### Send Raw String or byte[] Requests

You can easily get the raw string Response from Request DTO's that return are annotated with `IReturn<string>`, e.g:
 
```java
public static class HelloString implements IReturn<String> { ... }

String response = client.get(new HelloString().setName("World"));
```

You can also specify that you want the raw UTF-8 `byte[]` or `String` response instead of a the deserialized Response DTO by specifying
the Response class you want returned, e.g:

```java
byte[] response = client.get("/hello?Name=World", byte[].class);
```

#### Java HTTP Marker Interfaces

Like the .NET and Swift Service Clients, the HTTP Interface markers are also annotated on Java DTO's and let you use the same
`send` API to send Requests via different HTTP Verbs, e.g:  

```java
public static class HelloByGet implements IReturn<HelloResponse>, IGet { ... }
public static class HelloByPut implements IReturn<HelloResponse>, IPut { ... }

HelloResponse response = client.send(new HelloByGet().setName("World")); //GET

client.sendAsync(new HelloByPut().setName("World"),                         //PUT
    new AsyncResult<HelloResponse>() {
        @Override
        public void success(HelloResponse response) { }
    });
```

#### IReturnVoid Support

New Sync/Async overloads have been added for `IReturnVoid` Request DTO's:

```java
client.delete(new DeleteCustomer().setId(1));
```


### Typed Error Handling
Thanks to Java also using typed Exceptions for error control flow, error handling in Java will be instantly familiar to C# devs which also throws a typed `WebServiceException` containing the remote servers structured error data:

```java
ThrowType request = new ThrowType()
    .setType("NotFound")
    .setMessage("not here");

try {
	ThrowTypeResponse response = testClient.post(request);
}
catch (WebServiceException webEx) {
    ResponseStatus status = webEx.getResponseStatus();
	status.getMessage();    //= not here
    status.getStackTrace(); //= (Server StackTrace)
}
```

Likewise structured Validation Field Errors are also accessible from the familiar `ResponseStatus` DTO, e.g:

```java
ThrowValidation request = new ThrowValidation()
    .setEmail("invalidemail");

try {
    client.post(request);
} catch (WebServiceException webEx){
    ResponseStatus status = webEx.getResponseStatus();

    ResponseError firstError = status.getErrors().get(0);
    firstError.getErrorCode(); //= InclusiveBetween
    firstError.getMessage();   //= 'Age' must be between 1 and 120. You entered 0.
    firstError.getFieldName(); //= Age
}
```

#### Async Error Handling
Async Error handling differs where in order to access the `WebServiceException` you'll need to implement the **error(Exception)** callback, e.g:

```java
client.postAsync(request, new AsyncResult<ThrowTypeResponse>() {
    @Override
    public void error(Exception ex) {
        WebServiceException webEx = (WebServiceException)ex;
        
        ResponseStatus status = webEx.getResponseStatus();
        status.getMessage();    //= not here
        status.getStackTrace(); //= (Server StackTrace)
    }
});
```

Async Validation Errors are also handled in the same way: 

```java
client.postAsync(request, new AsyncResult<ThrowValidationResponse>() {
    @Override
    public void error(Exception ex) {
        WebServiceException webEx = (WebServiceException)ex;
        ResponseStatus status = webEx.getResponseStatus();

        ResponseError firstError = status.getErrors().get(0);
        firstError.getErrorCode(); //= InclusiveBetween
        firstError.getMessage();   //= 'Age' must be between 1 and 120. You entered 0.
        firstError.getFieldName(); //= Age
    }
}
```

### JsonServiceClient Error Handlers
To make it easier to generically handle Web Service Exceptions, the Java Service Clients also support static Global Exception handlers by assigning `AndroidServiceClient.GlobalExceptionFilter`, e.g:

```java
AndroidServiceClient.GlobalExceptionFilter = new ExceptionFilter() {
    @Override
    public void exec(HttpURLConnection res, Exception ex) {
    	//...
    }
};
```

As well as local Exception Filters by specifying a handler for `client.ExceptionFilter`, e.g:

```java
client.ExceptionFilter = new ExceptionFilter() {
    @Override
    public void exec(HttpURLConnection res, Exception ex) {
    	//...
    }
};
```

## Java generated DTO Types

Our goal with **Java Add ServiceStack Reference** is to ensure a high-fidelity, idiomatic translation within the constraints of Java language and its built-in libraries, where .NET Server DTO's are translated into clean, conventional Java POJO's where .NET built-in Value Types mapped to their equivalent Java data Type.

To see what this ends up looking up we'll go through some of the [Generated Test Services](https://test.servicestack.net/types/java) to see how they're translated in Java.

### .NET Attributes translated into Java Annotations
By inspecting the `HelloAllTypes` Request DTO we can see that C# Metadata Attributes e.g. `[Route("/all-types")]` are also translated into the typed Java Annotations defined in the **net.servicestack:client** dependency. But as Java only supports defining a single Annotation of the same type, any subsequent .NET Attributes of the same type are emitted in comments.

### Terse, typed API's with IReturn interfaces
Java Request DTO's are also able to take advantage of the `IReturn<TResponse>` interface marker to provide its terse, typed generic API but due to Java's Type erasure the Response Type also needs to be encoded in the Request DTO as seen by the `responseType` field and `getResponseType()` getter:

```java
@Route("/all-types")
public static class HelloAllTypes implements IReturn<HelloAllTypesResponse>
{
    public String name = null;
    public AllTypes allTypes = null;
    
    public String getName() { return name; }
    public HelloAllTypes setName(String value) { this.name = value; return this; }
    public AllTypes getAllTypes() { return allTypes; }
    public HelloAllTypes setAllTypes(AllTypes value) { this.allTypes = value; return this; }

    private static Object responseType = HelloAllTypesResponse.class;
    public Object getResponseType() { return responseType; }
}
```

### Getters and Setters generated for each property
Another noticeable feature is the Java getters and setters property convention are generated for each public field with setters returning itself allowing for multiple setters to be chained within a single expression. 

To comply with Gson JSON Serialization rules, the public DTO fields are emitted in the same JSON naming convention as the remote ServiceStack server which for the [test.servicestack.net](https://test.servicestack.net) Web Services, follows its **camelCase** naming convention that is configured in its AppHost with: 
```csharp
JsConfig.Init(new Config { TextCase = TextCase.CamelCase });
```

Whilst the public fields match the remote server JSON naming convention, the getters and setters are always emitted in Java's **camelCase** convention to maintain a consistent API irrespective of the remote server configuration. To minimize API breakage they should be the preferred method to access DTO fields.

### Java Type Conversions
By inspecting the `AllTypes` DTO fields we can see what Java Type each built-in .NET Type gets translated into. In each case it selects the most suitable concrete Java datatype available, inc. generic collections. We also see only reference types are used (i.e. instead of their primitive types equivalents) since DTO properties are optional and need to be nullable. 

```java
public static class AllTypes
{
    public Integer id = null;
    public Integer nullableId = null;
    @SerializedName("byte") public Short Byte = null;
    @SerializedName("short") public Short Short = null;
    @SerializedName("int") public Integer Int = null;
    @SerializedName("long") public Long Long = null;
    public Integer uShort = null;
    public Long uInt = null;
    public BigInteger uLong = null;
    @SerializedName("float") public Float Float = null;
    @SerializedName("double") public Double Double = null;
    public BigDecimal decimal = null;
    public String string = null;
    public Date dateTime = null;
    public TimeSpan timeSpan = null;
    public Date dateTimeOffset = null;
    public UUID guid = null;
    @SerializedName("char") public String Char = null;
    public Date nullableDateTime = null;
    public TimeSpan nullableTimeSpan = null;
    public ArrayList<String> stringList = null;
    public ArrayList<String> stringArray = null;
    public HashMap<String,String> stringMap = null;
    public HashMap<Integer,String> intStringMap = null;
    public SubType subType = null;
    ...
}
```

The only built-in Value Type that didn't have a suitable built-in Java equivalent was `TimeSpan`. In this case it uses our new [TimeSpan.java](https://github.com/ServiceStack/ServiceStack.Java/blob/master/src/AndroidClient/client/src/main/java/net/servicestack/client/TimeSpan.java) class which implements the same familiar API available in .NET's `TimeSpan`. 

Something else you'll notice is that some fields are annotated with the `@SerializedName()` Gson annotation. This is automatically added for Java keywords - required since Java doesn't provide anyway to escape keyword identifiers. The first time a Gson annotation is referenced it also automatically includes the required Gson namespace imports. If needed, this can also be explicitly added by with:

```java
JavaGenerator.AddGsonImport = true;
```

### Java Enums
.NET enums are also translated into typed Java enums where basic enums end up as a straightforward translation, e.g:

```java
public static enum BasicEnum
{
    Foo,
    Bar,
    Baz;
}
```

Whilst as Java doesn't support integer Enum flags directly the resulting translation ends up being a bit more convoluted:

```java
@Flags()
public static enum EnumFlags
{
    @SerializedName("1") Value1(1),
    @SerializedName("2") Value2(2),
    @SerializedName("4") Value3(4);

    private final int value;
    EnumFlags(final int intValue) { value = intValue; }
    public int getValue() { return value; }
}
```

### [Java Functional Utils](https://github.com/mythz/java-linq-examples)

The Core Java Functional Utils required to run 
[C#'s 101 LINQ Samples in Java](https://github.com/mythz/java-linq-examples) 
are included in the **net.servicestack:client** Java package which as its compatible with Java 1.7, 
also runs on Android:

[![](https://raw.githubusercontent.com/ServiceStack/Assets/master/img/wikis/java/linq-examples-screenshot.png)](https://github.com/mythz/java-linq-examples)

Whilst noticeably more verbose than most languages, it enables a functional style of programming that provides
an alternative to imperative programming with mutating collections and eases porting efforts of functional code 
which can be mapped to its equivalent core functional method.

## Java Configuration
The header comments in the generated DTO's allows for further customization of how the DTO's are generated which can then be updated with any custom Options provided using the **Update ServiceStack Reference** Menu Item in Android Studio. Options that are preceded by a single line Java comment `//` are defaults from the server which can be overridden.

To override a value, remove the `//` and specify the value to the right of the `:`. Any value uncommented will be sent to the server to override any server defaults.

```java
/* Options:
Date: 2015-04-10 12:41:14
Version: 1
BaseUrl: https://techstacks.io

Package: net.servicestack.techstacks
//GlobalNamespace: dto
//AddPropertyAccessors: True
//SettersReturnThis: True
//AddServiceStackTypes: True
//AddResponseStatus: False
//AddImplicitVersion: 
//IncludeTypes: 
//ExcludeTypes: 
//DefaultImports: java.math.*,java.util.*,net.servicestack.client.*,com.google.gson.annotations.*
*/
```
We'll go through and cover each of the above options to see how they affect the generated DTO's:

### Package
Specify the package name that the generated DTO's are in:
```
Package: net.servicestack.techstacks
```
Will generate the package name for the generated DTO's as:

```java
package net.servicestack.techstacks;
```

### GlobalNamespace
Change the name of the top-level Java class container that all static POJO classes are generated in, e.g changing the `GlobalNamespace` to:
```
GlobalNamespace: techstacksdto
```
Will change the name of the top-level class to `techstacksdto`, e.g:

```java
public class techstacksdto
{
    ...
}
```
Where all static DTO classes can be imported using the wildcard import below:

```java
import net.servicestack.techstacksdto.*;
```

### AddPropertyAccessors
By default **getters** and **setters** are generated for each DTO property, you can prevent this default with:
```
AddPropertyAccessors: false
```
Which will no longer generate any property accessors, leaving just public fields, e.g:

```java
public static class AppOverviewResponse
{
    public Date Created = null;
    public ArrayList<Option> AllTiers = null;
    public ArrayList<TechnologyInfo> TopTechnologies = null;
    public ResponseStatus ResponseStatus = null;
}
```

### SettersReturnThis
To allow for chaining DTO field **setters** returns itself by default, this can be changed to return `void` with:
```
SettersReturnThis: false
```
Which will change the return type of each setter to `void`:

```java
public static class GetTechnology implements IReturn<GetTechnologyResponse>
{
    public String Slug = null;
    
    public String getSlug() { return Slug; }
    public void setSlug(String value) { this.Slug = value; }
}
```

### AddServiceStackTypes
Lets you exclude built-in ServiceStack Types and DTO's from being generated with:
```
AddServiceStackTypes: false
```
This will prevent Request DTO's for built-in ServiceStack Services like `Authenticate` from being emitted.

### AddImplicitVersion
Lets you specify the Version number to be automatically populated in all Request DTO's sent from the client:
```
AddImplicitVersion: 1
```
Which will embed the specified Version number in each Request DTO, e.g:

```java
public static class GetTechnology implements IReturn<GetTechnologyResponse>
{
    public Integer Version = 1;
    public Integer getVersion() { return Version; }
    public GetTechnology setVersion(Integer value) { this.Version = value; return this; }
}
```
This lets you know what Version of the Service Contract that existing clients are using making it easy to implement [ServiceStack's recommended versioning strategy](http://stackoverflow.com/a/12413091/85785).

### IncludeTypes
Is used as a Whitelist that can be used to specify only the types you would like to have code-generated:
```
/* Options:
IncludeTypes: GetTechnology,GetTechnologyResponse
```
Will only generate `GetTechnology` and `GetTechnologyResponse` DTO's, e.g:

```java
public class dto
{
    public static class GetTechnologyResponse { ... }
    public static class GetTechnology implements IReturn<GetTechnologyResponse> { ... }
}
```

#### Include Request DTO and its dependent types

You can include a Request DTO and all its dependent types with a `.*` suffix on the Request DTO, e.g:

```
/* Options:
IncludeTypes: GetTechnology.*
```

Which will include the `GetTechnology` Request DTO, the `GetTechnologyResponse` Response DTO and all Types that they both reference.

#### Include All Types within a C# namespace

If your DTOs are grouped into different namespaces they can be all included using the `/*` suffix, e.g:

```
/* Options:
IncludeTypes: MyApp.ServiceModel.Admin/*
```

This will include all DTOs within the `MyApp.ServiceModel.Admin` C# namespace. 

#### Include All Services in a Tag Group

Services [grouped by Tag](/api-design#group-services-by-tag) can be used in the `IncludeTypes` where tags can be specified using braces in the format `{tag}` or `{tag1,tag2,tag3}`, e.g:

```
/* Options:
IncludeTypes: {web,mobile}
```

Or individually:

```
/* Options:
IncludeTypes: {web},{mobile}
```

### ExcludeTypes
Is used as a Blacklist where you can specify which types you would like to exclude from being generated:
```
/* Options:
ExcludeTypes: GetTechnology,GetTechnologyResponse
```
Will exclude `GetTechnology` and `GetTechnologyResponse` DTO's from being generated.

### DefaultImports
Lets you override the default import packages included in the generated DTO's:
```
java.math.*,java.util.*,net.servicestack.client.*,com.acme.custom.*
```
Will override the default imports with the ones specified, i.e: 

```java
import java.math.*;
import java.util.*;
import net.servicestack.client.*;
import com.acme.custom.*;
```

By default the generated DTO's do not require any Google's Gson-specific serialization hints, but when they're needed e.g. if your DTO's use Java keywords or are attributed with `[DataMember(Name=...)]` the required Gson imports are automatically added which can also be added explicitly with:

```csharp
JavaGenerator.AddGsonImport = true;
```

Which will add the following Gson imports:

```java
import com.google.gson.annotations.*;
import com.google.gson.reflect.*;
```

### TreatTypesAsStrings

Due to the [unusual encoding of Guid bytes](http://stackoverflow.com/a/18085116/85785) it may be instead be 
preferential to treat Guids as opaque strings so they are easier to compare back to their original C# Guids. 
This can be enabled with the new `TreatTypesAsStrings` option:

```
/* Options:
...
TreatTypesAsStrings: Guid

*/
```

## Example [TechStacks Android App](https://github.com/ServiceStackApps/TechStacksAndroidApp)
To demonstrate Java Native Types in action we've ported the Swift [TechStacks iOS App](https://github.com/ServiceStackApps/TechStacksApp) to a native Java Android App to showcase the responsiveness and easy-of-use of leveraging Java Add ServiceStack Reference in Android Projects. 

[![](https://raw.githubusercontent.com/ServiceStack/Assets/master/img/release-notes/techstacks-android-app.jpg)](https://github.com/ServiceStackApps/TechStacksAndroidApp)

Checkout the [TechStacks Android App](https://github.com/ServiceStackApps/TechStacksAndroidApp) repository for a nice overview of how it leverages Java Native Types, Functional Java Utils and iOS-inspired Data Binding to easily develop services-heavy Mobile Apps.


# Kotlin Add ServiceStack Reference
Source: https://docs.servicestack.net/kotlin-add-servicestack-reference

![](https://raw.githubusercontent.com/ServiceStack/Assets/master/img/wikis/android-studio-splash-kotlin.png)

## [Kotlin](https://kotlinlang.org/) - a better language for Android and the JVM

Whilst Java is the flagship language for the JVM, it's slow evolution, lack of modern features and distasteful
language additions have grown it into an cumbersome language to develop with, as illustrated in the 
[C# 101 LINQ Examples in Java](https://github.com/mythz/java-linq-examples) where it's by far the worst of all 
modern languages compared, making it a poor choice for a functional-style of programming that's especially painful
for Android development which is stuck on Java 7.

By contrast [Kotlin](https://kotlinlang.org/) ended up being one of the 
[best modern languages for functional programming](https://github.com/mythz/kotlin-linq-examples) that's 
vastly more expressive, readable, maintainable and safer than Java. As Kotlin is being developed by JetBrains 
it also has great tooling support in **Android Studio**, **IntelliJ** and **Eclipse** and seamlessly integrates 
with existing Java code where projects can mix-and-match Java and Kotlin code together within the same application - 
making Kotlin a very attractive and easy choice for Android Development.

As we expect more Android and Java projects to be written in Kotlin in future we've added first-class 
[Add ServiceStack Reference](/add-servicestack-reference) 
support for Kotlin with IDE integration in 
[Android Studio](http://developer.android.com/tools/studio/index.html) and 
[IntelliJ IDEA](https://www.jetbrains.com/idea/) where App Devlopers can create and update an end-to-end typed 
API with just a Menu Item click - enabling a highly-productive workflow for consuming ServiceStack Services.

## Kotlin Android Example using Android Studio

<lite-youtube class="w-full mx-4 my-4" width="560" height="315" videoid="nmB0NaI9-3k" style="background-image: url('https://img.youtube.com/vi/nmB0NaI9-3k/maxresdefault.jpg')"></lite-youtube>

### Kotlin Android Resources

To help getting started with Kotlin, we'll maintain links to useful resources helping to develop Android Apps 
with Kotlin below:

 - [Getting started with Android and Kotlin](https://kotlinlang.org/docs/tutorials/kotlin-android.html) <small>_(kotlinlang.org)_</small>
 - [Kotlin for Android Developers](http://www.javaadvent.com/2015/12/kotlin-android.html) <small>_(javaadvent.com)_</small>
 - [Android Development with Kotlin - Jake Wharton](https://www.youtube.com/watch?v=A2LukgT2mKc&feature=youtu.be) <small>_(youtube.com)_</small>

## Installing Kotlin

Kotlin support is enabled in Android Studio by installing the JetBrain's Kotlin plugin in project settings:

![](https://raw.githubusercontent.com/ServiceStack/Assets/master/img/wikis/kotlin/install-plugin.png)

Then find and select the **Kotlin** plugin from the list and click **Install Plugin** button:

![](https://raw.githubusercontent.com/ServiceStack/Assets/master/img/wikis/kotlin/install-kotlin-plugins.png)

Subsequent Restarts of Android Studio will now load with the **Kotlin** plugin enabled.

### Configure Project to use Kotlin

After Kotlin is enabled in Android Studio you can configure which projects you want to have Kotlin support
by going to either `Tools -> Kotlin -> Configure Kotlin in Project` on the File Menu:

![](https://raw.githubusercontent.com/ServiceStack/Assets/master/img/wikis/kotlin/kotlin-configure-project.png)

Or [alternatively you can launch it](https://kotlinlang.org/docs/tutorials/kotlin-android.html#configuring-kotlin-in-the-project)
using Android Studio's Quick **Find Action** with `Ctrl + Shift + A` and typing in `Configure K` to filter it
from the list. 

Configuring a project to support Kotlin just modifies that projects 
[build.gradle](https://github.com/mythz/kotlin-linq-examples/blob/master/src/app/build.gradle), applying the
necessary Android Kotlin plugin and build scripts needed to compile Kotlin files with your project. Once Kotlin
is configured with your project you'll get first-class IDE support for Kotlin `.kt` source files including 
intell-sense, integrated compiler analysis and feedback, refactoring and debugging support, etc.

One convenient feature that's invaluable for porting Java code and learning Kotlin is the 
[Converting Java to Kotlin](https://kotlinlang.org/docs/tutorials/kotlin-android.html#converting-java-code-to-kotlin)
Feature which can be triggered by selecting a `.java` class and clicking `Ctrl + Alt + Shift + K` keyboard short-cut
(or using [Find Action](https://kotlinlang.org/docs/tutorials/kotlin-android.html#converting-java-code-to-kotlin)).

## [ServiceStack IDEA Android Studio Plugin](https://plugins.jetbrains.com/plugin/7749?pr=androidstudio)

With Kotlin enabled on your project you can install **ServiceStack IDEA** plugin to provide 
Add ServiceStack Reference functionality directly from within [Android Studio](https://developer.android.com/sdk/index.html). 

#### Install ServiceStack IDEA from the Plugin repository

The ServiceStack IDEA is now available to install directly from within IntelliJ or Android Studio IDE Plugins Repository, to Install Go to: 

 1. `File -> Settings...` Main Menu Item
 2. Select **Plugins** on left menu then click **Browse repositories...** at bottom
 
![](https://raw.githubusercontent.com/ServiceStack/Assets/master/img/wikis/kotlin/install-plugin-repositories.png)

Search for **ServiceStack** and click **Install plugin**

![](https://raw.githubusercontent.com/ServiceStack/Assets/master/img/wikis/kotlin/install-servicestack-plugin.png)

Restart to load the installed ServiceStack IDEA plugin

### [Download and Install ServiceStack IDEA Manually](/java-add-servicestack-reference#download-and-install-servicestack-idea-manually)

See docs on [Java Add ServiceStack Reference](/java-add-servicestack-reference#download-and-install-servicestack-idea-manually)
for instructions on other ways to install the ServiceStack IDEA plugin in Android Studio or IntelliJ.

### Manually adding client dependency to your Project

When using **Add ServiceStack Reference** feature the ServiceStack IDEA Plugin automatically adds a reference to
the **net.servicestack:android** dependency in your projects **build.gradle**, this can also manually add the 
reference by adding the dependency below:

```
dependencies {
    implementation fileTree(dir: 'libs', include: ['*.jar'])
    implementation 'net.servicestack:android:1.1.0'
}
```

This also lets you to change which ServiceStack Client library version you want to use, the example above uses 
**1.1.0**. The **net.servicestack:android** dependency contains the `AndroidServiceClient` and 
`JavaServiceClient` that your projects use to call remote ServiceStack Services using the typed Kotlin DTO's
added to your project by the **Add ServiceStack Reference** feature.

### [Add ServiceStack Reference](/add-servicestack-reference)

If you've previously used 
[Add ServiceStack Reference](/add-servicestack-reference) 
in any of the supported IDE's before, you'll be instantly familiar with Add ServiceStack Reference in 
Android Studio. The only additional field is **Package**, required in order to comply with Kotlin's class 
definition rules. 

To add a ServiceStack Reference, right-click (or press `Ctrl+Alt+Shift+R`) on the **Package folder** in your 
Java sources where you want to add the POJO DTO's. This will bring up the **New >** Items Context Menu where 
you can click on the **ServiceStack Reference...** Menu Item to open the **Add ServiceStack Reference** Dialog: 

![Add ServiceStack Reference Kotlin Context Menu](https://raw.githubusercontent.com/ServiceStack/Assets/master/img/wikis/kotlin/package-add-servicestack-reference.png)

The **Add ServiceStack Reference** Dialog will be partially populated with the selected **Package** with the 
package where the Dialog was launched from and the **File Name** defaulting to `dtos.kt` where the generated 
Kotlin DTO's will be added to. All that's missing is the url of the remote ServiceStack instance you wish to 
generate the DTO's for, e.g: `https://techstacks.io`:

![](https://raw.githubusercontent.com/ServiceStack/Assets/master/img/wikis/kotlin/kotlin-add-servicestack-reference.png)

Clicking **OK** will add the `dtos.kt` file to your project and modifies the current Project's **build.gradle** 
file dependencies list with the new **net.servicestack:android** dependency containing the JSON 
ServiceClients which is used together with the remote Servers DTO's to enable its typed Web Services API. If
for some reason you wish to instead add Java DTO's to your project instead of Kotlin, just rename the `dtos.kt` 
file extension to `dtos.java` and it will import Java classes instead.

::: info
As the Module's **build.gradle** file was modified you'll need to click on the **Sync Now** link in the top yellow banner to sync the **build.gradle** changes which will install or remove any modified dependencies
:::

### Update ServiceStack Reference

Like other Native Type languages, the generated DTO's can be further customized by modifying any of the options available in the header comments:

```
/* Options:
Date: 2025-06-04 09:53:03
Version: 8.80
Tip: To override a DTO option, remove "//" prefix before updating
BaseUrl: https://blazor-vue.web-templates.io

//Package: 
//AddServiceStackTypes: True
//AddResponseStatus: False
//AddImplicitVersion: 
//AddDescriptionAsComments: True
//IncludeTypes: 
//ExcludeTypes: 
//InitializeCollections: False
//TreatTypesAsStrings: 
//DefaultImports: java.math.*,java.util.*,java.io.InputStream,net.servicestack.client.*,com.google.gson.annotations.*,com.google.gson.reflect.*
*/
...
```

For example the package name can be changed by uncommenting the **Package:** option with the new package name, then either right-click on the file to bring up the file context menu or use Android Studio's **Alt+Enter** keyboard shortcut then click on **Update ServiceStack Reference** to update the DTO's with any modified options:

![](https://raw.githubusercontent.com/ServiceStack/Assets/master/img/wikis/kotlin/kotlin-update-servicestack-reference.png)

### Java Server Events Client

In addition to enabling end-to-end Typed APIs, Kotlin can also be used to handle real-time notifications 
with the [Java Server Events Client](/java-server-events-client).

### JsonServiceClient API

The goal of Native Types is to provide a productive end-to-end typed API to facilitate  consuming remote services 
with minimal effort, friction and cognitive overhead. One way we achieve this is by promoting a consistent, 
forwards and backwards-compatible message-based API that's works conceptually similar on every platform where 
each language consumes remote services by sending  **Typed DTO's** using a reusable **Generic Service Client** 
and a consistent client library API. Thanks to its seamless integration with Java, Kotlin is able to re-use the
same Java Client Library used by 
[Java Add ServiceStack Reference](/java-add-servicestack-reference).

To maximize knowledge sharing between different platforms, the Java ServiceClient API is modelled after the 
[.NET Service Clients API](/csharp-client) closely, as allowed 
within Java's language and idiomatic-style constraints. 

Thanks to C#/.NET being heavily inspired by Java, the resulting Java `JsonServiceClient` ends up bearing a close 
resemblance with .NET's Service Clients. The primary differences being due to language limitations like Java's
generic type erasure and lack of language features like property initializers making Java slightly more verbose 
to work with, however as **Add ServiceStack Reference** is able to take advantage of code-gen we're able to 
mitigate most of these limitations to retain a familiar developer UX.

The [ServiceClient.java](https://github.com/ServiceStack/ServiceStack.Java/blob/master/src/AndroidClient/client/src/main/java/net/servicestack/client/ServiceClient.java) interface provides a good overview on the API available on the concrete [JsonServiceClient](https://github.com/ServiceStack/ServiceStack.Java/blob/master/src/AndroidClient/client/src/main/java/net/servicestack/client/JsonServiceClient.java) class:

```java
public interface ServiceClient {
    boolean getAlwaysSendBasicAuthHeaders();

    void setBearerToken(String value);
    String getBearerToken();
    void setTokenCookie(String value);

    void setRefreshToken(String bearerToken);
    String getRefreshToken();
    void setRefreshTokenCookie(String value);

    void setAlwaysSendBasicAuthHeaders(boolean value);
    void setCredentials(String userName, String password);

    <TResponse> TResponse send(IReturn<TResponse> request);
    void send(IReturnVoid request);

    <TResponse> TResponse get(IReturn<TResponse> request);
    void get(IReturnVoid request);
    <TResponse> TResponse get(IReturn<TResponse> request, Map<String,String> queryParams);
    <TResponse> TResponse get(String path, Class responseType);
    <TResponse> TResponse get(String path, Type responseType);
    HttpURLConnection get(String path);

    <TResponse> TResponse post(IReturn<TResponse> request);
    void post(IReturnVoid request);
    <TResponse> TResponse post(String path, Object request, Class responseType);
    <TResponse> TResponse post(String path, Object request, Type responseType);
    <TResponse> TResponse post(String path, byte[] requestBody, String contentType, Class responseType);
    <TResponse> TResponse post(String path, byte[] requestBody, String contentType, Type responseType);
    HttpURLConnection post(String path, byte[] requestBody, String contentType);

    <TResponse> TResponse put(IReturn<TResponse> request);
    void put(IReturnVoid request);
    <TResponse> TResponse put(String path, Object request, Class responseType);
    <TResponse> TResponse put(String path, Object request, Type responseType);
    <TResponse> TResponse put(String path, byte[] requestBody, String contentType, Class responseType);
    <TResponse> TResponse put(String path, byte[] requestBody, String contentType, Type responseType);
    HttpURLConnection put(String path, byte[] requestBody, String contentType);

    <TResponse> TResponse delete(IReturn<TResponse> request);
    void delete(IReturnVoid request);
    <TResponse> TResponse delete(IReturn<TResponse> request, Map<String,String> queryParams);
    <TResponse> TResponse delete(String path, Class responseType);
    <TResponse> TResponse delete(String path, Type responseType);
    HttpURLConnection delete(String path);

    void setCookie(String name, String value);
    void setCookie(String name, String value, Long expiresInSecs);
    void clearCookies();
    String getCookieValue(String name);
    String getTokenCookie();
    String getRefreshTokenCookie();

    <TResponse> TResponse postFileWithRequest(IReturn<TResponse> request, UploadFile file);
    <TResponse> TResponse postFileWithRequest(Object request, UploadFile file, Object responseType);
    <TResponse> TResponse postFileWithRequest(String path, Object request, UploadFile file, Object responseType);

    <TResponse> TResponse postFilesWithRequest(IReturn<TResponse> request, UploadFile[] files);
    <TResponse> TResponse postFilesWithRequest(Object request, UploadFile[] files, Object responseType);
    <TResponse> TResponse postFilesWithRequest(String path, Object request, UploadFile[] files, Object responseType);
}
```

The primary concession is due to JVM's generic type erasure which forces the addition overloads that include a 
`Class` parameter for specifying the response type to deserialize into as well as a `Type` parameter overload 
which does the same for generic types. These overloads aren't required for API's that accept a Request DTO 
annotated with `IReturn<T>` interface marker as we're able to encode the Response Type in code-generated 
Request DTO classes.

### JsonServiceClient Usage

To get started you'll just need an instance of `JsonServiceClient` initialized with the **BaseUrl** of the 
remote ServiceStack instance you want to access, e.g:

```kotlin
val client = JsonServiceClient("https://techstacks.io")
```

::: info
The JsonServiceClient is made available after the `net.servicestack:android` package is automatically added to your **build.gradle** when adding a ServiceStack reference
:::

Typical usage of the Service Client is the same in .NET where you just need to send a populated Request DTO 
and the Service Client will return a populated Response DTO, e.g:

```kotlin
val response: AppOverviewResponse? = client.get(AppOverview())
val allTiers: ArrayList<Option> = response.AllTiers
val topTech: ArrayList<TechnologyInfo> = response.TopTechnologies
```

::: info Tip
Explicit type annotations are unnecessary in Kotlin, added above to show the types returned
:::

Another example using a populated Request DTO:

```kotlin
var request = GetTechnology()
request.Slug = "servicestack"

val response = client.get(request)
```

### Custom Example Usage

We'll now go through some of the other API's to give you a flavour of what's available. When preferred you 
can also consume Services using a custom route by supplying a string containing the route and/or Query String. 
As no type info is available you'll need to specify the Response DTO class to deserialize the response into, e.g:

```kotlin
val response = client.get("/overview", OverviewResponse::class.java)
```

The path can either be a relative or absolute url in which case the **BaseUrl** is ignored and the full 
absolute url is used instead, e.g:

```kotlin
val response = client.get("https://techstacks.io/overview", OverviewResponse::class.java)
```

### AutoQuery Example Usage

You can also send requests composed of both a Typed DTO and untyped String Map by providing a Hash Map of 
additional args. This is typically used when querying 
[implicit conventions in AutoQuery services](/autoquery#implicit-conventions), e.g:

```kotlin
val response = client.get(FindTechnologies(), hashMapOf(Pair("DescriptionContains","framework")))
```

There's also the [Utils.java](https://github.com/ServiceStack/ServiceStack.Java/blob/master/src/AndroidClient/client/src/main/java/net/servicestack/client/Utils.java) 
static class which contains a number of helpers to simplify common usage patterns and reduce the amount of 
boiler plate required for common tasks, e.g they can simplify reading raw bytes or raw String from a HTTP Response. 

Here's how you can download an image bytes using a custom `JsonServiceClient` HTTP Request and load 
it into an Android Image `Bitmap`:

```kotlin
val httpRes:HttpURLConnection = client.get("https://servicestack.net/img/logo.png")
val imgBytes = Utils.readBytesToEnd(httpRes)
val img = BitmapFactory.decodeByteArray(imgBytes, 0, imgBytes.size)
```

### Uploading Files

The `postFileWithRequest` method can be used to upload a file with an API Request.

### Kotlin Speech to Text

Here's an example calling [AI Server's](/ai-server/) `SpeechToText` API:

```kotlin
val audioBytes = Files.readAllBytes(Paths.get("audio.wav"))
val response = client.postFileWithRequest(SpeechToText(),
    UploadFile("audio", "audio.wav", "audio/wav", audioBytes))
```

To upload multiple files use `postFilesWithRequest`.

### AndroidServiceClient

Unlike .NET, the JVM doesn't have an established Async story or any language support that simplifies execution 
and composition of Async tasks, as a result the Async story on Android is fairly fragmented with multiple 
options built-in for executing non-blocking tasks on different threads including:

 - Thread
 - Executor
 - HandlerThread
 - AsyncTask
 - Service
 - IntentService
 - AsyncQueryHandler
 - Loader

JayWay's Oredev presentation on [Efficient Android Threading](http://www.slideshare.net/andersgoransson/efficient-android-threading) 
provides a good overview of the different threading strategies above with their use-cases, features and pitfalls. 
Unfortunately none of the above options enable a Promise/Future-like API which would've been ideal in maintaining 
a consistent Task-based Async API across all ServiceStack Clients. Of all the above options the new Android 
[AsyncTask](http://developer.android.com/reference/android/os/AsyncTask.html) ended up the most suitable option, 
requiring the least effort for the typical Service Client use-case of executing non-blocking WebService Requests 
and having their results called back on the Main UI thread.

### AsyncResult

To enable a simpler Async API decoupled from Android, we've introduced a higher-level 
[AsyncResult](https://github.com/ServiceStack/ServiceStack.Java/blob/master/src/AndroidClient/client/src/main/java/net/servicestack/client/AsyncResult.java) 
abstract class which allows capturing of Async callbacks using an idiomatic anonymous Java class to provide an 
optimal dev experience for Java 7 on Android.

::: info
`AsyncResult` is modelled after [jQuery.ajax](http://api.jquery.com/jquery.ajax/) and allows specifying 
**success()**, **error()** and **complete()** callbacks as needed
:::

To provide an optimal experience for Kotlin and Java 8, we've added 
[SAM overloads](https://kotlinlang.org/docs/reference/java-interop.html#sam-conversions) 
using the alternative `AsyncSuccess<T>`, `AsyncSuccessVoid` and `AsyncError` interfaces which as they only 
contain a single method are treated like a lambda in Kotlin/Java 8, so instead of using the more verbose 
`AsyncResult<T>` overloads:

```kotlin
client.getAsync(Overview(), object: AsyncResult<OverviewResponse>() {
    override fun success(response: OverviewResponse?) {
        var topUsers = response!!.TopUsers
    }
    override fun error(ex: Exception?) {
        ex?.printStackTrace()
    }
})
```

You can instead use the equivalent and more succinct `AsyncSuccess<T>` API:

```kotlin
client.getAsync(Overview(), AsyncSuccess<OverviewResponse> {
        var topUsers = it.TopUsers
    }, AsyncError {
        it.printStackTrace()
    })
```

### AsyncServiceClient API

The complete `AsyncServiceClient` API implemented by `AndroidServiceClient`:

```java
public interface AsyncServiceClient {
    <T> void sendAsync(IReturn<T> request, final AsyncResult<T> asyncResult);
    <T> void sendAsync(IReturn<T> request, final AsyncSuccess<T> success);
    <T> void sendAsync(IReturn<T> request, final AsyncSuccess<T> success, final AsyncError error);
    void sendAsync(IReturnVoid request, final AsyncResultVoid asyncResult);
    void sendAsync(IReturnVoid request, final AsyncSuccessVoid success);
    void sendAsync(IReturnVoid request, final AsyncSuccessVoid success, final AsyncError error);

    <T> void getAsync(IReturn<T> request, final AsyncResult<T> asyncResult);
    <T> void getAsync(IReturn<T> request, final AsyncSuccess<T> success);
    <T> void getAsync(IReturn<T> request, final AsyncSuccess<T> success, final AsyncError error);
    void getAsync(IReturnVoid request, final AsyncResultVoid asyncResult);
    void getAsync(IReturnVoid request, final AsyncSuccessVoid success);
    void getAsync(IReturnVoid request, final AsyncSuccessVoid success, final AsyncError error);
    <T> void getAsync(IReturn<T> request, final Map<String, String> queryParams, final AsyncResult<T> asyncResult);
    <T> void getAsync(IReturn<T> request, final Map<String, String> queryParams, AsyncSuccess<T> success);
    <T> void getAsync(String path, final Class responseType, final AsyncResult<T> asyncResult);
    <T> void getAsync(String path, final Class responseType, final AsyncSuccess<T> success);
    <T> void getAsync(String path, final Type responseType, final AsyncResult<T> asyncResult);
    <T> void getAsync(String path, final Type responseType, final AsyncSuccess<T> success);
    void getAsync(String path, final AsyncResult<byte[]> asyncResult);
    void getAsync(String path, final AsyncSuccess<byte[]> success);

    <T> void postAsync(IReturn<T> request, final AsyncResult<T> asyncResult);
    <T> void postAsync(IReturn<T> request, final AsyncSuccess<T> success);
    <T> void postAsync(IReturn<T> request, final AsyncSuccess<T> success, final AsyncError error);
    void postAsync(IReturnVoid request, final AsyncResultVoid asyncResult);
    void postAsync(IReturnVoid request, final AsyncSuccessVoid success);
    void postAsync(IReturnVoid request, final AsyncSuccessVoid success, final AsyncError error);
    <T> void postAsync(String path, final Object request, final Class responseType, final AsyncResult<T> asyncResult);
    <T> void postAsync(String path, final Object request, final Class responseType, final AsyncSuccess<T> success);
    <T> void postAsync(String path, final Object request, final Type responseType, final AsyncResult<T> asyncResult);
    <T> void postAsync(String path, final Object request, final Type responseType, final AsyncSuccess<T> success);
    <T> void postAsync(String path, final byte[] requestBody, final String contentType, final Class responseType, final AsyncResult<T> asyncResult);
    <T> void postAsync(String path, final byte[] requestBody, final String contentType, final Class responseType, final AsyncSuccess<T> success);
    <T> void postAsync(String path, final byte[] requestBody, final String contentType, final Type responseType, final AsyncResult<T> asyncResult);
    <T> void postAsync(String path, final byte[] requestBody, final String contentType, final Type responseType, final AsyncSuccess<T> success);
    void postAsync(String path, final byte[] requestBody, final String contentType, final AsyncResult<byte[]> asyncResult);
    void postAsync(String path, final byte[] requestBody, final String contentType, final AsyncSuccess<byte[]> success);

    <T> void putAsync(IReturn<T> request, final AsyncResult<T> asyncResult);
    <T> void putAsync(IReturn<T> request, final AsyncSuccess<T> success);
    <T> void putAsync(IReturn<T> request, final AsyncSuccess<T> success, final AsyncError error);
    void putAsync(IReturnVoid request, final AsyncResultVoid asyncResult);
    void putAsync(IReturnVoid request, final AsyncSuccessVoid success);
    void putAsync(IReturnVoid request, final AsyncSuccessVoid success, final AsyncError error);
    <T> void putAsync(String path, final Object request, final Class responseType, final AsyncResult<T> asyncResult);
    <T> void putAsync(String path, final Object request, final Class responseType, final AsyncSuccess<T> success);
    <T> void putAsync(String path, final Object request, final Type responseType, final AsyncResult<T> asyncResult);
    <T> void putAsync(String path, final Object request, final Type responseType, final AsyncSuccess<T> success);
    <T> void putAsync(String path, final byte[] requestBody, final String contentType, final Class responseType, final AsyncResult<T> asyncResult);
    <T> void putAsync(String path, final byte[] requestBody, final String contentType, final Class responseType, final AsyncSuccess<T> success);
    <T> void putAsync(String path, final byte[] requestBody, final String contentType, final Type responseType, final AsyncResult<T> asyncResult);
    <T> void putAsync(String path, final byte[] requestBody, final String contentType, final Type responseType, final AsyncSuccess<T> success);
    void putAsync(String path, final byte[] requestBody, final String contentType, final AsyncResult<byte[]> asyncResult);
    void putAsync(String path, final byte[] requestBody, final String contentType, final AsyncSuccess<byte[]> success);

    <T> void deleteAsync(IReturn<T> request, final AsyncResult<T> asyncResult);
    <T> void deleteAsync(IReturn<T> request, final AsyncSuccess<T> success);
    <T> void deleteAsync(IReturn<T> request, final AsyncSuccess<T> success, final AsyncError error);
    void deleteAsync(IReturnVoid request, final AsyncResultVoid asyncResult);
    void deleteAsync(IReturnVoid request, final AsyncSuccessVoid success);
    void deleteAsync(IReturnVoid request, final AsyncSuccessVoid success, final AsyncError error);
    <T> void deleteAsync(IReturn<T> request, final Map<String, String> queryParams, final AsyncResult<T> asyncResult);
    <T> void deleteAsync(IReturn<T> request, final Map<String, String> queryParams, final AsyncSuccess<T> success);
    <T> void deleteAsync(String path, final Class responseType, final AsyncResult<T> asyncResult);
    <T> void deleteAsync(String path, final Class responseType, final AsyncSuccess<T> success);
    <T> void deleteAsync(String path, final Type responseType, final AsyncResult<T> asyncResult);
    <T> void deleteAsync(String path, final Type responseType, final AsyncSuccess<T> success);
    void deleteAsync(String path, final AsyncResult<byte[]> asyncResult);
    void deleteAsync(String path, final AsyncSuccess<byte[]> success);
}
```

The `AsyncServiceClient` interface is implemented by the `AndroidServiceClient` concrete class which 
behind-the-scenes uses an Android [AsyncTask](http://developer.android.com/reference/android/os/AsyncTask.html) 
to implement its Async API's. 

Whilst the `AndroidServiceClient` is contained in the **net.servicestack:android** dependency and only works in 
Android, the `JsonServiceClient` instead is contained in a seperate pure Java **net.servicestack:client** 
dependency which can be used independently to provide a typed Java API for consuming ServiceStack Services 
from any Java or Kotlin JVM application.

### Async API Usage

To make use of Async API's in an Android App (which you'll want to do to keep web service requests off the 
Main UI thread), you'll instead need to use an instance of `AndroidServiceClient` which as it inherits 
`JsonServiceClient` can be used to perform both Sync and Async requests:

```kotlin
val client = AndroidServiceClient("https://techstacks.io")
```

Like other Service Clients, there's an equivalent Async API matching their Sync counterparts which differs 
by ending with an **Async** suffix which instead of returning a typed response, fires the supplied callback 
with the typed response, e.g: 

```kotlin
client.getAsync(AppOverview(), AsyncSuccess<AppOverviewResponse> {
    val allTiers = it.AllTiers
    val topTech = it.TopTechnologies
})
```

Which just like the `JsonServiceClient` Sync examples above also provide a number of flexible options to execute 
Custom Async Web Service Requests, e.g: 

```kotlin
client.getAsync("/overview", OverviewResponse::class.java,
    AsyncSuccess<OverviewResponse?> {  
    })
```

Calling a Web Service using an absolute url:

```kotlin
client.getAsync("https://techstacks.io/overview", OverviewResponse::class.java,
    AsyncSuccess<OverviewResponse>() {
    })
```

#### Async AutoQuery Example

Calling an untyped AutoQuery Service with additional untyped Dictionary String arguments:

```kotlin
client.getAsync(FindTechnologies(), hashMapOf(Pair("DescriptionContains", "framework")),
    AsyncSuccess<QueryResponse<Technology>>() {
    })
```

#### Download Raw Image Async Example

Example downloading raw Image bytes and loading it into an Android Image `Bitmap`:

```kotlin
client.getAsync("https://servicestack.net/img/logo.png", {
    val img = BitmapFactory.decodeByteArray(it, 0, it.size);
})
```

#### Send Raw String or byte[] Requests

You can easily get the raw string Response from Request DTO's that return are annotated with `IReturn<string>`, e.g:
 
```java
open class HelloString : IReturn<String> { ... }

var request = HelloString()
request.name = "World"

val response:String? = client.get(request)
```

You can also specify that you want the raw UTF-8 `byte[]` or `String` response instead of a the deserialized 
Response DTO by specifying the Response class you want returned, e.g:

```kotlin
val response:ByteArray = client.get("/hello?Name=World", ByteArray::class.java);
```

#### Kotlin HTTP Marker Interfaces

Like the .NET and Swift Service Clients, the HTTP Interface markers are also annotated on Kotlin DTO's and let 
you use the same `send` API to send Requests via different HTTP Verbs, e.g:  

```kotlin
open class HelloGet : IReturn<HelloVerbResponse>, IGet { ... }
open class HelloPut : IReturn<HelloVerbResponse>, IPut { ... }

val response = client.send(HelloGet()) //GET

client.sendAsync(HelloPut(),           //PUT
    AsyncSuccess<HelloVerbResponse> { });
```

#### IReturnVoid Support

Sync/Async overloads are also available for `IReturnVoid` Request DTO's:

```kotlin
client.delete(DeleteCustomer())
```

### Typed Error Handling

Thanks to Kotlin also using typed Exceptions for error control flow, error handling in Kotlin will be instantly 
familiar to C# devs which also throws a typed `WebServiceException` containing the remote servers structured 
error data:

```kotlin
var request = ThrowType()
request.Type = "NotFound"
request.message = "not here"

try {
    val response = client.post(request)
} catch(webEx: WebServiceException) {
    val status = webEx.responseStatus
    status.message    //= not here
    status.stackTrace //= (Server StackTrace)
}
```

Likewise structured Validation Field Errors are also accessible from the familiar `ResponseStatus` DTO, e.g:

```kotlin
var request = ThrowValidation()
request.email = "invalidemail"

try {
    client.post(request);
} catch (webEx: WebServiceException){
    val status = webEx.responseStatus

    val firstError = status.errors[0]
    firstError.errorCode //= InclusiveBetween
    firstError.message   //= 'Age' must be between 1 and 120. You entered 0.
    firstError.fieldName //= Age
}
```

#### Async Error Handling
Async Error handling differs where in order to access the `WebServiceException` you'll need to implement the **error(Exception)** callback, e.g:

```kotlin
client.postAsync(request, AsyncSuccess<ThrowTypeResponse> { },
    AsyncError {
        val webEx = it as WebServiceException

        val status = webEx.responseStatus
        status.message    //= not here
        status.stackTrace //= (Server StackTrace)
    })
```

Async Validation Errors are also handled in the same way: 

```kotlin
client.postAsync(request, AsyncSuccess<ThrowValidationResponse> { },
    AsyncError {
        val webEx = it as WebServiceException

        val status = webEx.responseStatus
        val firstError = status.errors[0]
        firstError.errorCode //= InclusiveBetween
        firstError.message   //= 'Age' must be between 1 and 120. You entered 0.
        firstError.fieldName //= Age
    })
```

### JsonServiceClient Error Handlers
To make it easier to generically handle Web Service Exceptions, the Java Service Clients also support static Global Exception handlers by assigning `AndroidServiceClient.GlobalExceptionFilter`, e.g:

```kotlin
AndroidServiceClient.GlobalExceptionFilter = ExceptionFilter { res:HttpURLConnection?, ex ->
}
```

As well as local Exception Filters by specifying a handler for `client.ExceptionFilter`, e.g:

```kotlin
client.ExceptionFilter = ExceptionFilter { res:HttpURLConnection?, ex ->
}
```

### More Usage Examples

You can find more sync and async Kotlin ServiceClient examples in the links below:

 - [Kotlin ServiceClient Tests](https://github.com/ServiceStack/ServiceStack.Java/tree/master/src/AndroidClient/kotlin/src/androidTest/java/test/servicestack/net/kotlin)
 - [TechStacks Kotlin App](https://github.com/ServiceStackApps/TechStacksKotlinApp)

## Kotlin generated DTO Types

Our goal with **Kotlin Add ServiceStack Reference** is to ensure a high-fidelity, idiomatic translation within 
the constraints of Kotlin language and its built-in libraries, where .NET Server DTO's are translated into 
clean, conventional Kotlin classes where .NET built-in Value Types mapped to their equivalent JVM data Type.

To see what this ends up looking up we'll go through some of the 
[Generated Test Services](https://test.servicestack.net/types/kotlin) to see how they're translated in Kotlin.

### .NET Attributes translated into Java Annotations
By inspecting the `HelloAllTypes` Request DTO we can see that C# Metadata Attributes e.g. `[Route("/all-types")]` 
are also translated into the typed Kotlin Annotations defined in the **net.servicestack:client** dependency. 
But as JVM only supports defining a single Annotation of the same type, any subsequent .NET Attributes of 
the same type are emitted in comments.

### Terse, typed API's with IReturn interfaces
Kotlin Request DTO's are also able to take advantage of the `IReturn<TResponse>` interface marker to provide 
its terse, typed generic API but due to JVM's Type erasure the Response Type also needs to be encoded in the 
Request DTO as seen by the `responseType` static companion property:

```java
@Route("/all-types")
open class HelloAllTypes : IReturn<HelloAllTypesResponse>
{
    var name:String? = null
    var allTypes:AllTypes? = null
    var allCollectionTypes:AllCollectionTypes? = null
    companion object { private val responseType = HelloAllTypesResponse::class.java }
    override fun getResponseType(): Any? = responseType
}
```

### DTO Property Behavior

To comply with Gson JSON Serialization rules, the public DTO properties are emitted in the same JSON naming 
convention as the remote ServiceStack server which for the [test.servicestack.net](https://test.servicestack.net) 
Web Services, follows its **camelCase** naming convention that is configured in its AppHost with: 

```csharp
JsConfig.Init(new Config { TextCase = TextCase.CamelCase });
```

### Kotlin Type Conversions

By inspecting the `AllTypes` DTO properties we can see what Kotlin Type each built-in .NET Type gets translated 
into. In each case it selects the most suitable concrete datatype available, inc. generic collections. 
We also see nullable reference types are used since DTO properties are optional and need to be nullable, whlist 
collection types are default initialized to an empty collection to make it simplify its usage in Kotlin:

```kotlin
open class AllTypes
{
    var id:Int? = null
    var nullableId:Int? = null
    @SerializedName("byte") var Byte:Short? = null
    @SerializedName("short") var Short:Short? = null
    @SerializedName("int") var Int:Int? = null
    @SerializedName("long") var Long:Long? = null
    var uShort:Int? = null
    var uInt:Long? = null
    var uLong:BigInteger? = null
    @SerializedName("float") var Float:Float? = null
    @SerializedName("double") var Double:Double? = null
    var decimal:BigDecimal? = null
    var string:String? = null
    var dateTime:Date? = null
    var timeSpan:TimeSpan? = null
    var dateTimeOffset:Date? = null
    var guid:UUID? = null
    @SerializedName("char") var Char:String? = null
    var nullableDateTime:Date? = null
    var nullableTimeSpan:TimeSpan? = null
    var stringList:ArrayList<String> = ArrayList<String>()
    var stringArray:ArrayList<String>? = null
    var stringMap:HashMap<String,String> = HashMap<String,String>()
    var intStringMap:HashMap<Int,String> = HashMap<Int,String>()
    var subType:SubType? = null
}
```

The only built-in Value Type that didn't have a suitable built-in Java equivalent was `TimeSpan`. 
In this case it uses our new 
[TimeSpan.java](https://github.com/ServiceStack/ServiceStack.Java/blob/master/src/AndroidClient/client/src/main/java/net/servicestack/client/TimeSpan.java) 
class which implements the same familiar API available in .NET's `TimeSpan`. 

Something else you'll notice is that some fields are annotated with the `@SerializedName()` Gson annotation. 
This is automatically added for Kotlin keywords. The first time a Gson annotation is referenced it also 
automatically includes the required Gson namespace imports. If needed, this can also be explicitly added by with:
```csharp
KotlinGenerator.AddGsonImport = true;
```

### Kotlin Enums
.NET enums are also translated into typed Kotlin enums where basic enums end up as a straightforward translation, e.g:

```kotlin
enum class BasicEnum
{
    Foo,
    Bar,
    Baz,
}
```

Whilst as Kotlin doesn't support integer Enum flags directly the resulting translation ends up being a bit more convoluted:

```kotlin
@Flags()
enum class EnumFlags(val value:Int)
{
    @SerializedName("1") Value1(1),
    @SerializedName("2") Value2(2),
    @SerializedName("4") Value3(4),
}
```

## Kotlin Configuration
The header comments in the generated DTO's allows for further customization of how the DTO's are generated 
which can then be updated with any custom Options provided using the **Update ServiceStack Reference** Menu Item 
in Android Studio. Options that are preceded by a single line Java comment `//` are defaults from the server 
which can be overridden.

To override a value, remove the `//` and specify the value to the right of the `:`. Any value uncommented will 
be sent to the server to override any server defaults.

```kotlin
/* Options:
Date: 2015-12-17 05:17:47
Version: 4.051
Tip: To override a DTO option, remove "//" prefix before updating
BaseUrl: https://techstacks.io

Package: servicestack.net.techstacks
//AddServiceStackTypes: True
//AddResponseStatus: False
//AddImplicitVersion: 
//IncludeTypes: 
//ExcludeTypes: 
//InitializeCollections: True
//TreatTypesAsStrings: 
//DefaultImports: java.math.*,java.util.*,net.servicestack.client.*,com.google.gson.annotations.*,com.google.gson.reflect.*
*/
```
We'll go through and cover each of the above options to see how they affect the generated DTO's:

### Package
Specify the package name that the generated DTO's are in:
```
Package: net.servicestack.techstacks
```
Will generate the package name for the generated DTO's as:

```kotlin
package servicestack.net.techstacks
```

### AddServiceStackTypes
Lets you exclude built-in ServiceStack Types and DTO's from being generated with:
```
AddServiceStackTypes: False
```
This will prevent Request DTO's for built-in ServiceStack Services like `Authenticate` from being emitted.

### AddImplicitVersion
Lets you specify the Version number to be automatically populated in all Request DTO's sent from the client:
```
AddImplicitVersion: 1
```
Which will embed the specified Version number in each Request DTO, e.g:

```kotlin
open class GetTechnology : IReturn<GetTechnologyResponse>
{
    val Version:Int = 1
}

```
This lets you know what Version of the Service Contract that existing clients are using making it easy to implement [ServiceStack's recommended versioning strategy](http://stackoverflow.com/a/12413091/85785).

### IncludeTypes
Is used as a Whitelist that can be used to specify only the types you would like to have code-generated:
```
/* Options:
IncludeTypes: GetTechnology,GetTechnologyResponse
```
Will only generate `GetTechnology` and `GetTechnologyResponse` DTO's, e.g:

```kotlin
open class GetTechnology : IReturn<GetTechnologyResponse> { ... }
open class GetTechnologyResponse { ... }
```

#### Include Request DTO and its dependent types

You can include a Request DTO and all its dependent types with a `.*` suffix on the Request DTO, e.g:

```
/* Options:
IncludeTypes: GetTechnology.*
```

Which will include the `GetTechnology` Request DTO, the `GetTechnologyResponse` Response DTO and all Types that they both reference.

#### Include All Types within a C# namespace

If your DTOs are grouped into different namespaces they can be all included using the `/*` suffix, e.g:

```
/* Options:
IncludeTypes: MyApp.ServiceModel.Admin/*
```

This will include all DTOs within the `MyApp.ServiceModel.Admin` C# namespace. 

#### Include All Services in a Tag Group

Services [grouped by Tag](/api-design#group-services-by-tag) can be used in the `IncludeTypes` where tags can be specified using braces in the format `{tag}` or `{tag1,tag2,tag3}`, e.g:

```
/* Options:
IncludeTypes: {web,mobile}
```

Or individually:

```
/* Options:
IncludeTypes: {web},{mobile}
```

### ExcludeTypes
Is used as a Blacklist where you can specify which types you would like to exclude from being generated:
```
/* Options:
ExcludeTypes: GetTechnology,GetTechnologyResponse
```
Will exclude `GetTechnology` and `GetTechnologyResponse` DTO's from being generated.

### DefaultImports
Lets you override the default import packages included in the generated DTO's:
```
DefaultImports: java.math.*,java.util.*,net.servicestack.client.*,com.acme.custom.*
```
Will override the default imports with the ones specified, i.e: 

```kotlin
import java.math.*
import java.util.*
import net.servicestack.client.*
import com.acme.custom.*
```

By default the generated DTO's do not require any Google's Gson-specific serialization hints, but when they're 
needed e.g. if your DTO's use Kotlin keywords or are attributed with `[DataMember(Name=...)]` the required Gson 
imports are automatically added which can also be added explicitly with:
```csharp
JavaGenerator.AddGsonImport = true;
```
Which will add the following Gson imports:
```java
import com.google.gson.annotations.*
import com.google.gson.reflect.*
```

### TreatTypesAsStrings

Due to the [unusual encoding of Guid bytes](http://stackoverflow.com/a/18085116/85785) it may be instead be 
preferential to treat Guids as opaque strings so they are easier to compare back to their original C# Guids. 
This can be enabled with the new `TreatTypesAsStrings` option:

```
/* Options:
...
TreatTypesAsStrings: Guid

*/
```

## Example [TechStacks Android App](https://github.com/ServiceStackApps/TechStacksKotlinApp)
To demonstrate Kotlin Native Types in action we've ported the Java 
[TechStacks Android App](https://github.com/ServiceStackApps/TechStacksAndroidApp) to a native 
Android App written in Kotlin to showcase the responsiveness and easy-of-use of leveraging 
Kotlin Add ServiceStack Reference in Android Projects. 

[![](https://raw.githubusercontent.com/ServiceStack/Assets/master/img/release-notes/techstacks-kotlin-app.png)](https://github.com/ServiceStackApps/TechStacksAndroidApp)

Checkout the [TechStacks Kotlin Android App](https://github.com/ServiceStackApps/TechStacksKotlinApp) 
repository for a nice overview of how it leverages Kotlin Native Types and iOS-inspired Data Binding to easily 
develop services-heavy Mobile Apps.


# Dart Add ServiceStack Reference
Source: https://docs.servicestack.net/dart-add-servicestack-reference

![Dart Banner](/img/pages/dart/dart.png)

ServiceStack's **Add ServiceStack Reference** feature allows clients to generate Native Types from a simple [@servicestack/cli command-line utility](https://github.com/ServiceStack/servicestack-cli#servicestackcli) - providing a simple way to give clients typed access to your ServiceStack Services.

## Dart Android Example using Android Studio

<lite-youtube class="w-full mx-4 my-4" width="560" height="315" videoid="ocH5L-CikQ0" style="background-image: url('https://img.youtube.com/vi/ocH5L-CikQ0/maxresdefault.jpg')"></lite-youtube>
<lite-youtube class="w-full mx-4 my-4" width="560" height="315" videoid="EwOwbZ9mUZk" style="background-image: url('https://img.youtube.com/vi/EwOwbZ9mUZk/maxresdefault.jpg')"></lite-youtube>

### Dart ServiceStack Reference

Dart ServiceStack Reference supports **all Dart 2.0 platforms**, including Flutter and AngularDart or Dart Web Apps - in the same optimal development workflow pioneered in [Add ServiceStack Reference](/add-servicestack-reference) where it doesn't requiring any additional tooling, transformers or build steps. 

Due to the lack of reflection and Mirror support, consuming JSON APIs can be quite [cumbersome in Flutter](https://flutter.io/cookbook/networking/fetch-data/). But we've been able to achieve the same productive development experience available in [all supported languages](/add-servicestack-reference) where you can use the generated Dart DTOs from any remote v5.1+ ServiceStack endpoint with ServiceStack's Smart generic
[JsonServiceClient](https://pub.dartlang.org/documentation/servicestack/0.0.7/client/JsonServiceClient-class.html) available in the [servicestack Dart package](https://pub.dartlang.org/packages/servicestack#-installing-tab-), to enable an end-to-end Typed API for calling Services by [sending and receiving native DTOs](/architecture-overview#client-architecture).

### Install

You can use the same [x dotnet tool](/dotnet-tool) simple command-line utility to easily Add and Update ServiceStack References for all supported languages:

Install [.NET SDK](https://dotnet.microsoft.com/download) then install the `x` dotnet tool:

:::sh
dotnet tool install --global x
:::

::include npx-get-dtos.md::

### Example Usage

You can then execute `x dart` with the URL of the remote ServiceStack Instance you want to generated DTOs for, e.g:

:::sh
`x dart https://techstacks.io`
:::

This will generate Dart DTOs for the [entire TechStacks API](https://techstacks.io/metadata):

```
Saved to: dtos.dart
```

::: info
If no name is specified in the 2nd argument, it uses `dtos` if it doesn't exist, otherwise falls back to infer it from the URL
:::

To make API calls we need to use the `JsonServiceClient`, installed by adding the [servicestack](https://pub.dartlang.org/packages/servicestack#-installing-tab-) package to our Dart projects `pubspec.yaml`:

```yaml
dependencies:
  servicestack: ^2.0.1
```

Saving `pubspec.yaml` in VS Code with the [Dart Code Extension](https://dartcode.org) automatically calls `pub get` or `flutter packages get` (in Flutter projects) to add any new dependencies to your project.

We now have everything we need to be able to make typed API requests to any of [TechStacks APIs](https://techstacks.io/metadata) with a shared `JsonServiceClient` instance populated with the base URL of the remote endpoint, e.g:

```dart
import 'package:servicestack/client.dart';

import 'dtos.dart';

var client = JsonServiceClient("https://techstacks.io");

main() async {
  var response = await client.get(GetTechnology(slug: "flutter"));
  print("${response.technology.name}: ${response.technology.vendorUrl}");
}
```

Like C#, Dart has Generics and Type Inference so the `response` returned is the typed `HelloResponse` DTO giving us rich intelli-sense and compiler type safety. 

### Platform neutral usage

Both **dart:io** `JsonServiceClient` and **dart:html** `JsonWebClient` implement the same shared `IServiceClient` interface which support a platform-neutral source-compatible API using the
`ClientFactory` APIs, e.g: 

```dart
import 'package:servicestack/web_client.dart' if (dart.library.io) 'package:servicestack/client.dart';

main() async {
  var client = ClientFactory.create('https://techstacks.io');
  var response = await client.get(GetTechnology(slug: "flutter"));
  print("${response.technology.name}: ${response.technology.vendorUrl}");
}
```

For advanced configuration you can use the `createWith(ClientOptions)` API, e.g you can use `dev.servicestack.com` which resolves to `10.0.2.2` 
which in Android you can use to access `127.0.0.1` of the host OS allowing you to access your local development server.

In this example we'll create either a typed Service Client to our local development server in **Debug** during development (ignoring its self-signed certificate)
and our production server in **Release** mode: 

```dart
import 'package:servicestack/web_client.dart' if (dart.library.io) 'package:servicestack/client.dart';
import 'package:flutter/foundation.dart';

main() async {
  var client = kDebugMode
    ? ClientFactory.createWith(ClientOptions(baseUrl:'https://dev.servicestack.com:5001', ignoreCert:true))
    : ClientFactory.create('https://techstacks.io');
}
```

::: info Tip
If you add a `127.0.0.1 dev.servicestack.com` mapping in your OS's `hosts` file you'll also be able to use `dev.servicestack.com` to access your local dev server in your Host OS
:::

### Shared Initialization Configuration

For more advanced configuration you can use the `ClientConfig.initClient` client factory filter to customize all service client instances 
as done in this example to configure all client instances with any previously saved JWT Bearer & Refresh Tokens to enable authenticated access:

```dart
import 'package:flutter/foundation.dart';
import 'package:shared_preferences/shared_preferences.dart';
import 'package:servicestack/web_client.dart' if (dart.library.io) 'package:servicestack/client.dart';

SharedPreferences prefs;
IServiceClient client;
AuthenticateResponse auth;

Future<void> main() async {
  runApp(MyApp());

  ClientConfig.initClient = (client) {
    if (auth != null) {
      client.bearerToken = auth.bearerToken;
      client.refreshToken = auth.refreshToken;
    }
  };

  prefs = await SharedPreferences.getInstance();

  var json = prefs.getString('auth');
  auth = json != null
      ? AuthenticateResponse.fromJson(jsonDecode(json))
      : null;

  client = ClientFactory.createWith(ClientOptions(
      baseUrl:'https://dev.servicestack.com:5001', ignoreCert:kDebugMode));
}
```

#### AngularDart and Dart Web Usage

For AngularDart or Dart Web Apps import `web_client.dart` and use the `JsonWebClient`:

```dart
import 'package:servicestack/web_client.dart';

import 'dtos.dart';              // Add ServiceStack Reference DTOs

//...
var client = JsonWebClient("https://techstacks.io");
var response = await client.get(GetTechnology(slug: "flutter"));
```

See the [HelloAngularDart](https://github.com/ServiceStackApps/HelloAngularDart) project for a working example.

#### Platform agnostic Usage

For creating libraries that can be consumed in any Dart platform reference `servicestack.dart` and use the `IServiceClient` interface which
is implemented by both `JsonServiceClient` and `JsonWebClient`:

```dart
import 'package:servicestack/servicestack.dart';

import 'dtos.dart';              // Add ServiceStack Reference DTOs

//...
fetchTechnologies(IServiceClient client) async {
    var response = await client.get(GetTechnology(slug: "flutter"));
}
```

### Rich Generated Models

Thanks to the direct C# to Dart model code generation we're able to create the ideal idiomatic message-based APIs utilizing rich typed models with broad support for many of the C#/.NET features used when defining DTOs inc. Generics, Inheritance, multiple Interfaces, Enums (inc. int and Flag Enums), Tuples, metadata Attributes emitted in comments (emitting additional documentation in the generated models) whilst also taking care of mapping built-in C# Types like `DateTime`, `TimeSpan`, `byte[]` and `Stream` into their equivalent native Dart [DateTime](https://api.dartlang.org/stable/1.24.3/dart-core/DateTime-class.html), [Duration](https://api.dartlang.org/stable/1.24.3/dart-core/Duration-class.html) and [Uint8List](https://api.dartlang.org/stable/1.24.3/dart-typed_data/Uint8List-class.html) types, C# generic collections are also converted into their equivalent Dart generic collection Type.


#### JsonCodec compatible

The generated DTOs follow Dart's [JsonCodec](https://api.dartlang.org/stable/1.24.3/dart-convert/JsonCodec-class.html) pattern allowing them to be individually serializable with Dart's universal JSON encode/decode APIs, e.g:

```dart
//Serialization
var dto = MyDto(name:"foo");
String jsonString = json.encode(dto);

//Deserialization
Map<String,dynamic> jsonObj = json.decode(jsonString);
var fromJson = MyDto.fromJson(jsonObj);
```

#### Default Constructor

All DTOs also include a default constructor containing all properties as optional arguments providing a wrist-friendly syntax for creating and populating DTOs in a single constructor expression, e.g:

```dart
var request = MyDto(name:"foo");
```

Only the properties of each DTO are included in its default constructor so you'll need to use property accessors to initialize any fields in base classes, but thanks to Dart's support for method cascades you can still populate an entire DTO with a single expression, e.g:

```dart
var request = FindTechnologies(name:"Flutter")
    ..fields = "id,slug,vendorName,productUrl"
    ..orderBy = "created,-viewCount"
    ..take = 1;
```

#### IConvertible

All DTOs implement the `IConvertible` interface below where each instance can be converted to and from a Map of values, giving each model dynamism that's otherwise not possible in Flutter:

```csharp
abstract class IConvertible
{
    TypeContext context;
    fromMap(Map<String, dynamic> map);
    Map<String, dynamic> toJson();
}
```

The conversion logic that handles the behind-the-scenes conversion into and out of Dart Types is maintained in the extensible [JsonConverters](https://pub.dartlang.org/documentation/servicestack/0.0.7/client/JsonConverters/Converters.html) class which lets you replace built-in converters with your own implementation or register new Converters when you want to take over handling of specific types.

### JsonServiceClient

The `JsonServiceClient` is a smart full-featured Service Client implementation with a number of high-level features that make consuming ServiceStack APIs a seamless experience, with built-in support for:

 - HTTP Basic Auth (inc. [API Key support](/auth/api-key-authprovider))
 - [Cookies, Sessions and Credential Auth](/auth/sessions)
 - [JWT, including using RefreshTokens to auto-fetch new JWT Bearer Tokens](/auth/jwt-authprovider)
 - [Structured Error Handling](/error-handling)
 - [Auto Batched Requests](/auto-batched-requests)
 - Global and per-instance Request, Response and Exception Filters
 - `onAuthenticationRequired` hook to handle re-authentication and transparent replay of failed 401 requests

Behind the scenes `JsonServiceClient` leverages the optimal [`HttpClient` in dart:io](https://docs.flutter.io/flutter/dart-io/HttpClient-class.html) to perform HTTP Requests in Flutter and Dart VM Apps.

### JsonWebClient

The `JsonWebClient` performs HTTP Requests using [dart:html BrowserClient](https://webdev.dartlang.org/angular/guide/server-communication) to use the browsers built-in `XMLHttpRequest` object. Despite their implementation differences `JsonWebClient` also supports the same feature-set as the Dart VM's `JsonServiceClient` above. 

AngularDart or Dart Web Apps can use `JsonWebClient` by importing `web_client.dart`, e.g: 

```dart
import 'package:servicestack/web_client.dart';

var client = JsonWebClient("https://techstacks.io");
```

### IServiceClient API

Both JSON Service Client variants implement the same flexible `IServiceClient` API below, use the same DTOs and implementation and throws the same structured `WebServiceException` which results in Typed API Requests being source-compatible between Dart Web Apps, Dart VM Server and AOT compiled Flutter Web Apps:

```csharp
abstract class IServiceClient {
  String? baseUrl;
  String? replyBaseUrl;
  String? oneWayBaseUrl;

  String? bearerToken;
  String? refreshToken;
  String? userName;
  String? password;

  AsyncCallbackFunction? onAuthenticationRequired;
  String? getTokenCookie();
  String? getRefreshTokenCookie();

  void clearCookies();

  Future<ApiResult<T>> api<T>(IReturn<T> request, {Map<String, dynamic>? args, String? method});

  Future<ApiResult<EmptyResponse>> apiVoid(IReturnVoid request, {Map<String, dynamic>? args, String? method});

  Future<T> get<T>(IReturn<T> request, {Map<String, dynamic>? args});

  Future<Map<String, dynamic>> getUrl(String path, {Map<String, dynamic>? args});

  Future<T> getAs<T>(String path, {Map<String, dynamic>? args, T? responseAs});

  Future<T> post<T>(IReturn<T> request, {dynamic body, Map<String, dynamic>? args});

  Future<Map<String, dynamic>> postToUrl(String path, dynamic body, {Map<String, dynamic>? args});

  Future<T> postAs<T>(String path, dynamic body, {Map<String, dynamic>? args, T? responseAs});

  Future<T> delete<T>(IReturn<T> request, {Map<String, dynamic>? args});

  Future<Map<String, dynamic>> deleteUrl(String path, {Map<String, dynamic>? args});

  Future<T> deleteAs<T>(String path, {Map<String, dynamic>? args, T? responseAs});

  Future<T> put<T>(IReturn<T> request, {dynamic body, Map<String, dynamic>? args});

  Future<Map<String, dynamic>> putToUrl(String path, dynamic body, {Map<String, dynamic>? args});

  Future<T> putAs<T>(String path, dynamic body, {Map<String, dynamic>? args, T? responseAs});

  Future<T> patch<T>(IReturn<T> request, {dynamic body, Map<String, dynamic>? args});

  Future<Map<String, dynamic>> patchToUrl(String path, dynamic body, {Map<String, dynamic> args});

  Future<T> patchAs<T>(String path, dynamic body, {Map<String, dynamic>? args, T? responseAs});

  Future<List<T>> sendAll<T>(Iterable<IReturn<T>> requests);

  Future<void> sendAllOneWay<T>(Iterable<IReturn<T>> requests);

  Future<T> send<T>(IReturn<T> request, {String? method, Map<String, dynamic>? args, T? responseAs});

  void close({bool force = false});
}
```

#### Concrete-specific functionality

In addition to implementing the `IServiceClient` above, each Service Client includes additional concrete specific functionality allowing for finer-grained access to their underlying HTTP Clients, e.g. as the Request/Response filters have different Type signatures (dart:io's `HttpClientResponse` vs Browser's `Response`) they can't be declared in the shared `IServiceClient` interface, but thanks to Dart's type inference many of the extended concrete APIs are still source-compatible, e.g:

```dart
var vmClient = JsonServiceClient(baseUrl)
    ..responseFilter = (res) => print(res.headers["X-Args"]);

var webClient = JsonWebClient(baseUrl)
    ..responseFilter = (res) => print(res.headers["X-Args"]);
```

### Uploading Files

The `postFileWithRequest` method can be used to upload a file with an API Request.

### Dart Speech to Text

Here's an example calling [AI Server's](/ai-server/) `SpeechToText` API:

```dart
var audioFile = new File('audio.wav');
var uploadFile = new UploadFile(
    fieldName: 'audio',
    fileName: audioFile.uri.pathSegments.last,
    contentType: 'audio/wav',
    contents: await audioFile.readAsBytes()
);

var response = await client.postFileWithRequest(new SpeechToText(), uploadFile);
```

To upload multiple files use `postFilesWithRequest`.


#### Comprehensive Test Suite

To ensure a high quality implementation we've ported the [TypeScript @servicestack/client](https://github.com/ServiceStack/servicestack-client) test suite over to Dart which is itself a good resource for discovering [different supported features and flexible HTTP Request options](https://github.com/ServiceStack/servicestack-dart/tree/master/test) available. 

### HelloFlutter App

To showcase popular API Requests in action we've created a basic [HelloFlutter](https://github.com/ServiceStackApps/HelloFlutter) App that mimics functionality in the [HelloMobile](https://github.com/ServiceStackApps/HelloMobile) App used to provide working examples of the same ServiceStack Service Client features running in the different supported Mobile and Desktop platforms.

[HelloFlutter](https://github.com/ServiceStackApps/HelloFlutter) was created in VS Code with the [DartCode extension](https://dartcode.org) using the [Flutter: New Project](https://flutter.io/get-started/test-drive/#vscode) action in VS Code's Command Palette.

This creates a basic Flutter App which you can run in your Android Device or Android Emulator where it's automatically picked and made visible in the **bottom right** of VS Code's status bar.

Then to use `JsonServiceClient` add the `servicestack` dependency to your apps [pubspec.yaml](https://github.com/ServiceStackApps/HelloFlutter/blob/master/pubspec.yaml):

  dependencies:
    servicestack: ^2.0.1

Saving `pubspec.yaml` automatically runs [flutter packages get](https://flutter.io/using-packages/) to install any new dependencies in your App. 

Our App will be making API calls to 2 different ServiceStack instances which we'll need to get typed DTOs for using the `x` command-line utility:

```bash
cd lib
x dart https://techstacks.io
x dart https://test.servicestack.net test
```

Which will save the DTOs for each endpoint in different files:

```
Saved to: dtos.dart
Saved to: test.dtos.dart
```

Incidentally you can get the latest version for all Dart Service References by running `x dart` without arguments:

:::sh
x dart
:::

Which updates all Dart references in the current directory, including any customization options available in the header of each file:

```
Updated: test.dtos.dart
Updated: dtos.dart
```

This gives us everything we need to call Web Services in our Flutter App, by importing `package:servicestack/client.dart` containing `JsonServiceClient` as well as any generated DTOs.

Then create new `JsonServiceClient` instances initialized with the `BaseUrl` for each of the remote endpoints we want to call:

```dart
import 'package:servicestack/client.dart';

import 'test.dtos.dart';
import 'dtos.dart';

const TestBaseUrl = "https://test.servicestack.net";
const TechStacksBaseUrl = "https://techstacks.io";

var testClient = JsonServiceClient(TestBaseUrl);
var techstacksClient = JsonServiceClient(TechStacksBaseUrl);
```

### HelloFlutter UI

Flutter works similarly to React and React Native where you need to return the entire UI layout for your Widget in its `Widget build(BuildContext context)` method, akin to React's `render()` method. For complete reference the app is contained in [lib/main.dart](https://github.com/ServiceStackApps/HelloFlutter/blob/master/lib/main.dart), but for clarity we'll just highlight the relevant parts in each section. 

Our widget requires some state to render its UI so our widget needs to inherit `StatefulWidget`. Stateful widgets require an additional supporting class for reasons [explained in this Thread](https://github.com/flutter/flutter/issues/8794):

::: info 
With a stateful widget, it's common to make closures whose life cycle are tied to the state's life cycle, which lasts through multiple widgets. With a stateless widget, it's common to make closures whose life cycle are tied to the widget's life cycle, which doesn't cause a problem
:::

Ultimately this results in following the same dual class pattern below where the `HelloFlutterState` defines the state it needs as instance fields, this state is preserved across Hot Module reloads which is how Dart can update a live running App despite the implementation of the class changing.

```dart
class HelloFlutter extends StatefulWidget {
  @override
  State<StatefulWidget> createState() => HelloFlutterState();
}

class HelloFlutterState extends State<HelloFlutter> {
  //State for this widget
  String result = "";
  Uint8List imageBytes = Uint8List(0);

  @override
  Widget build(BuildContext context) {

      //...
      RaisedButton(
        child: Text("Async"),
        onPressed: () async {
          var r = await testClient.get(Hello(name: "Async"));
          setState(() {
            result = r.result;
          });
        },
      ),

      //...
      result != null && result != "" 
          ? Text(result) 
          : Image.memory(imageBytes, width:500.0, height:170.0),
  }
}
```

HelloFlutter's UI consists of 6 buttons across the top of the screen and an area to display the results of each call in the Widget's body. Each of the example Requests will populate either the `result` String for standard JSON responses or `imageBytes` for the `HelloImage` Service returning binary data.

#### Standard API Requests

The first **Async** example shows an example of the most popular API Request for calling ServiceStack Services, simply by sending a populated Request DTO that returns a populated Response DTO, in this case sending a `Hello` Request DTO that returns a `HelloResponse` DTO:

```dart
var r = await testClient.get(Hello(name: "Async"));
setState(() {
  result = r.result;
});
```

To update the UI any modified State needs to be done within the `setState((){ })` closure which triggers re-rendering of the Widget with the new state.

This results in displaying the contents of the `result` String in a `Text` widget that was returned by the remote `Hello` Service:

![](/img/pages/dart/flutter/helloflutter-01.png)


#### Authenticated Requests

This example shows how to make Authenticated Requests where first the `JsonServiceClient` instance is authenticated by sending a `Authenticate` request with valid Username/Password credentials which is validated against the servers configured [CredentialsAuthProvider](/auth/authentication-and-authorization#auth-providers). If successful this will return [Session Cookies](/auth/sessions) containing a reference to the Authenticated UserSession stored on the server. The Cookies are automatically saved on the `JsonServiceClient` instance and re-sent on subsequent requests which is how it's able to make an Authenticated request to the [protected `HelloAuth` Service](https://github.com/ServiceStack/Test/blob/3cc559d8de79e1c70ff7f4327458040ca055dea3/src/Test/Test.ServiceInterface/TestAuthService.cs#L18-L19):

```dart
RaisedButton(
  child: Text("Auth"),
  onPressed: () async {

    var auth = await testClient.post(Authenticate(
        provider: "credentials",
        userName: "test",
        password: "test"));

    var r = await testClient.get(HelloAuth(name: "Auth"));

    setState(() {
      result = "${r.result} your JWT is: ${auth.bearerToken}";
    });
  },
),
```

If the Username and Password were valid it will display the result of the `HelloAuth` Service along with the encapsulated JWT Token returned in the initial `AuthenticateResponse` call. 

![](/img/pages/dart/flutter/helloflutter-02.png)

JWT's encapsulate a signed, stateless Authenticated UserSession which is able to Authenticate with remote Services that have an `JwtAuthProvider` registered with the same AES or RSA Key used to sign the JWT Token. As they enable [Authentication with stateless Services they're ideal for use in Microservices](/auth/jwt-authprovider#stateless-auth-microservices).

#### JWT RefreshToken Requests

The JWT sample shows an example of authenticating via JWT, but instead of configuring the `JsonServiceClient` instance with the JWT BearerToken above (and what's needed to make JWT Authenticated Requests), it's only populating the [long-lived RefreshToken](/auth/jwt-authprovider#refresh-tokens) which the client automatically uses behind the scenes to fetch a JWT Bearer Token from the remote ServiceStack endpoint, which if the User is still allowed to Sign In will populate the instance with a new JWT Bearer Token encapsulated with the latest UserSession.

```dart
RaisedButton(
  child: Text("JWT"),
  onPressed: () async {
    var auth = await testClient.post(Authenticate(
        provider: "credentials",
        userName: "test",
        password: "test"));

    var newClient = JsonServiceClient(TestBaseUrl)
      ..refreshToken = auth.refreshToken;
    
    var r = await newClient.get(HelloAuth(name: "JWT"));

    setState(() {
      result = "${r.result} your RefreshToken is: ${auth.refreshToken}";
    });
  },
),
```

The RefreshToken is smaller than a JWT Bearer Token as it just contains a signed token with permission to fetch new JWT Tokens and not the actual UserSession contained in the JWT Bearer Token.

![](/img/pages/dart/flutter/helloflutter-03.png)

#### AutoQuery Requests

[AutoQuery](/autoquery/rdbms) lets us effortlessly creating queryable high-performance RDBMS APIs with just a Request DTO class definition, e.g:

```csharp
[Route("/technology/search")]
public class FindTechnologies : QueryDb<Technology>
{
    public string Name { get; set; }
    public string NameContains { get; set; }
}
```

ServiceStack takes care of creating the implementation for this Service from this definition which queries the `Technology` RDBMS table. 

Any properties added to the AutoQuery Request DTO will be generated in the Dart `FindTechnologies` Request DTO. However AutoQuery also lets you query any other property on the `Technology` table using any of the configured [Implicit Conventions](/autoquery/rdbms#implicit-conventions). 

We can include any additional arguments that are not explicitly defined on the Request DTO using the optional `args` parameter available in each `IServiceClient` API.

This examples calls 2 different AutoQuery Services, first to retrieve the **Flutter** `Technology` in https://techstacks.io to retrieve its `id` which it uses to query the latest `Announcement` or `Showcase` posted in the **Flutter** organization:

```dart
RaisedButton(
  child: Text("Query"),
  onPressed: () async {
    
    var techs = await techstacksClient.get(FindTechnologies(), args: {"slug": "flutter"});
    
    var posts = await techstacksClient.get(QueryPosts(
        anyTechnologyIds: [techs.results[0].id],
        types: ['Announcement', 'Showcase'])
      ..take = 1);

    setState(() {
      result = "Latest Flutter Announcement:\n“${posts.results[0].title}”";
    });
  },
),
```

The 2nd Request calls the `QueryPosts` AutoQuery Service highlighting the Service Client's support for [sending complex type arguments on the QueryString](/serialization-deserialization#passing-complex-objects-in-the-query-string) and an example of using Dart's method cascade operator to populate the `take` field in  the [inherited QueryBase class](/autoquery/rdbms#iquery).

![](/img/pages/dart/flutter/helloflutter-04.png)

#### Auto Batched Requests

The `sendAll` and `sendAllOneWay` APIs lets you use ServiceStack's [Auto Batched Requests](/auto-batched-requests) feature to batch multiple Requests DTOs of the same Type in a single Request that returns all Responses in a single Response, e.g:

```dart
RaisedButton(
  child: Text("Batch"),
  onPressed: () async {
    
    var requests = ['foo', 'bar', 'qux']
        .map((name) => Hello(name: name));
    
    var responses = await testClient.sendAll(requests);

    setState(() {
      result = "Batch Responses:\n${responses.map((r) => r.result).join('\n')}";
    });
  },
),
```

![](/img/pages/dart/flutter/helloflutter-05.png)

#### Generating Unknown Types

This is one area where we hit limitations of not being able to use Reflection in Dart which requires generating factories ahead-of-time for each type we need to create instances of at runtime. This is typically inferred by inspecting all Types referenced in each DTO, but as Auto Batched Requests lets you combine multiple requests for every Service, in the interest for reducing the amount of code-generation needed ServiceStack doesn't generate an explicit Service Contract for the Batched version of each API. 

Instead you'll need to specify missing types needed, the easiest solution to do this is to create a Dummy Service containing properties of any missing Types needed, in this case we need to generate a factory for the `List<HelloResponse>` used to return the batched `HelloResponse` DTOs in:

```csharp
public class UnknownTypes
{
    public List<HelloResponse> HelloResponses { get; set; }
}

public class UnknownTypesService : Service
{
    public object Any(UnknownTypes request) => request;
}
```

#### Binary Requests

Most API Requests typically involve sending a populated Request DTO that returns a Typed Response DTO although ServiceStack Services can also [return raw data](/service-return-types) like `String`, `byte[]` and `Stream` responses which the `JsonServiceClient` also seamlessly supports where instead of returning a Typed DTO it returns the raw HTTP Body as a `String` for Request DTOs implementing `IReturn<String>` or an `Uint8List` for any binary responses (e.g. Services implementing `IReturn<byte[]>` or `IReturn<Stream>`).

This example calls the [`HelloImage` Service](https://github.com/ServiceStack/Test/blob/90678a1d57ac63daaafea7322e0a4f542a93488f/src/Test/Test.ServiceInterface/ImageService.cs#L137) which dynamically creates and returns an image based on the different properties on the incoming `HelloImage` Request DTO. As it implements `IReturn<byte[]>` the `JsonServiceClient` returns the binary contents of the HTTP Response in a `Uint8List` - the preferred type for bytes in Dart.

```dart
RaisedButton(
  child: Text("Image"),
  onPressed: () async {

    Uint8List bytes = await testClient.get(HelloImage(
        name: "Flutter",
        fontFamily: "Roboto",
        background: "#0091EA",
        width: 500,
        height: 170));

    setState(() {
      result = "";
      imageBytes = bytes;
    });

  },
),

//...
result != null && result != "" 
    ? Text(result) 
    : Image.memory(imageBytes, width:500.0, height:170.0),
```

To display the image we assign the response to the `imageBytes` field within the stateful widget's `setState()` which triggers a re-render of the UI containing the generated Image displayed using the [Image widget](https://docs.flutter.io/flutter/widgets/Image-class.html):

![](/img/pages/dart/flutter/helloflutter-06.png)

### Angular Dart

The [HelloAngularDart](https://github.com/ServiceStackApps/HelloAngularDart) project demonstrates the same functionality in an AngularDart Web App running inside a Web Browser.

The only difference is having to import `web_client.dart` containing the `JsonWebClient`:

```dart
import 'package:servicestack/web_client.dart';
```

and changing the clients to use the `JsonWebClient` instead, e.g:

```dart
var testClient = JsonWebClient(TestBaseUrl);
var techstacksClient = JsonWebClient(TechStacksBaseUrl);
```

But otherwise the actual client source code for all of the Typed API requests remains exactly the same. 

The `HelloAngularDart` App is contained within the [hello_world](https://github.com/ServiceStackApps/HelloAngularDart/tree/master/lib/src/hello_world) component with all Dart logic in:

#### [hello_world.dart](https://github.com/ServiceStackApps/HelloAngularDart/blob/master/lib/src/hello_world/hello_world.dart)

```dart
import 'dart:typed_data';
import 'dart:convert';

import 'package:angular/angular.dart';
import 'package:servicestack/web_client.dart';

import '../dtos/test.dtos.dart';
import '../dtos/dtos.dart';

@Component(
  selector: 'hello-world',
  styleUrls: const ['hello_world.css'],
  templateUrl: 'hello_world.html',
)
class HelloWorldComponent {
  var result = "";
  var imageSrc = "data:image/gif;base64,R0lGODlhAQABAAAAACH5BAEKAAEALAAAAAABAAEAAAICTAEAOw=="; // 1x1 pixel
  static const TestBaseUrl = "https://test.servicestack.net";
  static const TechStacksBaseUrl = "https://techstacks.io";
  var testClient = JsonWebClient(TestBaseUrl);
  var techstacksClient = JsonWebClient(TechStacksBaseUrl);

  doAsync() async {
    var r = await testClient.get(Hello(name: "Async"));
    result = r.result;
  }

  doAuth() async {
    var auth = await testClient.post(Authenticate(
        provider: "credentials", userName: "test", password: "test"));
    var r = await testClient.get(HelloAuth(name: "Auth"));
    result = "${r.result} your JWT is: ${auth.bearerToken}";
  }

  doJWT() async {
    var auth = await testClient.post(Authenticate(
        provider: "credentials", userName: "test", password: "test"));

    var newClient = JsonWebClient(TestBaseUrl)
      ..refreshToken = auth.refreshToken;
    var r = await newClient.get(HelloAuth(name: "JWT"));
    result = "${r.result} your RefreshToken is: ${auth.refreshToken}";
  }

  doQuery() async {
    var techs = await techstacksClient
        .get(FindTechnologies(), args: {"slug": "flutter"});
    var posts = await techstacksClient.get(QueryPosts(
        anyTechnologyIds: [techs.results[0].id],
        types: ['Announcement', 'Showcase'])
      ..take = 1);
    result = "Latest Flutter Announcement:\n“${posts.results[0].title}”";
  }

  doBatch() async {
    var requests = ['foo', 'bar', 'qux'].map((name) => Hello(name: name));
    var responses = await testClient.sendAll(requests);
    result = "Batch Responses:\n${responses.map((r) => r.result).join('\n')}";
  }

  doImage() async {
    Uint8List bytes = await testClient.get(HelloImage(
        name: "Flutter",
        fontFamily: "Roboto",
        background: "#0091EA",
        width: 500,
        height: 170));

    result = "";
    imageSrc = "data:image/png;base64," + base64.encode(bytes);
  }
}
```

#### [hello_world.html](https://github.com/ServiceStackApps/HelloAngularDart/blob/master/lib/src/hello_world/hello_world.html)

Which uses this template markup to render its UI:

```html
<div>
    <button (click)="doAsync()">Async</button>
    <button (click)="doAuth()">Auth</button>
    <button (click)="doJWT()">JWT</button>
    <button (click)="doQuery()">Query</button>
    <button (click)="doBatch()">Batch</button>
    <button (click)="doImage()">Image</button>
</div>

<div id="result">{{result}}</div>

<img src="{{imageSrc}}">
```

Where it runs a functionally equivalent App in a browser:

![](/img/pages/dart/angulardart/helloangulardart-01.png)


## DTO Customization Options 

In most cases you'll just use the generated Dart DTOs as-is, however you can further customize how
the DTOs are generated by overriding the default options.

### Customize DTO Type generation

Additional Dart specific customization can be statically configured like `PreTypeFilter`, `InnerTypeFilter` & `PostTypeFilter` (available in all languages) can be used to inject custom code in the generated DTOs output. 

Use the `PreTypeFilter` to generate source code before and after a Type definition, e.g. this will append the `[Validate]` attribute on non enum & interface types:

```csharp
DartGenerator.PreTypeFilter = (sb, type) => {
    if (!type.IsEnum.GetValueOrDefault() && !type.IsInterface.GetValueOrDefault())
    {
        sb.AppendLine("@validate()");
    }
};
```

The `InnerTypeFilter` gets invoked just after the Type Definition which can be used to generate common members for all Types and interfaces, e.g:

```csharp
TypeScriptGenerator.InnerTypeFilter = (sb, type) => {
    sb.AppendLine("String id = '${Random().nextDouble()}'.substring(2);");
};
```

There's also `PrePropertyFilter` & `PostPropertyFilter` for generating source before and after properties, e.g:

```csharp
TypeScriptGenerator.PrePropertyFilter = (sb , prop, type) => {
    if (prop.Name == "Id")
    {
        sb.AppendLine("@PrimaryKey()");
    }
};
```

### Emit custom code

To enable greater flexibility when generating complex Typed DTOs, you can use `[Emit{Language}]` attributes to generate code before each type or property.

These attributes can be used to generate different attributes or annotations to enable client validation for different validation libraries in different languages, e.g:

```csharp
[EmitDart("@validate")]
[EmitCode(Lang.Dart | Lang.CSharp | Lang.Kotlin, "// App User")]
public class User : IReturn<User>
{
    [EmitDart("@isNotEmpty", "@isEmail")]
    [EmitCode(Lang.TypeScript | Lang.Kotlin, new[]{ "@IsNotEmpty()", "@IsEmail()" })]
    public string Email { get; set; }
}
```

Which will generate `[EmitDart]` code in Dart DTOs:

```dart
@validate
// App User
class User implements IReturn<User>, IConvertible
{
    @isNotEmpty
    @isEmail
    String email;

    User({this.email});
    User.fromJson(Map<String, dynamic> json) { fromMap(json); }

    fromMap(Map<String, dynamic> json) {
        email = json['email'];
        return this;
    }

    Map<String, dynamic> toJson() => {
        'email': email
    };

    createResponse() { return User(); }
    String getTypeName() { return "User"; }
    TypeContext context = _ctx;
}
```

Whilst the generic `[EmitCode]` attribute lets you emit the same code in multiple languages with the same syntax.

### Client Customization Options

The header in the generated DTOs show the different options Dart native types support with their 
defaults. Default values are shown with the comment prefix of `//`. To override a value, remove the `//` 
and specify the value to the right of the `:`. Any uncommented value will be sent to the server to override 
any server defaults.

The DTO comments allows for customizations for how DTOs are generated. The default options that were used 
to generate the DTOs are repeated in the header comments of the generated DTOs, options that are preceded 
by a Dart comment `//` are defaults from the server, any uncommented value will be sent to the server 
to override any server defaults.

```dart
/* Options:
Date: 2025-06-04 09:48:37
Version: 8.80
Tip: To override a DTO option, remove "//" prefix before updating
BaseUrl: https://blazor-vue.web-templates.io

//GlobalNamespace: 
//AddServiceStackTypes: True
//AddResponseStatus: False
//AddImplicitVersion: 
//AddDescriptionAsComments: True
//IncludeTypes: 
//ExcludeTypes: 
//DefaultImports: package:servicestack/servicestack.dart
*/
```

We'll go through and cover each of the above options to see how they affect the generated DTOs:

### Change Default Server Configuration

The above defaults are also overridable on the ServiceStack Server by modifying the default config on the 
`NativeTypesFeature` Plugin, e.g:

```csharp
//Server example in CSharp
var nativeTypes = this.GetPlugin<NativeTypesFeature>();
nativeTypes.MetadataTypesConfig.GlobalNamespace = "dtos";
...
```

We'll go through and cover each of the above options to see how they affect the generated DTOs:

### GlobalNamespace

Specify a library for the generated Dart DTOs:

```dart
library dtos;
```

### AddResponseStatus

Automatically add a `ResponseStatus` property on all Response DTOs, regardless if it wasn't already defined:

```dart
class  GetAnswers implements IReturn<GetAnswersResponse>
{
    ...
    ResponseStatus responseStatus;
}
```

### AddImplicitVersion

Lets you specify the Version number to be automatically populated in all Request DTOs sent from the client: 

```dart
class GetAnswers implements IReturn<GetAnswersResponse>
{
    int version = 1;
    ...
}
```

This lets you know what Version of the Service Contract that existing clients are using making it easy 
to implement ServiceStack's [recommended versioning strategy](http://stackoverflow.com/a/12413091/85785). 

### IncludeTypes

Is used as a Whitelist to specify only the types you would like to have code-generated:

```
/* Options:
IncludeTypes: GetTechnology,GetTechnologyResponse
```

Will only generate `GetTechnology` and `GetTechnologyResponse` DTOs:

```csharp
class class GetTechnology { ... }
class class GetTechnologyResponse { ... }
```

#### Include Request DTO and its dependent types

You can include a Request DTO and all its dependent types with a `.*` suffix on the Request DTO, e.g:

```
/* Options:
IncludeTypes: GetTechnology.*
```

Which will include the `GetTechnology` Request DTO, the `GetTechnologyResponse` Response DTO and all Types that they both reference.

#### Include All Types within a C# namespace

If your DTOs are grouped into different namespaces they can be all included using the `/*` suffix, e.g:

```
/* Options:
IncludeTypes: MyApp.ServiceModel.Admin/*
```

This will include all DTOs within the `MyApp.ServiceModel.Admin` C# namespace. 

#### Include All Services in a Tag Group

Services [grouped by Tag](/api-design#group-services-by-tag) can be used in the `IncludeTypes` where tags can be specified using braces in the format `{tag}` or `{tag1,tag2,tag3}`, e.g:

```
/* Options:
IncludeTypes: {web,mobile}
```

Or individually:

```
/* Options:
IncludeTypes: {web},{mobile}
```

### ExcludeTypes
Is used as a Blacklist to specify which types you would like excluded from being generated:

```
/* Options:
ExcludeTypes: GetTechnology,GetTechnologyResponse
```

Will exclude `GetTechnology` and `GetTechnologyResponse` DTOs from being generated.

### DefaultImports
Add additional import statements to the generated DTO's:

```
/* Options:
DefaultImports: package:servicestack/client.dart,package:flutter/material.dart
```

Will import the `servicestack/client.dart` and `flutter/material.dart` packages:

```swift
import 'package:servicestack/client.dart';
import 'package:flutter/material.dart';
```


# F# Add ServiceStack Reference
Source: https://docs.servicestack.net/fsharp-add-servicestack-reference

![F# Header](https://raw.githubusercontent.com/ServiceStack/Assets/master/img/wikis/fsharp-header.png)

ServiceStack's **Add ServiceStack Reference** feature allows clients to generate Native Types from directly within VS.NET using [ServiceStackVS VS.NET Extension](/create-your-first-webservice) - providing a simpler, cleaner and more versatile alternative to WCF's Add Service Reference feature that's built into VS.NET.

The article outlines ServiceStack's support generating F# DTO's - providing a flexible alternative than sharing your compiled DTO .NET assembly with clients. Now F# clients can easily add a reference to a remote ServiceStack instance and update typed DTO's directly from within VS.NET - reducing the burden and effort required to consume ServiceStack Services whilst benefiting from clients native language strong-typing feedback. 

## [Add ServiceStack Reference](/add-servicestack-reference)

The easiest way to Add a ServiceStack reference to your project is to right-click on your project to bring up [ServiceStackVS's](/create-your-first-webservice) `Add ServiceStack Reference` context-menu item. This opens a dialog where you can add the url of the ServiceStack instance you want to typed DTO's for, as well as the name of the DTO source file that's added to your project.

[![Add ServiceStack Reference](https://raw.githubusercontent.com/ServiceStack/Assets/master/img/apps/StackApis/add-service-ref-flow.png)](https://raw.githubusercontent.com/ServiceStack/Assets/master/img/apps/StackApis/add-service-ref-flow.png)

After clicking OK, the servers DTO's and [ServiceStack.Client](https://www.nuget.org/packages/ServiceStack.Client) NuGet package are added to the project, providing an instant typed API:

[![Calling ServiceStack Service with FSharp](https://raw.githubusercontent.com/ServiceStack/Assets/master/img/release-notes/fsharp-add-servicestack-reference.png)](https://raw.githubusercontent.com/ServiceStack/Assets/master/img/release-notes/fsharp-add-servicestack-reference.png)

### Update ServiceStack Reference

Updating a ServiceStack reference works intuitively where you just have to click on the DTO's you want to update and click **Update ServiceStack Reference** on the context menu:

[![Calling ServiceStack Service with FSharp](https://raw.githubusercontent.com/ServiceStack/Assets/master/img/release-notes/fsharp-update-servicestack-reference.png)](https://raw.githubusercontent.com/ServiceStack/Assets/master/img/release-notes/fsharp-update-servicestack-reference.png)

As there's no configuration stored about the ServiceStack Reference you might be wondering how this works? The **Update ServiceStack Reference** context menu only appears on F# source files ending with `.dto.fs` or `.dtos.fs`. It then uses the `BaseUrl` in the metadata comments for where to fetch and update to the latest F# server DTO's.

### Console Demo
![FSharp Console Demo](https://github.com/ServiceStack/Assets/raw/master/img/servicestackvs/servicestack%20reference/fsharp-demo.gif)

### F# Client Example

Just like with C#, F# Native Types can be used in ServiceStack's [Generic Service Clients](/csharp-client) providing and end-to-end Typed API whose PCL support also allows F# to be used in [mobile clients apps](https://github.com/ServiceStackApps/HelloMobile) without having to share compiled DTOs:

```fsharp
let client = new JsonApiClient("https://blazor-vue.web-templates.io")
let response = client.Get(new SearchQuestions(
    Tags = new List<string>([ "redis"; "ormlite" ])))        

Inspect.printDump(response)
```

### Change Default Server Configuration

The above defaults are also overridable on the ServiceStack Server by modifying the default config on the `NativeTypesFeature` Plugin, e.g:

```csharp
var typesConfig = this.GetPlugin<NativeTypesFeature>().MetadataTypesConfig;
typesConfig.AddDataContractAttributes = false;
...
```

## Constraints

As the ordering constraint in F# conflicted with the ordering of types by C# namespaces, the cleanest approach was to add all DTO's under a single namespace. By default the namespace used will be the base **ServiceModel** namespace which is overridable with the `GlobalNamespace` Config:

```csharp
typesConfig.GlobalNamespace = "Client.Namespace";
```

This does mean that each type name needs to be unique which is a best-practice that's now a requirement in order to make use of F# native types. Another semantic difference is that any C# nested classes become top-level classes when translated to F#.  

### FSharp Configuration

The header comments in the generated DTO's allows for further customization of how they're generated where ServiceStackVS automatically watches for any file changes and updates the generated DTO's with any custom Options provided. Options that are preceded by a F# single line comment `//` are defaults from the server that can be overridden, e.g:

```fsharp
(* Options:
Date: 2025-06-04 09:53:35
Version: 8.80
Tip: To override a DTO option, remove "//" prefix before updating
BaseUrl: https://blazor-vue.web-templates.io

//GlobalNamespace: 
//MakeDataContractsExtensible: False
//AddReturnMarker: True
//AddDescriptionAsComments: True
//AddDataContractAttributes: False
//AddIndexesToDataMembers: False
//AddGeneratedCodeAttributes: False
//AddResponseStatus: False
//AddImplicitVersion: 
//ExportValueTypes: False
//IncludeTypes: 
//ExcludeTypes: 
//InitializeCollections: False
//AddNamespaces: 
*)
```

To override a value, remove the `//` and specify the value to the right of the `:`. Any value uncommented will be sent to the server to override any server defaults.

We'll go through and cover each of the above options to see how they affect the generated DTO's:

### MakeDataContractsExtensible

Add .NET's DataContract's [ExtensionDataObject](http://msdn.microsoft.com/en-us/library/system.runtime.serialization.extensiondataobject(v=vs.110).aspx) to all DTO's:

```fsharp
[<AllowNullLiteral>]
type GetAnswersResponse() = 
    interface IExtensibleDataObject with
        member val ExtensionData:ExtensionDataObject = null with get, set
    end
    member val Ansnwer:Answer = null with get,set
    member val ExtensionData:ExtensionDataObject = null with get,set
```

### AddReturnMarker

AddReturnMarker annotates Request DTO's with an `IReturn<TResponse>` marker referencing the Response type ServiceStack infers your Service to return:

```fsharp
type GetAnswers() = 
    interface IReturn<GetAnswersResponse>
    member val QuestionId:Int32 = new Int32() with get,set
``` 

::: info 
Original DTO doesn't require a return marker as response type can be inferred from Services return type or when using the `%Response` DTO Naming convention
:::

### AddDescriptionAsComments

Converts any textual Description in `[Description]` attributes as F# Doc comments which allows your API to add intellisense in client projects:

```fsharp
///<summary>
///Get a list of Answers for a Question
///</summary>
type GetAnswers() = 
...
```

### AddDataContractAttributes

Decorates all DTO types with `[DataContract]` and properties with `[DataMember]`:

```fsharp
[<DataContract>]
[<AllowNullLiteral>]
type GetAnswers() = 
    interface IReturn<GetAnswersResponse>
    [<DataMember>]
    member val QuestionId:Int32 = new Int32() with get,set
```

### AddIndexesToDataMembers

Populates a DataMember Order index for all properties:

```fsharp
[<DataContract>]
type GetAnswers() = 
    interface IReturn<GetAnswersResponse>
    [<DataMember(Order=1)>]
    member val QuestionId:Int32 = new Int32() with get,set
```

> Requires AddDataContractAttributes=true

### AddGeneratedCodeAttributes

Emit `[<GeneratedCode>]` attribute on all generated Types:

```fsharp
[<GeneratedCode>]
type GetAnswers() = ...
```

### AddResponseStatus

Automatically add a `ResponseStatus` property on all Response DTO's, regardless if it wasn't already defined:

```fsharp
type GetAnswersResponse() = 
    ...
    member val ResponseStatus:ResponseStatus = null with get,set
```

### AddImplicitVersion

Lets you specify the Version number to be automatically populated in all Request DTO's sent from the client: 

```csharp
type GetAnswers() = 
    interface IReturn<GetAnswersResponse>
    member val Version:int = 1 with get, set
    ...
```

This lets you know what Version of the Service Contract that existing clients are using making it easy to implement ServiceStack's [recommended versioning strategy](http://stackoverflow.com/a/12413091/85785). 

### IncludeTypes
Is used as a Whitelist that can be used to specify only the types you would like to have code-generated:
```
/* Options:
IncludeTypes: GetTechnology,GetTechnologyResponse
```
Will only generate `GetTechnology` and `GetTechnologyResponse` DTO's, e.g:

```fsharp
type GetTechnology() = ...
type GetTechnologyResponse() = ...
```

#### Include Request DTO and its dependent types

You can include a Request DTO and all its dependent types with a `.*` suffix on the Request DTO, e.g:

```
/* Options:
IncludeTypes: GetTechnology.*
```

Which will include the `GetTechnology` Request DTO, the `GetTechnologyResponse` Response DTO and all Types that they both reference.

#### Include All Types within a C# namespace

If your DTOs are grouped into different namespaces they can be all included using the `/*` suffix, e.g:

```
/* Options:
IncludeTypes: MyApp.ServiceModel.Admin/*
```

This will include all DTOs within the `MyApp.ServiceModel.Admin` C# namespace. 

### ExcludeTypes
Is used as a Blacklist where you can specify which types you would like to exclude from being generated:
```
/* Options:
ExcludeTypes: GetTechnology,GetTechnologyResponse
```
Will exclude `GetTechnology` and `GetTechnologyResponse` DTO's from being generated.

### InitializeCollections

Lets you automatically initialize collections in Request DTO's:

```fsharp
type SearchQuestions() = 
    interface IReturn<SearchQuestionsResponse>
    member val Tags:List<String> = new List<String>() with get,set
```

### AddNamespaces

Include additional F# namespaces, e.g:

```
/* Options:
AddNamespaces: System.Drawing,MyApp
```

Where it will generate the specified namespaces in the generated Types:

```csharp
open System.Drawing
open MyApp
```


# VB.NET Add ServiceStack Reference
Source: https://docs.servicestack.net/vbnet-add-servicestack-reference

![VB.NET Header](https://raw.githubusercontent.com/ServiceStack/Assets/master/img/wikis/vb-header.png)

ServiceStack's **Add ServiceStack Reference** feature allows clients to generate Native Types from directly within VS.NET using [ServiceStackVS VS.NET Extension](/create-your-first-webservice) - providing a simpler, cleaner and more versatile alternative to WCF's Add Service Reference feature that's built into VS.NET.

The article outlines ServiceStack's support generating VB.Net DTO's - providing a flexible alternative than sharing your compiled DTO .NET assembly with clients. Now VB.Net clients can easily add a reference to a remote ServiceStack instance and update typed DTO's directly from within VS.NET - reducing the burden and effort required to consume ServiceStack Services whilst benefiting from clients native language strong-typing feedback. 

## [Add ServiceStack Reference](/add-servicestack-reference)

The easiest way to Add a ServiceStack reference to your project is to right-click on your project to bring up [ServiceStackVS's](/create-your-first-webservice) `Add ServiceStack Reference` context-menu item. This opens a dialog where you can add the url of the ServiceStack instance you want to typed DTO's for, as well as the name of the DTO source file that's added to your project.

[![Add ServiceStack Reference](https://raw.githubusercontent.com/ServiceStack/Assets/master/img/apps/StackApis/add-service-ref-flow.png)](https://raw.githubusercontent.com/ServiceStack/Assets/master/img/apps/StackApis/add-service-ref-flow.png)

After clicking OK, the servers DTO's and [ServiceStack.Client](https://www.nuget.org/packages/ServiceStack.Client) NuGet package are added to the project, providing an instant typed API:
![VB.Net Console client](https://github.com/ServiceStack/Assets/raw/master/img/apps/StackApis/call-service-vb.png)

With the VB.Net code generated on the Server, the role of [ServiceStackVS's](/create-your-first-webservice) **Add ServiceStack Reference** is there just to integrate the remote VB.Net DTO's into the clients VS.NET project. This is just getting the generated DTOs from the server with default options set by the server and adding them locally to your project within Visual Studio.

![Add VB.Net ServiceStack Reference Demo](https://github.com/ServiceStack/Assets/raw/master/img/servicestackvs/servicestack%20reference/addref-vbnet.gif)

## Update ServiceStack Reference

If your server has been updated and you want to update to client DTOs, simply right-click on the DTO file within VS.NET and select `Update ServiceStack Reference`. 

![VBNet update demo](https://github.com/ServiceStack/Assets/raw/master/img/servicestackvs/servicestack%20reference/updateref-vbnet.gif)

### Simple Usage Example

Async Example:

```vb
Dim client = new JsonApiClient("https://techstacks.io")

Dim response = Await client.SendAsync(New AppOverview())
response.PrintDump()
```

Sync Example:

```vb
Dim client = new JsonApiClient("https://techstacks.io")

Dim response = client.Send(New AppOverview())
response.PrintDump()
```

## DTO Customization Options 

The header comments in the generated DTO's allows for further customization of how they're generated where ServiceStackVS automatically watches for any file changes and updates the generated DTO's with any custom Options provided. Options that are preceded by a VB.Net Class comment `'''` are defaults from the server that can be overridden, e.g:

```vb
' Options:
'Date: 2025-06-04 09:53:47
'Version: 8.80
'Tip: To override a DTO option, remove "''" prefix before updating
'BaseUrl: https://blazor-vue.web-templates.io
'
'''GlobalNamespace: 
'''MakePartial: True
'''MakeVirtual: True
'''MakeDataContractsExtensible: False
'''AddReturnMarker: True
'''AddDescriptionAsComments: True
'''AddDataContractAttributes: False
'''AddIndexesToDataMembers: False
'''AddGeneratedCodeAttributes: False
'''AddResponseStatus: False
'''AddImplicitVersion: 
'''InitializeCollections: False
'''ExportValueTypes: False
'''IncludeTypes: 
'''ExcludeTypes: 
'''AddNamespaces: 
'''AddDefaultXmlNamespace: http://schemas.servicestack.net/types
```

To override these options on the client, the comment has to be changed to start with a single `'` instead of triple `'''`. This convention is due to VB.Net not having block quotes. For example, if we did't want our classes to be partial by default for the VB.Net client, our options would look like below.

```vb
' Options:
'Date: 2014-10-21 00:45:05
'Version: 1
'BaseUrl: https://blazor-vue.web-templates.io
'
'MakePartial: False
'''MakeVirtual: True
'''MakeDataContractsExtensible: False
'''AddReturnMarker: True
'''AddDescriptionAsComments: True
'''AddDataContractAttributes: False
'''AddIndexesToDataMembers: False
'''AddGeneratedCodeAttributes: False
'''AddResponseStatus: False
'''AddImplicitVersion: 
'''InitializeCollections: True
'''ExportValueTypes: False
'''IncludeTypes: 
'''ExcludeTypes: 
'''AddNamespaces: 
'''AddDefaultXmlNamespace: http://schemas.servicestack.net/types
```
Options that do not start with a `'''` are sent to the server to override any defaults set by the server.

### Change Default Server Configuration

The above defaults are also overridable on the ServiceStack Server by modifying the default config on the `NativeTypesFeature` Plugin, e.g:

```csharp
//Server example in CSharp
var nativeTypes = this.GetPlugin<NativeTypesFeature>();
nativeTypes.MetadataTypesConfig.MakeVirtual = false;
...
```

We'll go through and cover each of the above options to see how they affect the generated DTO's:

### MakePartial

Adds the `partial` modifier to all types, letting you extend generated DTO's with your own class separate from the generated types:

```vb
Public Partial Class GetAnswers
```

### MakeVirtual

Adds the `virtual` modifier to all properties:

```vb
Public Partial Class GetAnswers
    ...
    Public Overridable Property QuestionId As Integer
End Class
```

### MakeDataContractsExtensible

Add .NET's DataContract's [ExtensionDataObject](http://msdn.microsoft.com/en-us/library/system.runtime.serialization.extensiondataobject(v=vs.110).aspx) to all DTO's:

```vb
Public Partial Class Hello
            ...
    Implements IExtensibleDataObject
            ...
    Public Overridable Property ExtensionData As ExtensionDataObject Implements IExtensibleDataObject.ExtensionData
End Class
```

### AddReturnMarker

AddReturnMarker annotates Request DTO's with an `IReturn(Of T)` marker referencing the Response type ServiceStack infers your Service to return:

```vb
Public Partial Class GetAnswers
    Implements IReturn(Of GetAnswersResponse)
``` 

> Original DTO doesn't require a return marker as response type can be inferred from Services return type or when using the `%Response` DTO Naming convention

### AddDescriptionAsComments

Converts any textual Description in `<Description>` attributes as VB.Net class Doc comments which allows your API to add intellisense in client projects:

```vb
'''<Summary>
'''Get a list of Answers for a Question
'''</Summary>
Public Class GetAnswers
```

### AddDataContractAttributes

Decorates all DTO types with `<DataContract>` and properties with `<DataMember>` as well as adding default XML namespaces for all VB.Net namespaces used:

```vb
<Assembly: ContractNamespace("http://schemas.servicestack.net/types", ClrNamespace:="StackApis.ServiceModel.Types")>
<Assembly: ContractNamespace("http://schemas.servicestack.net/types", ClrNamespace:="StackApis.ServiceModel")>
...
<DataContract>
Partial Public Class GetAnswers
    Implements IReturn(Of GetAnswersResponse)
    <DataMember>
    Public Overridable Property QuestionId As Integer
End Class
```

### AddIndexesToDataMembers

Populates a DataMember Order index for all properties:

```vb
<DataContract>
Public Partial Class GetAnswers
    ...
    <DataMember(Order:=1)>
    Public Overridable Property QuestionId As Integer
End Class
```

> Requires **AddDataContractAttributes=true**

### AddGeneratedCodeAttributes

Emit `<GeneratedCode>` attribute on all generated Types:

```vb
<GeneratedCode>
Public Partial Class GetAnswers ...
```

### AddResponseStatus

Automatically add a `ResponseStatus` property on all Response DTO's, regardless if it wasn't already defined:

```vb
Public Partial Class GetAnswers
    ...
    Public Overridable Property ResponseStatus As ResponseStatus
End Class
```

### AddImplicitVersion

Lets you specify the Version number to be automatically populated in all Request DTO's sent from the client: 

```vb
Public Partial Class GetAnswers
    Public Overridable Property Version As Integer
    Public Sub New()
                Version = 1
    End Sub
    ...
End Class
```

This lets you know what Version of the Service Contract that existing clients are using making it easy to implement ServiceStack's [recommended versioning strategy](http://stackoverflow.com/a/12413091/85785). 

### InitializeCollections

Lets you automatically initialize collections in Request DTO's:

```vb
Public Partial Class SearchQuestions
    Public Sub New()
        Tags = New List(Of String)
    End Sub
    Public Overridable Property Tags As List(Of String)
    ...
}
```

### IncludeTypes
Is used as a Whitelist that can be used to specify only the types you would like to have code-generated:
```
/* Options:
IncludeTypes: GetTechnology,GetTechnologyResponse
```
Will only generate `GetTechnology` and `GetTechnologyResponse` DTO's, e.g:

```vb
Public Partial Class GetTechnology ...
Public Partial Class GetTechnologyResponse ...
```

#### Include Request DTO and its dependent types

You can include a Request DTO and all its dependent types with a `.*` suffix on the Request DTO, e.g:

```
/* Options:
IncludeTypes: GetTechnology.*
```

Which will include the `GetTechnology` Request DTO, the `GetTechnologyResponse` Response DTO and all Types that they both reference.

#### Include All Types within a C# namespace

If your DTOs are grouped into different namespaces they can be all included using the `/*` suffix, e.g:

```
/* Options:
IncludeTypes: MyApp.ServiceModel.Admin/*
```

This will include all DTOs within the `MyApp.ServiceModel.Admin` C# namespace. 

### ExcludeTypes
Is used as a Blacklist where you can specify which types you would like to exclude from being generated:
```
/* Options:
ExcludeTypes: GetTechnology,GetTechnologyResponse
```
Will exclude `GetTechnology` and `GetTechnologyResponse` DTO's from being generated.

### AddNamespaces

Include additional VB.NET namespaces, e.g:

```
' Options:
'AddNamespaces: System.Drawing,MyApp
```

Where it will generate the specified namespaces in the generated Types:

```csharp
Imports System.Drawing
Imports MyApp
```

### AddDefaultXmlNamespace

This lets you change the default DataContract XML namespace used for all namespaces:

```csharp
<Assembly: ContractNamespace("http://my.types.net", ClrNamespace:="StackApis.ServiceModel.Types")>
<Assembly: ContractNamespace("http://my.types.net", ClrNamespace:="StackApis.ServiceModel")>
```

> Requires AddDataContractAttributes=true


# ES3 Common.js Add ServiceStack Reference
Source: https://docs.servicestack.net/commonjs-add-servicestack-reference

In addition to [TypeScript](/typescript-add-servicestack-reference) support for generating typed Data Transfer Objects (DTOs), JavaScript is now supported.

Unlike TypeScript, JavaScript generated DTOs can be used directly from the browser, removing the need to keep your DTOs in sync with extra tooling by including a direct reference in your HTML Page:

```html
<script src="/types/js"></script>
```

To make typed API Requests from web pages, you need only include: 

  - **/js/require.js** - containing a simple `require()` to load **CommonJS** libraries
  - **/js/servicestack-client.js** - [built-in UMD @servicestack/client](/servicestack-client-umd) in **ServiceStack.dll**
  - **/types/js** - containing your APIs typed JS DTOs - all built-in ServiceStack

After which you'll have access to the generic `JsonServiceClient` with your APIs Typed Request DTOs, e.g:

```html
<script src="/js/require.js"></script>
<script src="/js/servicestack-client.js"></script>
<script src="/types/js"></script>

<script>
var { JsonServiceClient, Hello } = exports

var client = new JsonServiceClient()
client.api(new Hello({ name }))
    .then(api => console.log(api.response))
</script>    
```

Using **/types/js** has the same behavior as using `dtos.js` generated from `$ tsc dtos.ts` whose outputs are identical, i.e. both containing your API DTOs generated in CommonJS format. It's feasible to simulate the TypeScript compiler's output in this instance as ServiceStack only needs to generate DTO Types and Enums to enable its end-to-end API, and not any other of TypeScript's vast feature set.

### Enhanced Dev Time productivity with TypeScript

Even when no longer using TypeScript DTOs in your Apps, it's still useful to have TypeScript's `dtos.ts` included in your project (inc. Vanilla JS projects) to serve as optional type annotations enabling rich intelli-sense and static analysis in IDEs that support it, but as it's no longer used at runtime you're free to generate it at optimal times that don't interrupt your dev workflow.


## DTO Customization Options

In most cases you'll just use the generated JavaScript DTO's as-is, however you can further customize how
the DTOs are generated by overriding the default options.

The header in the generated DTOs show the different options JavaScript types support with their
defaults. Default values are shown with the comment prefix of `//`. To override a value, remove the `//`
and specify the value to the right of the `:`. Any uncommented value will be sent to the server to override
any server defaults.

The DTO comments allows for customizations for how DTOs are generated. The default options that were used
to generate the DTOs are repeated in the header comments of the generated DTOs, options that are preceded
by a TypeScript comment `//` are defaults from the server, any uncommented value will be sent to the server
to override any server defaults.

```js
/* Options:
Date: 2022-01-28 02:10:26
Version: 6.00
Tip: To override a DTO option, remove "//" prefix before updating
BaseUrl: https://vue-vite-api.jamstacks.net

//AddServiceStackTypes: True
//AddDescriptionAsComments: True
//IncludeTypes: 
//ExcludeTypes: 
//DefaultImports: 
*/
```

We'll go through and cover each of the above options to see how they affect the generated DTO's:

### Change Default Server Configuration

Above defaults are also overridable on the ServiceStack Server by modifying the default config on the `NativeTypesFeature` Plugin, e.g:

```csharp
//Server example in CSharp
var nativeTypes = this.GetPlugin<NativeTypesFeature>();
nativeTypes.MetadataTypesConfig.IgnoreTypesInNamespaces = "test";
...
```

We'll go through and cover each of the above options to see how they affect the generated DTO's:

### IncludeTypes

Is used as a Whitelist to specify only the types you would like to have code-generated:

```
/* Options:
IncludeTypes: Hello, HelloResponse
```

Will only generate `Hello` and `HelloResponse` DTOs:

```csharp
var HelloResponse = /** @class */ (function () {
    ...
}());
exports.HelloResponse = HelloResponse;
var Hello = /** @class */ (function () {
    ...
}());
exports.Hello = Hello;
```

#### Include Generic Types

Use .NET's Type Name to include Generic Types, i.e. the Type name separated by the backtick followed by the number of generic arguments, e.g:

```
IncludeTypes: IReturn`1,MyPair`2
```

#### Include Request DTO and its dependent types

You can include a Request DTO and all its dependent types with a `.*` suffix on the Request DTO, e.g:

```
/* Options:
IncludeTypes: GetTechnology.*
```

Which will include the `GetTechnology` Request DTO, the `GetTechnologyResponse` Response DTO and all Types that they both reference.

#### Include All Types within a C# namespace

If your DTOs are grouped into different namespaces they can be all included using the `/*` suffix, e.g:

```
/* Options:
IncludeTypes: MyApp.ServiceModel.Admin/*
```

This will include all DTOs within the `MyApp.ServiceModel.Admin` C# namespace.

#### Include All Services in a Tag Group

Services [grouped by Tag](/api-design#group-services-by-tag) can be used in the `IncludeTypes` where tags can be specified using braces in the format `{tag}` or `{tag1,tag2,tag3}`, e.g:

```
/* Options:
IncludeTypes: {web,mobile}
```

Or individually:

```
/* Options:
IncludeTypes: {web},{mobile}
```

### ExcludeTypes
Is used as a Blacklist to specify which types you would like excluded from being generated:

```
/* Options:
ExcludeTypes: GetTechnology,GetTechnologyResponse
```

Will exclude `GetTechnology` and `GetTechnologyResponse` DTOs from being generated.

### Cache

When using `/types/js` directly from a `script` tag, the server will cache the result by default when not running in `HostContext.DebugMode`.

This caching process can be disabled if required by using `?cache=false`.


# Server Events
Source: https://docs.servicestack.net/server-events

![](/img/pages/server-events/server-events-banner.png)

[Server Sent Events](http://www.html5rocks.com/en/tutorials/eventsource/basics/) (SSE) is an elegant [web technology](http://dev.w3.org/html5/eventsource/) for efficiently receiving push notifications from any HTTP Server. It can be thought of as a mix between long polling and one-way WebSockets and contains many benefits over each:

  - **Simple** - Server Sent Events is just a single long-lived HTTP Request that any HTTP Server can support
  - **Efficient** - Each client uses a single TCP connection and each message avoids the overhead of HTTP Connections and Headers that's [often faster than Web Sockets](http://matthiasnehlsen.com/blog/2013/05/01/server-sent-events-vs-websockets/).
  - **Resilient** - Browsers automatically detect when a connection is broken and automatically reconnects
  - **Interoperable** - As it's just plain-old HTTP, it's introspectable with your favorite HTTP Tools and even works through HTTP proxies (with buffering and [chunked-encoding turned off](https://www.w3.org/TR/eventsource/#notes)).
  - **Well Supported** - As a Web Standard it's supported in all major browsers except for IE which [can be enabled with polyfills](http://html5doctor.com/server-sent-events/#yaffle) - see [default_ieshim.cshtml](https://github.com/ServiceStackApps/Chat/blob/master/src/Chat/default_ieshim.cshtml) and its [Live Chat Example](http://chat.netcore.io/default_ieshim).

We've chosen to adopt Server Sent Events for Server Notifications as it's a beautifully simple and elegant [Web Standard](http://dev.w3.org/html5/eventsource/) with better HTTP fidelity than **WebSockets**, that's perfect fit for Server Push Communications that works in both ServiceStack' ASP.NET, SelfHosts and .NET Core without requiring any extra .NET dependencies or [require the host Windows Server have WebSockets support](http://stackoverflow.com/a/12073593/85785) to use. 

Our integrated and high-performance solution enhances this simple lightweight protocol with rich pub/sub features allowing for [flexible and targeted messaging](/server-events#sending-server-events)
and intelligent clients enabling a variety of different strategies for easily handling events, includes built-in APIs for easily modifying active subscriptions and querying the state of subscribed channels as well as built-in heartbeats and auto-retries for establishing hassle-free persistent connections to backend servers.

### Server Event Clients

Our native Server Event clients covers the most popular Mobile, Desktop and Server platforms with new first-class implementations for Android, Java and TypeScript which now includes:

 - [C# Server Events Client](/csharp-server-events-client)
    - Xamarin.iOS
    - Xamarin.Android
    - UWP
    - .NET Framework 4.5+
    - .NET Core (.NET Standard 1.3+)
- [TypeScript Server Events Client](/typescript-server-events-client)
    - Web
    - Node.js Server
    - React Native
        - iOS
        - Android
- [Java Server Events Client](/java-server-events-client)
    - Android
    - JVM 1.7+ (Java, Kotlin, Scala, etc)
        - Java Clients
        - Java Servers
- [JavaScript (jQuery plugin)](/javascript-server-events-client)
    - Web

### gRPC Server Events Clients

In addition to the smart generic HTTP Server Events Clients above, Server Events is also available via a [gRPC Server Streaming Endpoint](/server-events-grpc)
which opens ServiceStack Server Events open to gRPC's ecosystem of typed generated client proxies, including:

 - [gRPC Flutter](/grpc/flutter)
 - [gRPC Android](/grpc/android)
 - [gRPC C#](/grpc/csharp)
 - [gRPC Swift](/grpc/swift)
 - [gRPC Java](/grpc/java)
 - [gRPC Dart](/grpc/dart)
 - [gRPC GO](/grpc/go)
 - [gRPC Node.js](/grpc/nodejs)
 - [gRPC Python](/grpc/python)
 - [gRPC Ruby](/grpc/ruby)
 - [gRPC PHP](/grpc/php)
 
Our C#, TypeScript and Java Server Event Clients are ports with full feature parity as C#, offering the same functionality behind idiomatic APIs for their respective programming language. The Integration test suite has also been ported to each platform to assert behavior conformance and provides a good reference showcasing the aesthetics of using Server Events Clients in each language:

 - [C# Server Events Integration Tests](https://github.com/ServiceStack/ServiceStack/blob/master/tests/ServiceStack.WebHost.Endpoints.Tests/ServerEventTests.cs)
 - [TypeScript  Server Events Integration Tests](https://github.com/ServiceStack/servicestack-client/blob/master/tests/serverevents.spec.ts)
 - [Java 8 / JVM Server Events Integration Tests](https://github.com/ServiceStack/ServiceStack.Java/blob/master/src/AndroidClient/client/src/test/java/net/servicestack/client/ServerEventClientTests.java)
 - [Java 7 / Android Server Events Integration Tests](https://github.com/ServiceStack/ServiceStack.Java/blob/master/src/AndroidClient/android/src/androidTest/java/net/servicestack/android/ServerEventClientTests.java)

### Server Event Providers

There are 2 Server Implementations of Server Events available, the default In Memory provider enables sending
real-time communications to all clients subscribed to the same ServiceStack Instance whilst Redis Server Events utilizes a distributed redis-server back-end to provide a scale-out option capable of serving across multiple fan-out/load-balanced App Servers:

  - Memory Server Events (default)
  - [Redis Server Events](/redis-server-events)

## Registering

Like most other [modular functionality](/plugins) in ServiceStack, Server Sent Events is encapsulated in a single Plugin that can be registered in your AppHost with:

```csharp
Plugins.Add(new ServerEventsFeature());
```

The registration above is all that's needed for most use-cases which just uses the defaults below:

```csharp
class ServerEventsFeature
{
    StreamPath = "/event-stream";            // The entry-point for Server Sent Events
    HeartbeatPath = "/event-heartbeat";      // Where to send heartbeat pulses
    UnRegisterPath = "/event-unregister";    // Where to unregister your subscription
    SubscribersPath = "/event-subscribers";  // View public info of channel subscribers 

    // Return `401 Unauthorized` to non-authenticated clients
    LimitToAuthenticatedUsers = false;

    // How long to wait for heartbeat before unsubscribing
    IdleTimeout = TimeSpan.FromSeconds(30);  

    // Client Interval for sending heartbeat messages
    HeartbeatInterval = TimeSpan.FromSeconds(10);

    // Send notifications when subscribers join/leave
    NotifyChannelOfSubscriptions = true;
}
```

::: info
The paths lets you customize the routes for the built-in Server Events API's, whilst setting a path to `null` disables that feature
:::

### Custom Event Hooks

A number of hooks are available providing entry points where custom logic can be added to modify or enhance existing behavior:

```csharp
class ServerEventsFeature
{
    Action<IRequest> OnInit;                          // Subscription pre-initialization callback
     //Filter OnConnect messages
    Action<IEventSubscription, Dictionary<string, string>> OnConnect;

    // Events fired when 
    Action<IEventSubscription, IRequest> OnCreated;   // Subscription is created
    Func<IEventSubscription, Task> OnSubscribeAsync;  // Subscription is registered 
    Func<IEventSubscription,Task> OnUnsubscribeAsync; // Subscription is unregistered
    Func<IEventSubscription, Task> OnUpdateAsync;     // Subscription is updated

    // Fired when message is published
    Action<IEventSubscription, IResponse, string> OnPublish; 
    Func<IEventSubscription, IResponse, string, Task> OnPublishAsync; 
}
```

## Sending Server Events

The way your Services send notifications is via the `IServerEvents` API which defaults to an in-memory `MemoryServerEvents` implementation which keeps a record of all subscriptions and connections in memory:

::: info
Server Events can be configured to use a [distributed Redis backend](/redis-server-events) allowing it to work across load-balanced app servers
:::

```csharp
public interface IServerEvents : IDisposable
{
    // External API's
    Task NotifyAllAsync(string sel, object msg, CancellationToken ct=default);
    Task NotifyChannelAsync(string chan, string sel, object msg, CancellationToken ct=default);
    Task NotifySubscriptionAsync(string subId, string sel, object msg,string chan,CancellationToken ct=default)
    Task NotifyUserIdAsync(string userId, string sel, object msg, string chan, CancellationToken ct=default)
    Task NotifyUserNameAsync(string userName, string sel, object msg, string chan,CancellationToken ct=default)
    Task NotifySessionAsync(string sessionId, string sel, object msg, string chan,CancellationToken ct=default)

    // Sync APIs
    void NotifyAll(string selector, object message);
    void NotifyChannel(string channel, string selector, object message);
    void NotifySubscription(string subscriptionId, string selector, object message, string channel = null);
    void NotifyUserId(string userId, string selector, object message, string channel = null);
    void NotifyUserName(string userName, string selector, object message, string channel = null);
    void NotifySession(string sessionId, string selector, object message, string channel = null);

    SubscriptionInfo GetSubscriptionInfo(string id);
    List<SubscriptionInfo> GetSubscriptionInfosByUserId(string userId);

    // Raw JSON APIs
    Task NotifyAllJsonAsync(string selector, string json, CancellationToken ct=default)
    Task NotifyChannelJsonAsync(string channel, string selector, string json, CancellationToken ct=default)
    Task NotifySubscriptionJsonAsync(string subscriptionId, string selector, string json, string chan)
    Task NotifyUserIdJsonAsync(string userId, string selector, string json, string chan)
    Task NotifyUserNameJsonAsync(string userName, string selector, string json, string chan)
    Task NotifySessionJsonAsync(string sessionId, string selector, string json, string chan)

    // Admin API's
    Task RegisterAsync(IEventSubscription subscription, Dictionary<string,string> conArgs,CancellationToken ct)
    Task UnRegisterAsync(string subscriptionId, CancellationToken token=default);

    long GetNextSequence(string sequenceId);

    Task<int> RemoveExpiredSubscriptionsAsync(CancellationToken token = default);

    Task SubscribeToChannelsAsync(string subscriptionId, string[] channels, CancellationToken ct);
    Task UnsubscribeFromChannelsAsync(string subscriptionId, string[] channels, CancellationToken ct);

    List<SubscriptionInfo> GetAllSubscriptionInfos();

    // Client API's
    List<Dictionary<string, string>> GetSubscriptionsDetails(params string[] channels);
    List<Dictionary<string, string>> GetAllSubscriptionsDetails();
    Task<bool> PulseAsync(string subscriptionId, CancellationToken ct=default);

    // Clear all Registrations
    void Reset();
    void Start();
    void Stop();
}
```

We recommend using the non-blocking `*Async` APIs when possible, especially in .NET Core Apps or high load environments.

The API's your Services predominantly deal with are the **External API's** which allow sending of messages at different levels of granularity. As Server Events have deep integration with ServiceStack's [Sessions](/auth/sessions) and [Authentication Providers](/auth/authentication-and-authorization) you're also able to notify specific users by either:

```csharp
NotifyUserIdAsync()   // UserAuthId
NotifyUserNameAsync() // UserName
NotifySessionAsync()  // Session Id
```

Whilst these all provide different ways to send a message to a single authenticated user, any user can be connected to multiple subscriptions at any one time (e.g. by having multiple tabs open). Each one of these subscriptions is uniquely identified by a `subscriptionId` which you can send a message with using: 

```csharp
NotifySubscriptionAsync() // Unique Subscription Id
```

There are also API's to retrieve a users single event subscription as well as all subscriptions for a user:

```csharp
SubscriptionInfo GetSubscriptionInfo(string id);

List<SubscriptionInfo> GetSubscriptionInfosByUserId(string userId);
```

## Event Subscription

An Event Subscription allows you to inspect different metadata contained on each subscription as well as being able to `Publish()` messages directly to it, manually send a Heartbeat `Pulse()` (to keep the connection active) as well as `Unsubscribe()` to revoke the subscription and terminate the HTTP Connection.

```csharp
public interface IEventSubscription : IMeta, IDisposable
{
    DateTime CreatedAt { get; set; }
    DateTime LastPulseAt { get; set; }
    long LastMessageId { get; }

    string[] Channels { get; }
    string UserId { get; }
    string UserName { get; }
    string DisplayName { get; }
    string SessionId { get; }
    string SubscriptionId { get; }
    string UserAddress { get; set; }
    bool IsAuthenticated { get; set; }
    bool IsClosed { get; }

    void UpdateChannels(string[] channels);

    Func<IEventSubscription, Task> OnUnsubscribeAsync { get; set; }
    Action<IEventSubscription> OnUnsubscribe { get; set; }
    Task UnsubscribeAsync();

    void Publish(string selector, string message);
    Task PublishAsync(string selector, string message, CancellationToken token=default);
    void PublishRaw(string frame);
    Task PublishRawAsync(string frame, CancellationToken token=default);
    void Pulse();

    Dictionary<string,string> ServerArgs { get; set; }
    Dictionary<string,string> ConnectArgs { get; set; }
}
```

The `IServerEvents` API also offers an API to UnRegister a subscription with:

```csharp
void UnRegister(IEventSubscription subscription);
```

### Event Subscription Metadata

The `ServerArgs` string Dictionary on `IEventSubscription` and `SubscriptionInfo` is for storing metadata on a SSE subscription that you only want visible on the Server (e.g. Service implementations), `ConnectArgs` is for info you want the subscribed client to have access to from its `OnConnect` event whilst the `Meta` dictionary is for public info you'd like other channel subscribers to have access to from their `OnJoin`, `OnLeave` and `OnUpdate` on subscriber events. 
 
Here's an example of using the server `OnCreated` callback to populate all 3 Dictionaries:
 
```csharp
new ServerEventsFeature {
    OnCreated = (sub,req) => {
        var session = req.GetSession();
        if (!session.IsAuthenticated) return;
        sub.Meta["Nickname"] = session.Nickname;           // channel subscribers
        sub.ConnectArgs["Email"] = session.Email;          // client subscriber 
        sub.ServerArgs["PostalCode"] = session.PostalCode; // server
    }
}
```

## Channels

Standard Publish / Subscribe patterns include the concept of a **Channel** upon which to subscribe and publish messages to. The channel in Server Events can be any arbitrary string which is declared on the fly when it's first used. 

::: info Tip
As Request DTO names are unique in ServiceStack they can make for good channel names which benefit from providing a typed API for free, e.g: `nameof(Request)`
:::

The API to send a message to a specific channel is:

```csharp
void NotifyChannel(string channel, string selector, object message);
```

Which just includes the name of the `channel`, the `selector` you wish the message applies to and the `message` to send which can be any JSON serializable object.

Along with being able to send a message to everyone on a channel, each API also offers an optional `channel` filter which when supplied will limit messages only to that channel:

```csharp
void NotifyUserId(string userId, string selector, object message, string channel = null);
```

## Order of Events

The following Server and Client callbacks are fired when a client first makes a Server Events Connection:

 1. `ServerEventsFeature.OnInit()` - Fired when the server receives the initial HTTP connection. This callback can be used to customize any HTTP Headers that are sent back to the client
 2. `ServerEventsFeature.OnCreated()` - Fired when the server `IEventSubscription` is created but before it becomes Connected.
 3. `ServerEventsFeature.OnConnect()` - Fired when the `IEventSubscription` is about to be connected. This callback can be used to modify the connection info arguments the client receives
 4. **(Client)**  - The Client is then sent an `cmd.onConnect` message with the connection info arguments about the connection. 
 5. `ServerEventsFeature.OnSubscribe()` - Fired after the subscription is registered. This callback can be used to send any custom messages to the client
 6. `ServerEventsFeature.OnUpdateAsync()` - Fired after the subscription is updated (e.g. subscribed Channels are updated)
 7. **(Client)** - If `ServerEventsFeature.NotifyChannelOfSubscriptions = true` every client in the same channel receives a `cmd.onJoin` message to notify them that a new subscription has joined the channel as well as a `cmd.onLeave` message when subscription leaves the channel

::: info
The `cmd.onConnect`, `cmd.onJoin` and `cmd.onLeave` messages can be handled with the [Global Event Handlers](/javascript-server-events-client#global-event-handlers) on the JavaScript Client and the [Message Event Handlers](/csharp-server-events-client#message-event-handlers) or the [Global Receiver](/csharp-server-events-client#the-global-receiver) .NET ServerEventClient
:::

### Heartbeats

Periodically whilst the client maintains a ServerEvents subscription with the server it will send periodic Heartbeats to the Server. This will fire the `ServerEventsFeature.OnHeartbeatInit()` server event which if the client is still connected will be sent a `cmd.onHeartbeat` message. If the subscription no longer exists, heartbeats will return a `404 - Subscription {id} does not exist` HTTP Response.

## Chat Features

The implementation of Chat is a great way to explore different Server Event features which make it easy to develop highly interactive and responsive web apps with very little effort. 

### Active Subscribers

One feature common to chat clients is to get details of all the active subscribers in a channel which we can get from the built-in `/event-subscribers` route, e.g:

```javascript
$.getJSON(`/event-subscribers?channel=${channel}`, function (users) {
    $.map(users, function(user) {
        usersMap[user.userId] = user;
        refCounter[user.userId] = (refCounter[user.userId] || 0) + 1;
    });
    var html = $.map(usersMap, function(user) { return createUser(user); }).join('');
    $("#users").html(html);
});
```

As a single user can have multiple subscriptions (e.g. multiple tabs open) users are merged into a single `usersMap` so each user is only listed once in the users list and a `refCounter` is maintained with the number of subscriptions each user has, so we're able to tell when the user has no more active subscriptions and can remove them from the list.

### Chat box

Chat's text box provides a free-text entry input to try out different Server Event features where each text message is posted to a ServiceStack Service which uses the `IServerEvents` API to send notifications the channels subscribers. When a server event is received on the client, the ss-utils.js client bindings routes the message to the appropriate handler. As all messages go through this same process, the moment the log entry appears in your chat window is also when it appears for everyone else (i.e instant when running localhost).

Normal chat messages (i.e. that don't specify a selector) uses the default `cmd.chat` selector which is sent to the `chat` handler that just echoes the entry into the chat log with:

```javascript
chat: function (m, e) {
    addEntry({ id: m.id, userId: m.fromUserId, userName: m.fromName, msg: m.message, 
               cls: m.private ? ' private' : '' });
}

```

### Specifying a selector

You can specify to use an alternative selector by prefixing the message with a `/{selector}`, e.g: 

```
/cmd.announce This is your captain speaking ...
```

When a selector is specified in Chat it routes the message to the `/channels/{Channel}/raw` Service which passes the raw message through as a string. Normal Chat entries are instead posted to the `/channels/{Channel}/chat` Service, adding additional metadata to the chat message with the user id and name of the sender so it can be displayed in the chat log. The Javascript code that calls both Services is simply: 

```javascript
if (msg[0] == "/") {
    parts = $.ss.splitOnFirst(msg, " ");
    $.post(`/channels/${channel}/raw`, 
        { from: activeSub.id, toUserId: to, message: parts[1], selector: parts[0].substring(1) });
} else {
    $.post(`/channels/${channel}/chat`, 
        { from: activeSub.id, toUserId: to, message: msg, selector: "cmd.chat" });
}
```

### Sending a message to a specific user

Another special syntax supported in Chat is the ability to send messages to other users by prefixing it with `@` followed by the username, e.g:

```
@mythz this is a private message
@mythz /tv.watch http://youtu.be/518XP8prwZo
```

There's also a special `@me` alias to send a message to yourself, e.g:

```
@me /tv.watch http://youtu.be/518XP8prwZo
```

## Server Event Services

By default ServiceStack doesn't expose any Services that can send notifications to other users by default.  It's left up to your application as to what functionality and level of granularity should be enabled for your Application. Your Services can send notifications via the `IServerEvents` provider.

Below is the annotated implementation for both Web Services used by Chat. The `PostRawToChannel` is a simple implementation that just relays the message sent to all users in the channel or just a specific user if `ToUserId` parameter is specified.

The `PostChatToChannel` Service is used for sending Chat messages which sends a wrapped `ChatMessage` DTO instead that holds additional metadata about the message that the Chat UI requires:

```csharp
[Route("/channels/{Channel}/chat")]
public class PostChatToChannel : IReturn<ChatMessage>
{
    public string From { get; set; }
    public string ToUserId { get; set; }
    public string Channel { get; set; }
    public string Message { get; set; }
    public string Selector { get; set; }
}

[Route("/channels/{Channel}/raw")]
public class PostRawToChannel : IReturnVoid
{
    public string From { get; set; }
    public string ToUserId { get; set; }
    public string Channel { get; set; }
    public string Message { get; set; }
    public string Selector { get; set; }
}

public class ServerEventsServices : Service
{
    public IServerEvents ServerEvents { get; set; }
    public IChatHistory ChatHistory { get; set; }
    public IAppSettings AppSettings { get; set; }

    public void Any(PostRawToChannel request)
    {
        if (!IsAuthenticated && AppSettings.Get("LimitRemoteControlToAuthenticatedUsers", false))
            throw new HttpError(HttpStatusCode.Forbidden, "You must be authenticated to use remote control.");

        // Ensure the subscription sending this notification is still active
        var sub = ServerEvents.GetSubscriptionInfo(request.From);
        if (sub == null)
            throw HttpError.NotFound($"Subscription {request.From} does not exist");

        // Check to see if this is a private message to a specific user
        if (request.ToUserId != null)
        {
            // Only notify that specific user
            ServerEvents.NotifyUserId(request.ToUserId, request.Selector, request.Message);
        }
        else
        {
            // Notify everyone in the channel for public messages
            ServerEvents.NotifyChannel(request.Channel, request.Selector, request.Message);
        }
    }

    public object Any(PostChatToChannel request)
    {
        // Ensure the subscription sending this notification is still active
        var sub = ServerEvents.GetSubscriptionInfo(request.From);
        if (sub == null)
            throw HttpError.NotFound($"Subscription {request.From} does not exist");

        var channel = request.Channel;

        // Create a DTO ChatMessage to hold all required info about this message
        var msg = new ChatMessage
        {
            Id = ChatHistory.GetNextMessageId(channel),
            FromUserId = sub.UserId,
            FromName = sub.DisplayName,
            Message = request.Message,
        };

        // Check to see if this is a private message to a specific user
        if (request.ToUserId != null)
        {
            // Mark the message as private so it can be displayed differently in Chat
            msg.Private = true;
            // Send the message to the specific user Id
            ServerEvents.NotifyUserId(request.ToUserId, request.Selector, msg);

            // Also provide UI feedback to the user sending the private message so they
            // can see what was sent. Relay it to all senders active subscriptions 
            var toSubs = ServerEvents.GetSubscriptionInfosByUserId(request.ToUserId);
            foreach (var toSub in toSubs)
            {
                // Change the message format to contain who the private message was sent to
                msg.Message = $"@{toSub.DisplayName}: {msg.Message}";
                ServerEvents.NotifySubscription(request.From, request.Selector, msg);
            }
        }
        else
        {
            // Notify everyone in the channel for public messages
            ServerEvents.NotifyChannel(request.Channel, request.Selector, msg);
        }

        if (!msg.Private)
            ChatHistory.Log(channel, msg);

        return msg;
    }
}
```

## Updating Channels on Live Subscriptions

You can update a live Server Events connection with Channels you want to Join or Leave using the 
built-in ServerEvents `UpdateEventSubscriber` Service:

```csharp
[Route("/event-subscribers/{Id}", "POST")]
public class UpdateEventSubscriber : IReturn<UpdateEventSubscriberResponse>
{
    public string Id { get; set; }
    public string[] SubscribeChannels { get; set; }
    public string[] UnsubscribeChannels { get; set; }
}
```

This lets you modify your active subscription with channels you want to join or leave with a HTTP POST Request, e.g:

```
POST /event-subscribers/{subId}
SubscribeChannels=chan1,chan2&UnsubscribeChannels=chan3,chan4
```

### onUpdate Notification

As this modifies the active subscription it also publishes a new **onUpdate** notification to all channel 
subscribers so they're able to maintain up-to-date info on each subscriber. 

In C# `ServerEventsClient` this can be handled together with **onJoin** and **onLeave** events using `OnCommand`:

```csharp
client.OnCommand = msg => ...; //= ServerEventJoin, ServerEventLeave or ServerEventUpdate
```

In the ss-utils JavaScript Client this can be handled with a Global Event Handler, e.g:

```javascript
$(source).handleServerEvents({
    handlers: {
        onConnect: connectedUserInfo => { ... },
        onJoin: userInfo => { ... },
        onLeave: userInfo => { ... },
        onUpdate: userInfo => { ... }
    }
});
```

### ServerEvents Update Channel APIs

Whilst internally, from within ServiceStack you can update a channel's subscription using the
[IServerEvents](https://github.com/ServiceStack/ServiceStack/blob/b9a33c34d0b0eedbcc6b3483257f1dc37bbf713f/src/ServiceStack/ServerEventsFeature.cs#L1004) APIs:

```csharp
public interface IServerEvents 
{
    ...
    void SubscribeToChannels(string subscriptionId, string[] channels);
    void UnsubscribeFromChannels(string subscriptionId, string[] channels);
}
```

## Troubleshooting

### Response Buffering delaying events

If your web server is configured to automatically buffer the response it will delay when the [Server Events get sent to the client](http://stackoverflow.com/a/25983774/85785). In IIS Express you can disable buffering by disabling compression for dynamic requests by adding this to your **Web.config**:

```xml
<system.webServer>
   <urlCompression doStaticCompression="true" doDynamicCompression="false" />
</system.webServer>
```

Alternatively you can switch to use Visual Studio Development Server which doesn't buffer by default.

## ServerEvents Examples

### [Android Java Chat](https://github.com/ServiceStackApps/AndroidJavaChat)

Java Chat client utilizing [Server Events](/java-server-events-client) for real-time notifications and enabling seamless OAuth Sign In's using Facebook, Twitter and Google's native SDKs:

[![](/img/pages/java/java-android-chat-screenshot-540x960.png)](https://github.com/ServiceStackApps/AndroidJavaChat)

### [Web, Node.js and React Native ServerEvents Apps](https://github.com/ServiceStackApps/typescript-server-events)

Using TypeScript ServerEvents Client to create real-time Web, node.js server and React Native Mobile Apps:

[![](https://raw.githubusercontent.com/ServiceStack/Assets/master/img/livedemos/typescript-serverevents/typescript-server-events-banner.png)](https://github.com/ServiceStackApps/typescript-server-events)

### [Gistlyn](https://github.com/ServiceStack/Gistlyn)

Gistlyn is a C# Gist IDE for creating, running and sharing stand-alone, executable C# snippets.

[![](https://raw.githubusercontent.com/ServiceStack/Assets/master/img/livedemos/gistlyn/home-screenshot.png)](http://gistlyn.com)

### [React Chat](https://github.com/ServiceStackApps/ReactChat)

React Chat is a port of [ServiceStack Chat](https://github.com/ServiceStackApps/Chat) ES5, jQuery Server Events 
demo into a [TypeScript](http://www.typescriptlang.org/), [React](http://facebook.github.io/react/) and 
[Redux](https://github.com/reactjs/redux) App:

![](https://raw.githubusercontent.com/ServiceStack/Assets/master/img/livedemos/chat-react/screenshot.png)

### [Xamarin.Android Chat](https://github.com/ServiceStackApps/AndroidXamarinChat)

Xamarin.Android Chat utilizes the 
[.NET PCL Server Events Client](/csharp-server-events-client)
to create an Android Chat App connecting to the existing 
[chat.netcore.io](http://chat.netcore.io/) Server Events back-end where it's able to communicate 
with existing Ajax clients and other connected Android Chat Apps. 

[![](https://raw.githubusercontent.com/ServiceStack/Assets/master/img/livedemos/xamarin-android-server-events.png)](https://www.youtube.com/watch?v=tImAm2LURu0)

> [YouTube Video](https://www.youtube.com/watch?v=tImAm2LURu0) and [AndroidXamarinChat Repo](https://github.com/ServiceStackApps/AndroidXamarinChat)

### [Networked Time Traveller Shape Creator](https://github.com/ServiceStackApps/typescript-redux#example-9---real-time-networked-time-traveller)

A network-enhanced version of the
[stand-alone Time Traveller Shape Creator](https://github.com/ServiceStackApps/typescript-redux#example-8---time-travelling-using-state-snapshots)
that allows users to **connect to** and **watch** other users using the App in real-time similar 
to how users can use Remote Desktop to watch another computer's screen: 

[![](https://raw.githubusercontent.com/ServiceStack/Assets/master/img/livedemos/redux-chrome-safari.png)](http://redux.servicestack.net)

> Live demo: http://redux.servicestack.net

### [Chat](https://github.com/ServiceStackApps/Chat)

> Feature-rich Single Page Chat App, showcasing Server Events support in 170 lines of JavaScript!

[![](https://raw.githubusercontent.com/ServiceStack/Assets/master/img/livedemos/chat.png)](http://chat.netcore.io)

### [React Chat Desktop](https://github.com/ServiceStackApps/ReactChatApps)

> Built with [React Desktop Apps](https://github.com/ServiceStackApps/ReactDesktopApps)
VS.NET template and packaged into a native Desktop App for Windows and OSX - showcasing synchronized 
real-time control of multiple Windows Apps:

[![](https://raw.githubusercontent.com/ServiceStack/Assets/master/img/livedemos/react-desktop-apps/dancing-windows.png)](https://youtu.be/-9kVqdPbqOM)

> Downloads for [Windows, OSX, Linux and Web](https://github.com/ServiceStackApps/ReactChatApps#downloads)


# C# Server Events Client
Source: https://docs.servicestack.net/csharp-server-events-client

Like ServiceStack's other [C# Service Clients](/csharp-client), the new `ServerEventsClient` is a [portable library](https://github.com/ServiceStackApps/HelloMobile) contained in the `ServiceStack.Client` NuGet package:

:::copy
`<PackageReference Include="ServiceStack.Client" Version="8.*" />`
:::

And like the Service Clients it requires the `BaseUri` of your ServiceStack instance as well as an optional `channel` for the client to subscribe to:

```csharp
var client = new ServerEventsClient(
    "http://chat.netcore.io", channels:"home");
```

### Managed Connection

The **C# ServerEvent Client** is a managed .NET client with feature parity with the [ServiceStack's JavaScript client](https://github.com/ServiceStackApps/Chat#client-bindings---ss-utilsjs) that **auto-reconnects** when a connection is lost, **sends periodic heartbeats** to maintain an active subscription as well as **auto-unregistering** once the client stops listening for messages, or gets disposed.

### Handling Server Events

Unlike other C# clients, the ServerEvents Client is mainly reactive in that it's primarily waiting for Server Events to be initiated from a remote server instead of the typical scenario in which requests are initiated by clients. To maximize utility, there are a number of different API's to receive and process messages:

### Assigning Callback Handlers

One way to receive messages (useful in long-running clients) is to assign handlers for each of the different events that are fired. This example shows how to capture all the different events a Client can receive:

```csharp
ServerEventConnect connectMsg = null;
var msgs = new List<ServerEventMessage>();
var commands = new List<ServerEventMessage>();
var errors = new List<Exception>();

var client = new ServerEventsClient(baseUri) {
    OnConnect = e => connectMsg = e,
    OnCommand = commands.Add,
    OnMessage = msgs.Add,
    OnException = errors.Add,
}.Start();
```

Once the Client is configured, calling `Start()` will start listening for messages and calling `Stop()` or `Dispose()` will cancel the background HTTP connection and stop it listening for server events.

### Customizing Metadata sent to clients

As ServerEvents have deep integration with the rest of ServiceStack we're able to offer [Typed Messages](https://github.com/ServiceStack/ServiceStack/blob/71b51d231d1ddb2ba7da39613e216ab75fd181c0/src/ServiceStack.Client/ServerEventsClient.cs#L14-L44) containing the users `UserAuthId`, `DisplayName` and `ProfileUrl` of the users avatar when it's available. The typed messages also offer an extensible `Dictionary<string,string> Meta` collection for maintaining custom metadata that can be sent to clients by appending to them in the ServerEventsFeature hooks, which can be defined when registering `ServerEventsFeature`:

```csharp
Plugins.Add(new ServerEventsFeature { 
    // private Connect args
    OnConnect = (subscription,httpReq) => AppendTo(subscription.Meta),

    // public Join/Leave args
    OnCreated = (subscription,httpReq) => AppendTo(subscription.Meta), 
})
``` 

Whilst distinct `OnJoin`, `OnLeave` `OnUpdate` and `OnReconnect` callbacks can be used to handle a specific event, e.g:

```csharp
var client = new ServerEventsClient(baseUrl, channel) {
    OnJoin = msg => ...,
    OnLeave = msg => ...,
    OnUpdate = msg => ...,
    OnReconnect = () => ...
};
```

### Using C# Async/Await friendly API's

Depending on your use-case, if you only want to use the ServerEvent Client for a short-time to listen for predictable responses (i.e. waiting for a Server callback on a pending request) you can alternatively use the Task-based API's letting you to participate in C# async/await workflows:

```csharp
var client = new ServerEventsClient(baseUri, channel="Home");

// Wait to receive onConnect event
ServerEventConnect connectMsg = await client.Connect();

// Wait to receive onJoin command event
ServerEventCommand joinMsg = await client.WaitForNextCommand();

// Hold a future task to get notified once a msg has been received
Task<ServerEventMessage> msgTask = client1.WaitForNextMessage();

// Send a Web Service Request using the built-in JsonServiceClient
client.ServiceClient.Post(new PostChatToChannel {
    Channel = client.Channel,     // The channel we're listening on
    From = client.SubscriptionId, // Populated after Connect() 
    Message = "Hello, World!",
});

// Wait till we receive the chat Msg event we sent earlier
ServerEventMessage msg = await msgTask;
```

The above example showcases the **3 Task-based API's** available:

  1. `Connect()` wait till receiving confirmation of a successful event subscription
  2. `WaitForNextCommand()` wait for the next `onJoin` or `onLeave` subscription events
  3. `WaitForNextMessage()` wait for the next message published to the channel

The `ServiceClient` property lets you access a `JsonServiceClient` that's pre-configured with the clients `BaseUri` so that is primed for Sending Web Service Requests with.

After the ServerEvent Client has connected, the `ConnectionInfo` property is populated with the typed `ServerEventConnect` response. 

### Message Event Handlers

The above examples show generic API's for receiving any type of message, but just like in the JavaScript client, more fine-grained API's are available for handling specific message types.

The `Handlers` dictionary is akin to the JavaScript Client's [Global Event Handlers](https://github.com/ServiceStackApps/Chat#global-event-handlers) which specify lambda's to be executed when messages are sent with the `cmd.*` selector:

```csharp
client.Handlers["chat"] = (client, msg) => {
    //Deserialize JSON string to typed DTO
    var chatMsg = msg.Json.FromJson<ChatMessage>(); 
    "Received '{0}' from '{1}'".Print(chatMsg.Message, chatMsg.FromName);
};
```

Roughly translates to the equivalent JavaScript below:

```javascript
$(source).handleServerEvents({
  handlers: {
    chat: function (msg, event) {
        console.log("Received " + msg.message + " from " + msg.fromName);
    }
  }
});
```

Where both methods handle the `ChatMessage` sent with the `cmd.chat` selector.

### Named Receivers

Whilst handlers provide a light way to handle loose-typed messages, there's a more structured and typed option that works similar to ServiceStack's `IService` classes but are used to instead handle typed Server Event Messages. 

To be able to handle messages with your own classes, get them to implement the `IReceiver` empty marker interface:

```csharp
public interface IReceiver
{
    void NoSuchMethod(string selector, object message);
}
```

Whilst primarily a marker interface, `IReceiver` does include a `NoSuchMethod` API to be able to handle messages sent with a unknown selector **target** that doesn't match any defined method or property.

**Named Receivers** are equivalent to [Receivers](https://github.com/ServiceStackApps/Chat#receivers) in the JavaScript client which can be assigned to handle all messages sent to a receiver with the selector format:

```
{receiver}.{target}
```

A Named Receiver can be registered with the API below:

```csharp
client.RegisterNamedReceiver<TestNamedReceiver>("test");
```

Which will forward all messages with a `test.*` selector to an instance of the `TestNamedReceiver` Type

```csharp
public class TestNamedReceiver : ServerEventReceiver
{
    public void FooMethod(CustomType request) {} // void return type

    public CustomType BarMethod(CustomType request)
    {        
        return request; // works with any return type, which are ignored
    }

    public CustomType BazSetter { get; set; } // Auto populate properties

    public override void NoSuchMethod(string selector, object message)
    {
        var msg = (ServerEventMessage)message;
        var nonExistentMethodType = msg.Json.FromJson<CustomType>();
    }
}
```

This is roughly equivalent to the following JavaScript code:

```javascript
$(source).handleServerEvents({
    receivers: {
        test: {
            FooMethod: function (msg, event) { ... },
            BarMethod: function (msg, event) { ... },
            BazSetter: null,            
        }
    }
});
```

> The [ServerEventReceiver](https://github.com/ServiceStack/ServiceStack/blob/68c7159037e7cf2a519d482b7dae524ca073da20/src/ServiceStack.Client/ServerEventsClient.Receiver.cs#L16-L28) is a convenient base class that in addition to implementing `IReceiver` interface, gets injected with the `Client` as well as additional context about the raw message available in `base.Request`.

#### Unknown Message Handling

One difference in the JavaScript client is that messages with **unknown** targets are assigned as properties on the `test` receiver, e.g `test.QuxTarget = {..}`.

### Sending messages to Named Receivers

Once registered, an instance of `TestNamedReceiver` will process messages sent with a `test.*` selector. The example below shows how to send a DTO to each of `TestNamedReceiver` defined methods and properties:

```csharp
public class MyEventServices : Service
{
    public IServerEvents ServerEvents { get; set; }

    public void Any(CustomType request)
    {
        ServerEvents.NotifyChannel("home", "test.FooMethod", request);
        ServerEvents.NotifyChannel("home", "test.BarMethod", request);
        ServerEvents.NotifyChannel("home", "test.BazSetter", request);

        ServerEvents.NotifyChannel("home", "test.QuxTarget", request);
    }
}
```

### Life-cycle of Receivers

Similar to **Services** in ServiceStack, each message is processed with an instance of the Receiver that's resolved from `ServerEventsClient.Resolver` which by default uses the [NewInstanceResolver](https://github.com/ServiceStack/ServiceStack/blob/ec0226b97227048c3bd7c24667a71e7af7e1ff31/src/ServiceStack.Client/ServerEventsClient.Receiver.cs#L30-L36) to execute messages using a new instance of the Receiver Type: 

```csharp
public class NewInstanceResolver : IResolver
{
    public T TryResolve<T>()
    {
        return typeof(T).CreateInstance<T>();
    }
}
```

This can be changed to re-use the same instance by assigning a [SingletonInstanceResolver](https://github.com/ServiceStack/ServiceStack/blob/ec0226b97227048c3bd7c24667a71e7af7e1ff31/src/ServiceStack.Client/ServerEventsClient.Receiver.cs#L38-L46) instead:

```csharp
public class SingletonInstanceResolver : IResolver
{
    ConcurrentDictionary<Type, object> Cache = 
        new ConcurrentDictionary<Type, object>();

    public T TryResolve<T>()
    {
        return (T)Cache.GetOrAdd(typeof(T), 
            type => type.CreateInstance<T>());
    }
}

client.Resolver = new SingletonInstanceResolver();
```

We can also have it resolve instances from your preferred IOC. Here's an example showing how to register all Receiver Types, auto-wire them with any custom dependencies, and instruct the client to resolve instances from our IOC:

```csharp
// Register all Receivers:
client.RegisterNamedReceiver<TestNamedReceiver>("test");
...

// Register all dependencies used in a new Funq.Container:
var container = new Container();
container.RegisterAs<Dependency, IDependency>();

// Go through an auto-wire all Registered Receiver Types with Funq:
container.RegisterAutoWiredTypes(client.ReceiverTypes);

// Change the client to resolve receivers from the new Funq Container:
client.Resolver = container;
```

We can assign `Funq.Container` directly as it already implements the [IResolver](https://github.com/ServiceStack/ServiceStack/blob/master/src/ServiceStack.Interfaces/Configuration/IResolver.cs) interface, whilst you can re-use the existing IOC **Container Adapters** to [enable support for other IOCs](/ioc#use-another-ioc-container). 

### The Global Receiver

Whilst Named Receivers are used to handle messages sent to a specific namespaced selector, the client also supports registering a **Global Receiver** for handling messages sent with the special `cmd.*` selector.

#### Handling Messages with the Default Selector

All `IServerEvents` Notify API's inlcudes [overloads for sending messages without a selector](https://github.com/ServiceStack/ServiceStack/blob/master/src/ServiceStack/ServerEventsFeature.cs#L743-L771) that by convention will take the format `cmd.{TypeName}`. 

These events can be handled with a Global Receiver **based on Message type**, e.g:

```csharp
public class GlobalReceiver : ServerEventReceiver
{
    public SetterType AnyNamedProperty { get; set; }

    public void AnyNamedMethod(CustomType request)
    {
        ...
    }
}

client.RegisterReceiver<GlobalReceiver>();
```

Which will be called when messages are sent without a selector, e.g:

```csharp
public class MyServices : Service
{
    public IServerEvents ServerEvents { get; set; }

    public void Any(Request request)
    {
        ServerEvents.NotifyChannel("home", new CustomType { ... });
        ServerEvents.NotifyChannel("home", new SetterType { ... });
    }
}
```

As Global Receivers handle other messages sent with the `cmd.*` selector and can be re-used as a named receiver, we can define a single class to handle all the different custom messages sent in [chat.netcore.io](http://chat.netcore.io) App, E.g:

```
cmd.chat Hi
cmd.announce This is your captain speaking...
cmd.toggle#channels
css.background-image url(https://servicestack.net/img/bg.jpg)
...
```

The above messages can all be handled with the Receiver below:

```csharp
public class JavaScriptReceiver : ServerEventReceiver
{
    public void Chat(ChatMessage message) { ... }
    public void Announce(string message) { ... }
    public void Toggle(string message) { ... }
    public void BackgroundImage(string cssRule) { ... }
}

client.RegisterReceiver<JavaScriptReceiver>();
client.RegisterNamedReceiver<JavaScriptReceiver>("css");
```

As seen above the **target** names are **case-insensitive** and `-` are collapsed to cater for JavaScript/CSS naming conventions.

## Event Triggers

Triggers enable a pub/sub event model where multiple listeners can subscribe and be notified of an event.

Registering an event handler can be done at anytime using the `addListener()` API, e.g:

```csharp
Action<ServerEventMessage> handler = msg => {
    Console.WriteLine($"received event ${msg.Target} with arg: ${msg.Json}");
};

var client = new ServerEventsClient("/", channels)
    .AddListener("customEvent", handler)
    .Start();

//Register another listener to 'customEvent' event
client.AddListener("customEvent", msg => { ... });
```

The selector to trigger this custom event is:

```
trigger.customEvent arg
trigger.customEvent {json}
```

Which can be sent in ServiceStack with a simple or complex type argument, e.g:

```csharp
ServerEvents.NotifyChannel(channel, "trigger.customEvent", "arg");
ServerEvents.NotifyChannel(channel, "trigger.customEvent", new ChatMessage { ... });
```

#### Removing Listeners

Use `RemoveListener()` to stop listening for an event, e.g:

```csharp
//Remove first event listener
client.RemoveListener("customEvent", handler);
```

## Channel Subscriber APIs

The sync/async APIs below built into the C# `ServerEventsClient` will let you modify an active Server Events
subscription to join new or leave existing channels:

```csharp
client.UpdateSubscriber(new UpdateEventSubscriber { 
    SubscribeChannels = new[]{ "chan1", "chan2" },
    UnsubscribeChannels = new[]{ "chan3", "chan4" },
});

client.SubscribeToChannels("chan1", "chan2");
client.UnsubscribeFromChannels("chan3", "chan4");

await client.SubscribeToChannelsAsync("chan1", "chan2");
await client.UnsubscribeFromChannelsAsync("chan3", "chan4");
```

### onUpdate Notification

As this modifies the active subscription it also publishes a new **onUpdate** notification to all channel 
subscribers so they're able to maintain up-to-date info on each subscriber. 
This can be handled together with **onJoin** and **onLeave** events using `OnCommand`:

```csharp
client.OnCommand = msg => ...; //= ServerEventJoin, ServerEventLeave or ServerEventUpdate
```

## Add Authentication support to .NET ServerEvents Client

The explicit `Authenticate` and `AuthenticateAsync` API's can be used to authenticate the ServerEvents ServiceClient which **shares cookies** with the WebRequest that connects to the `/event-stream` so authenticating with the Server Events ServiceClient will also authenticate the `/event-stream` HTTP Connection:

```csharp
client.Authenticate(new Authenticate {
    provider = CredentialsAuthProvider.Name,
    UserName = "user",
    Password = "pass",
    RememberMe = true,
});

client.Start();
```

This is equivalent to:

```csharp
client.ServiceClient.Post(new Authenticate {
    provider = CredentialsAuthProvider.Name,
    UserName = "user",
    Password = "pass",
    RememberMe = true,
});
```

## Custom Authentication

When using a [JWT](/auth/jwt-authprovider) or [API Key](/auth/api-key-authprovider) AuthProvider you can [send it inside a Cookie](/auth/jwt-authprovider#sending-jwt-using-cookies) so it gets sent with client Web Requests. Otherwise you can add the JWT Token or API Key using the `EventStreamRequestFilter` which gets executed before establishing the Server Events connection, e.g:

```csharp
new ServerEventsClient(...) {
    EventStreamRequestFilter = req => req.AddBearerToken(jwt)
}
```

Alternatively you can use `ResolveStreamUrl` which will let you modify the URL used to establish the Server Events connection which will also allow you to add the JWT Token to the QueryString as, e.g:

```csharp
var sseClient = new ServerEventsClient(baseUrl, channels) 
{
    ResolveStreamUrl = url => url.AddQueryParam("ss-tok", JWT),
    OnConnect = e => {
        $"{e.IsAuthenticated}, {e.UserId}, {e.DisplayName}".Print();
    }
}.Start();
```

This requires that your JWT AuthProvider to accept JWT Tokens via the QueryString which you can enable in ServiceStack's JWT AuthProvider with:

```csharp
new JwtAuthProvider {
    AllowInQueryString = true
}
```

To configure API Key AuthProvider to accept API Key in Request Params like QueryString or FormData:

```csharp
new ApiKeyAuthProvider {
    AllowInHttpParams = true
}
```

## Troubleshooting

The Server Events Client uses .NET's `HttpWebRequest` internally for its long-running SSE connection and periodic heartbeats where if you're also using 
other .NET ServiceClients to make API requests back to the same server you'll quickly hit its default limit (2) on number of requests allowed for a single domain 
which can be increased by changing [ServicePointManager.DefaultConnectionLimit](https://msdn.microsoft.com/en-us/library/system.net.servicepointmanager.defaultconnectionlimit(v=vs.110).aspx), e.g:

```csharp
ServicePointManager.DefaultConnectionLimit = maxNumOfConcurrentConnections;
```

# ServerEvent .NET Examples

## [Xamarin.Android Chat](https://github.com/ServiceStackApps/AndroidXamarinChat)

Xamarin.Android Chat utilizes the 
[.NET PCL Server Events Client](/csharp-server-events-client)
to create an Android Chat App connecting to the existing 
[chat.netcore.io](http://chat.netcore.io/) Server Events back-end where it's able to communicate 
with existing Ajax clients and other connected Android Chat Apps. 

[![](https://raw.githubusercontent.com/ServiceStack/Assets/master/img/livedemos/xamarin-android-server-events.png)](https://www.youtube.com/watch?v=tImAm2LURu0)

> [YouTube Video](https://www.youtube.com/watch?v=tImAm2LURu0) and [AndroidXamarinChat Repo](https://github.com/ServiceStackApps/AndroidXamarinChat)


# TypeScript Server Events Client
Source: https://docs.servicestack.net/typescript-server-events-client

![ServiceStack and TypeScript Banner](https://raw.githubusercontent.com/ServiceStack/Assets/master/img/release-notes/servicestack-heart-typescript.png)

The TypeScript `ServerEventClient` is an idiomatic port of ServiceStack's 
[C# Server Events Client](/csharp-server-events-client) in native TypeScript providing a productive 
client to consume ServiceStack's [real-time Server Events](/server-events) that can be used in both 
TypeScript Web and node.js server applications.

## Install

`ServerEventClient` is available in the 
[@servicestack/client npm package](https://github.com/ServiceStack/servicestack-client) 
which is preconfigured in all [ServiceStackVS TypeScript VS.NET Templates](https://github.com/ServiceStack/ServiceStackVS)

npm based projects can install it with:

```bash
$ npm install @servicestack/client
```

To configure Server Sent Events on the client create a new instance of `ServerEventsClient` with the
**baseUrl** and the **channels** you want to connect to, e.g:

```ts
const channels = ["home"];
const client = new ServerEventsClient("/", channels, {
    handlers: {
        onConnect: (sub:ServerEventConnect) => {  // Successful SSE connection
            console.log("You've connected! welcome " + sub.displayName);
        },
        onJoin: (msg:ServerEventJoin) => {        // User has joined subscribed channel
            console.log("Welcome, " + msg.displayName);
        },
        onLeave: (msg:ServerEventLeave) => {      // User has left subscribed channel
            console.log(msg.displayName + " has left the building");
        },
        onUpdate: (msg:ServerEventUpdate) => {    // User channel subscription was changed
            console.log(msg.displayName + " channels subscription were updated");
        },        
        onMessage: (msg:ServerEventMessage) => {} // Invoked for each other message
        //... Register custom handlers
        announce: (text:string) => {}             // Handle messages with simple argument
        chat: (chatMsg:ChatMessage) => {}         // Handle messages with complex type argument
        CustomMessage: (msg:CustomMessage) => {}  // Handle complex types with default selector
    },
    receivers: { 
        //... Register any receivers
        tv: {
            watch: function (id) {                // Handle 'tv.watch {url}' messages 
                var el = document.querySelector("#tv");
                if (id.indexOf('youtu.be') >= 0) {
                    var v = splitOnLast(id, '/')[1];
                    el.innerHTML = templates.youtube.replace("{id}", v);
                } else {
                    el.innerHTML = templates.generic.replace("{id}", id);
                }
                el.style.display = 'block'; 
            },
            off: function () {                    // Handle 'tv.off' messages
                var el = document.querySelector("#tv");
                el.style.display = 'none';
                el.innerHTML = '';
            }
        }
    },
    onException: (e:Error) => {},                 // Invoked on each Error
    onReconnect: (e:Error) => {}                  // Invoked after each auto-reconnect
})
.addListener("theEvent",(e:ServerEventMessage) => {}) // Add listener for pub/sub event trigger
.start();                                             // Start listening for Server Events!
```

> If hosted from same ServiceStack Instance, the relative `/` url can be used instead of the absolute `baseUrl` 

### Message Events

ServiceStack Server Events has 4 built-in events sent during a subscriptions life-cycle: 

 - **onConnect** - sent when successfully connected, includes the subscriptions private `subscriptionId` as well as heartbeat and unregister urls that's used to automatically setup periodic heartbeats
 - **onJoin** - sent when a new user joins the channel
 - **onLeave** - sent when a user leaves the channel
 - **onUpdate** - sent when a user's channels subscription was updated

> The onJoin/onLeave/onUpdate events can be turned off with `ServerEventsFeature.NotifyChannelOfSubscriptions=false`.

All other messages can be handled with the catch-all:

 - **onMessage** - fired when any other message is sent

### Server Event Client Events

Other top-level events the `ServerEventClient` fires that can be handled include: 

 - **onException** - Invoked on each error the client receives
 - **onReconnect** - Invoked after each time the client had to auto-reconnect
 - **onTick** - Invoked after any event or state change

## Selectors

A selector is a string that identifies what should handle the message, it's used by the client to route the message to different handlers. The client bindings supports 4 different handlers out of the box:

### Global Event Handlers

The easiest way to handle a custom event is to define a handler, e.g:

```ts
const client = new ServerEventsClient("/", channels, {
    handlers: {
        paint: (color:string) => {
            this.style.background = color;
        },
        chat: (chatMsg:ChatMessage, e:ServerEventMessage) => {
        }
    }
}).start();
```

The selector to invoke a global event handler is:

```
cmd.{handler} {message}
```

Which can be sent in ServiceStack with:

```csharp
ServerEvents.NotifyChannel(channel, "cmd.paint", "green");
ServerEvents.NotifyChannel(channel, "cmd.chat", new ChatMessage { ... });
```

Where `{handler}` is the name of the handler you want to invoke, e.g `cmd.paint`. When invoked from a server event the message (deserialized from JSON) is the first argument, the Server Sent DOM Event is the 2nd argument and `this` by default is assigned to `document.body`.

```ts
function paint(msg /* JSON object msg */, e /*ServerEventMessage*/){
    this // HTML Element or document.body
    this.style.background = "green";
}
```

#### Handling Messages with the Default Selector

All `IServerEvents` Notify API's includes [overloads for sending messages without a selector](https://github.com/ServiceStack/ServiceStack/blob/master/src/ServiceStack/ServerEventsFeature.cs#L743-L771) that by convention will take the format `cmd.{TypeName}`. 

As they're prefixed with `cmd.*` these events can be handled with a handler **based on Message type name**, e.g:

```ts
const client = new ServerEventsClient("/", channels, {
    handlers: {
        CustomType: (msg:CustomType) => { ... },
        SetterType: (msg:SetterType, e:ServerEventMessage) => { ... }
    }
}).start();
```

Which will be called when messages are sent without a selector, e.g:

```csharp
public class MyServices : Service
{
    public IServerEvents ServerEvents { get; set; }

    public void Any(Request request)
    {
        ServerEvents.NotifyChannel("home", new CustomType { ... });
        ServerEvents.NotifyChannel("home", new SetterType { ... });
    }
}
```

### Postfix CSS selector 

All server event handler options also support a postfix CSS selector for specifying what each handler should be bound to with a `$` followed by the CSS selector, e.g:

```
cmd.{handler}${cssSelector}
```

A concrete example for calling the above API would be:

```
cmd.paintGreen$#btnPaint
```

Which will bind `this` to the `#btnSubmit` HTML Element.

::: info
Spaces in CSS selectors need to be encoded with `%20`
:::

### Modifying CSS

As it's a popular use-case Server Events also has native support for modifying CSS properties with:

```
css.{propertyName}${cssSelector} {propertyValue}
```

Where the message is the property value, which roughly translates to:

```js
document.querySelectorAll({cssSelector}).style[{propertyName}] = {propertyValue}
```

When no CSS selector is specified it falls back to `document.body` by default.

```
css.background #eceff1
```

Some other examples include:

```
css.background$#top #673ab7   // $('#top').css('background','#673ab7')
css.font$li bold 12px verdana // $('li').css('font','bold 12px verdana')
css.visibility$a,img hidden   // $('a,img').css('visibility','#673ab7')
css.visibility$a%20img hidden // $('a img').css('visibility','hidden')
```

### Receivers

In programming languages based on message-passing like Smalltalk and Objective-C invoking a method is done by sending a message to a receiver. This is conceptually equivalent to invoking a method on an instance in C# where both these statements are roughly equivalent:

```objc
// Objective-C
[receiver method:argument]
```

```csharp
// C#
receiver.method(argument)
```

Support for receivers is available in the following format:

```
{receiver}.{target} {msg}
```

### Registering Receivers

Registering a receiver can be done with a map of the object instance and the name you want it to be exported as. E.g. The `window` and `document` global objects can be setup to receive messages with:

```ts
const client = new ServerEventsClient("/", channels, {
    receivers: {
        "window": window, 
        "document": document 
    }
}).start();
```

Alternatively you can add receivers at runtime with:

```ts
const client = new ServerEventsClient("/", channels)
    .registerNamedReceiver("window", window);
    .registerNamedReceiver("document", document)
    .start();
```

Once registered you can set any property or call any method on a receiver with:

```
document.title New Window Title
window.location http://google.com
```

Where if `{target}` was a function it will be invoked with the message, otherwise its property will be set.
By default when no `{cssSelector}` is defined, `this` is bound to the **receiver** instance.

Example of setting up a custom receiver:

```ts
const client = new ServerEventsClient("/", channels, {
    receivers: {
        tv: {
            watch: function (id) {
                var el = document.querySelector("#tv");
                if (id.indexOf('youtu.be') >= 0) {
                    var v = splitOnLast(id, '/')[1];
                    el.innerHTML = templates.youtube.replace("{id}", v);
                } else {
                    el.innerHTML = templates.generic.replace("{id}", id);
                }
                el.style.display = 'block'; 
            },
            off: function () {
                var el = document.querySelector("#tv");
                el.style.display = 'none';
                el.innerHTML = '';
            }
        }
    }
}).start();
```

This registers a custom `tv` receiver that can now be called with:

```
tv.watch http://youtu.be/518XP8prwZo
tv.watch https://servicestack.net/img/logo-220.png
tv.off
```

### Receiver Constructors

In addition to registering an object instance as a receiver, you can also specify a `class` 
(aka constructor Function) instead, e.g:

```ts
class CssReceiver {
    backgroundImage(url:string) {
        document.body.style.backgroundImage = url;
    }
}

const client = new ServerEventsClient("/", channels, {
    receivers: {
        css: CssReceiver
    }
}).start();
```

Which will invoke `backgroundImage` method off a new instance of the `CssReceiver` class that's triggered with:

```
css.background-image url(https://bit.ly/1yIJOBH)
```

and can be sent to all subscriptions on the **home** channel in ServiceStack with:

```csharp
ServerEvents.NotifyChannel("home", "css.background-image", "url(https://bit.ly/1yIJOBH)");
```

This works the same with Global Receivers, in addition Receivers can extend `ServerEventReceiver`:

```ts
class ServerEventReceiver implements IReceiver {
    public client: ServerEventsClient;
    public request: ServerEventMessage;
    noSuchMethod(selector: string, message:any) {}
}
```

To access additional built-in functionality where it will allow receivers to access the `ServerEventsClient` 
client dependency, the `ServerEventMessage` that was received, it also lets you handle any unhandled messages 
sent by implementing `noSuchMethod()`, e.g:

```ts
class JavaScriptReceiver extends ServerEventReceiver {

    chatMessage(msg: ChatMessage) {
        let request = new LogMessage();
        request.channel = msg.channel;
        request.message = msg.message;

        this.client.serviceClient.post(request)
            .then(r => {
                console.log(`logged ${msg.message} sent by ${msg.fromName} to ${msg.channel}`);
            });
    }
    
    announce(message:string) {
        alert(message);
    }

    toggle() {
        let el = document.querySelector(this.request.cssSelector);
        el.style.display = el.style.display != "none" ? "none" : "block";
    }

    noSuchMethod(selector:string, message:ServerEventMessage) {
        console.log(`Unhandled ${selector} was sent message: `, message);
    }
}

client.registerReceiver(JavaScriptReceiver); //register Global Receiver
```

These can triggered with:

```csharp
ServerEvents.NotifyChannel(channel, new ChatMessage { ... });
ServerEvents.NotifyChannel(channel, "cmd.announce", "Hello, World!");
ServerEvents.NotifyChannel(channel, "cmd.toggle$#sidebar");
ServerEvents.NotifyChannel(channel, "cmd.UnknownSelector", new Message { ... });
```

### Dependency Resolvers

You can control the lifetime of the receivers by injecting a custom resolver which will let you reuse the same
Receiver instance by using a `SingletonInstanceResolver`, e.g:

```ts
const client = new ServerEventsClient("/", channels)
    .setResolver(new SingletonInstanceResolver())
    .registerReceiver(JavaScriptReceiver)
    .start();
```

Which is implemented with:

```ts
export class SingletonInstanceResolver implements IResolver {
    tryResolve(ctor:ObjectConstructor): any {
        return (ctor as any).instance 
            || ((ctor as any).instance = new ctor());
    }
}
```

### Un Registering a Receiver

As receivers are maintained in a simple map, they can be disabled at anytime with:

```ts
client.unregisterReceiver("window");
```

and re-enabled with:

```ts
client.registerNamedReceiver("window", window);
```

Whilst Named Receivers are used to handle messages sent to a specific namespaced selector, the client also supports registering a **Global Receiver** for handling messages sent with the special `cmd.*` selector.

### Event Triggers

Triggers enable a pub/sub event model where multiple listeners can subscribe and be notified of an event.

Registering an event handler can be done at anytime using the `addListener()` API, e.g:

```ts
const handler = (e:ServerEventMessage) => {
    console.log(`received event ${e.target} with arg: ${JSON.parse(e.json)}`);
}

const client = new ServerEventsClient("/", channels)
    .addListener("customEvent", handler)
    .start();

//Register another listener to 'customEvent' event
client.addListener("customEvent", e => { ... });
```

The selector to trigger this custom event is:

```
trigger.customEvent arg
trigger.customEvent {json}
```

Which can be sent in ServiceStack with a simple or complex type argument, e.g:

```ts
ServerEvents.NotifyChannel(channel, "trigger.customEvent", "arg");
ServerEvents.NotifyChannel(channel, "trigger.customEvent", new ChatMessage { ... });
```

#### Removing Listeners

Use `removeListener()` to stop listening for an event, e.g:

```ts
//Remove first event listener
client.removeListener("customEvent", handler);
```

### Channel Subscriber APIs

You can use any of the APIs below to update an active Subscriptions Channels:

```ts
client.subscribeToChannels("chan3","chan4");
client.unsubscribeFromChannels("chan1","chan2");

//Alternatively subscribe/unsubscribe to channels in the same request with:
var request = new UpdateEventSubscriber();
request.subscribeChannels = ["chan3","chan4"];
request.unsubscribeChannels = ["chan1","chan2"];
client.updateSubscriber(request);
```

### Get Channel Subscribers

Once connected, you can get a list of channel subscribers the `ServerEventsClient` is currently connected
to with:

```ts
client.getChannelSubscribers()
    .then(users => users.forEach(x => 
        console.log(`#${x.userId} @${x.displayName} ${x.profileUrl} ${x.channels}`)));
```

### Accessing ServiceClient

Alternatively you can access the channel subscribers using the built-in `JsonServiceClient`, e.g:

```ts
let request = new GetEventSubscribers();
request.channels = ["chan1","chan2"];

client.serviceClient.get(request)
    .then(r => ...);
```

Which you can also use to call your own Services:

```ts
client.serviceClient.post(new MyRequest())
    .then(r => ...)
```

## Authentication via JWT

As the TypeScript `ServerEventsClient` needs to use the browsers native EventSource class to establish the SSE connection it's not able to customize 
the HTTP Request Headers in other clients but as the client shares the same cookies with the browser you can use a JWT Token Cookie either
by Requesting to use a [JWT Token Cookie at Authentication](/auth/jwt-authprovider#request-jwt-cookie-is-set-on-authentication) or by setting the Token
Cookie on the client, [CORS permitting](/corsfeature), e.g:

```js
document.cookie = "ss-tok={Token}";
```

Alternatively you can enable authenticating via JWT on the QueryString:

### Send JWTs in HTTP Params

The JWT Auth Provider can **opt-in** to accept JWT's via the Query String or HTML POST FormData with:

```csharp
new JwtAuthProvider {
    AllowInQueryString = true,
    AllowInFormData = true
}
```

This is useful for situations where it's not possible to attach the JWT in the HTTP Request Headers or `ss-tok` Cookie. 

For example if you wanted to authenticate via JWT to a real-time [Server Events stream](/server-events) from a token retrieved from a remote auth server (i.e. so the JWT Cookie isn't already configured with the SSE server) you can [call the /session-to-token API](/auth/jwt-authprovider#ajax-clients) to convert the JWT Bearer Token into a JWT Cookie which will configure it with that domain so the subsequent HTTP Requests to the SSE event stream contains the JWT cookie and establishes an authenticated session:

```ts
var client = new JsonServiceClient(BaseUrl);
client.setBearerToken(JWT);
await client.post(new ConvertSessionToToken());

var sseClient = new ServerEventsClient(BaseUrl, ["*"], {
    handlers: {
        onConnect: e => { 
            console.log(e.isAuthenticated /*true*/, e.userId, e.displayName);
        }
    }
}).start();
```

Unfortunately this wont work in `node.exe` Server Apps (or in integration tests) which doesn't support a central location for configuring domain cookies. One solution that works everywhere is to add the JWT to the `?ss-tok` query string that's used to connect to the `/event-stream` URL, e.g:

```csharp
var sseClient = new ServerEventsClient(BaseUrl, ["*"], {
    resolveStreamUrl: url => appendQueryString(url, { "ss-tok": JWT }),
    handlers: {
        onConnect: e => { 
            console.log(e.isAuthenticated /*true*/, e.userId, e.displayName);
        }
    }
}).start();
```

### Integration Test Examples

More examples of the `ServerEventClient` can be found in the [TypeScript ServerEventClient Test Suite](https://github.com/ServiceStack/servicestack-client/blob/master/tests/serverevents.spec.ts).

# TypeScript ServerEvents Examples

## [Web, Node.js and React Native ServerEvents Apps](https://github.com/ServiceStackApps/typescript-server-events)

Using TypeScript ServerEvents Client to create real-time Web, node.js server and React Native Mobile Apps:

[![](https://raw.githubusercontent.com/ServiceStack/Assets/master/img/livedemos/typescript-serverevents/typescript-server-events-banner.png)](https://github.com/ServiceStackApps/typescript-server-events)

## [Gistlyn](https://github.com/ServiceStack/Gistlyn)

Gistlyn is a C# Gist IDE for creating, running and sharing stand-alone, executable C# snippets.

[![](https://raw.githubusercontent.com/ServiceStack/Assets/master/img/livedemos/gistlyn/home-screenshot.png)](http://gistlyn.com)

> Live Demo: http://gistlyn.com

## [React Chat](https://github.com/ServiceStackApps/ReactChat)

React Chat is a port of [ServiceStack Chat](https://github.com/ServiceStackApps/Chat) ES5, jQuery Server Events 
demo into a [TypeScript](http://www.typescriptlang.org/), [React](http://facebook.github.io/react/) and 
[Redux](https://github.com/reactjs/redux) App:

![](https://raw.githubusercontent.com/ServiceStack/Assets/master/img/livedemos/chat-react/screenshot.png)

## [Networked Time Traveller Shape Creator](https://github.com/ServiceStackApps/typescript-redux#example-9---real-time-networked-time-traveller)

A network-enhanced version of the
[stand-alone Time Traveller Shape Creator](https://github.com/ServiceStackApps/typescript-redux#example-8---time-travelling-using-state-snapshots)
that allows users to **connect to** and **watch** other users using the App in real-time similar 
to how users can use Remote Desktop to watch another computer's screen: 

[![](https://raw.githubusercontent.com/ServiceStack/Assets/master/img/livedemos/redux-chrome-safari.png)](http://redux.servicestack.net)

> Live demo: http://redux.servicestack.net

## [Chat](https://github.com/ServiceStackApps/Chat)

> Feature-rich Single Page Chat App, showcasing Server Events support in 170 lines of JavaScript!

[![](https://raw.githubusercontent.com/ServiceStack/Assets/master/img/livedemos/chat.png)](http://chat.netcore.io)

## [React Chat Desktop](https://github.com/ServiceStackApps/ReactChatApps)

> Built with [React Desktop Apps](https://github.com/ServiceStackApps/ReactDesktopApps)
VS.NET template and packaged into a native Desktop App for Windows and OSX - showcasing synchronized 
real-time control of multiple Windows Apps:

[![](https://raw.githubusercontent.com/ServiceStack/Assets/master/img/livedemos/react-desktop-apps/dancing-windows.png)](https://youtu.be/-9kVqdPbqOM)

> Downloads for [Windows, OSX, Linux and Web](https://github.com/ServiceStackApps/ReactChatApps#downloads)


# Java Server Events Client
Source: https://docs.servicestack.net/java-server-events-client

![ServiceStack and Java Banner](/img/pages/java/java-client-logo.png)

The Java `ServerEventClient` is an idiomatic port of ServiceStack's 
[C# Server Events Client](/csharp-server-events-client) to Java providing a productive 
client to consume ServiceStack's [real-time Server Events](/server-events) that can be used in any 
Java/JVM (JRE 7+) Client/Server Applications or Java/Kotlin Android applications.

## Install

The `AndroidServerEventsClient` for Android is available in the 
[net.servicestack:android](https://bintray.com/servicestack/maven/ServiceStack.Android) package which 
can be installed in your 
[build.gradle](https://github.com/ServiceStackApps/AndroidJavaChat/blob/master/src/androidchat/app/build.gradle)
with:

```groovy
dependencies {
    implementation 'net.servicestack:android:1.1.0'
    ...
}
```

Or in Maven with:

```xml
<dependency>
  <groupId>net.servicestack</groupId>
  <artifactId>android</artifactId>
  <version>1.1.0</version>
  <type>pom</type>
</dependency>
```

Other Java/JVM languages running on the JVM (JRE 7+) can use the `ServerEventsClient` in the 
[net.servicestack:client](https://bintray.com/servicestack/maven/ServiceStack.Client) package which can 
be installed using Gradle:

```
compile 'net.servicestack:client:1.0.48'
```

Or Maven:

```xml
<dependency>
  <groupId>net.servicestack</groupId>
  <artifactId>client</artifactId>
  <version>1.0.48</version>
  <type>pom</type>
</dependency>
```

The `AndroidServerEventsClient` class for Android inherits `ServerEventsClient` to provide enhanced
functionality like alternative non-blocking APIs for all Sync APIs using Android Async Tasks. It also requires
the use of an external [OkHttp Client](http://square.github.io/okhttp/) dependency since the 
`HttpURLConnection` implementation in Android doesn't support cancellable non-blocking requests on HTTP Streams. Otherwise both implementations provide the same functionality and are interchangeable, for the 
purposes of demonstration we'll be using `AndroidServerEventsClient`. 

To configure Server Sent Events on the client create a new instance of `AndroidServerEventsClient` with the
**baseUrl** and the **channels** you want to connect to, e.g:

```java
ServerEventsClient client = new AndroidServerEventsClient(baseUrl, "home")
    .setOnConnect(sub -> {                        // Successful SSE connection
        Log.d("You've connected! welcome " + sub.getDisplayName());
    })
    .setOnJoin(e -> {                             // User has joined subscribed channel
        Log.d("Welcome, " + e.getDisplayName());
    })
    .setOnLeave(e -> {                            // User has left subscribed channel
        Log.d(e.getDisplayName() + " has left the building");
    })
    .setOnUpdate(e -> {                           // User channel subscription was changed
        Log.d(e.getDisplayName() + " has left the building");
    })
    .setOnMessage(msg -> { })                     // Invoked for each other message
    //... Register custom handlers
    .registerHandler("chat", (client, e) -> {     // Invoked for cmd.chat adhoc messages
        ChatMessage chatMsg = JsonUtils.fromJson(e.getJson(), ChatMessage.class);
    })    
    .registerReceiver(MyReceiver.class)           // Register Global 'cmd.' default receiver
    .registerNamedReceiver("tv",TvReceiver.class) // Register named 'tv.' receiver
    .addListener("theEvent", msg -> {})           // Add listener for pub/sub event trigger
    .setOnException(e -> { })                     // Invoked on each Error
    .setOnReconnect(() -> { })                    // Invoked after each auto-reconnect
    .start();                                     // Start listening for Server Events!

//Global Receiver Class
public class MyReceiver extends ServerEventReceiver {
    public void announce(String message){}       // Handle messages with simple argument
    public void chat(ChatMessage message){}      // Handle messages with complex type argument
    public void customType(CustomType message){} // Handle complex types with default selector      
    @Override                                    // Handle other unknown messages
    public void noSuchMethod(String selector, Object message){}
}

//Named Receiver Class
public class TvReciever extends ServerEventReceiver {
    public void watch(String videoUrl){}         // Handle 'tv.watch {url}' messages 
    public void off(){}                          // Handle 'tv.off' messages 
}
```

### Message Events

ServiceStack Server Events has 4 built-in events sent during a subscriptions life-cycle: 

 - **onConnect** - sent when successfully connected, includes the subscriptions private `subscriptionId` as well as heartbeat and unregister urls that's used to automatically setup periodic heartbeats
 - **onJoin** - sent when a new user joins the channel
 - **onLeave** - sent when a user leaves the channel
 - **onUpdate** - sent when a user's channels subscription was updated

> The onJoin/onLeave/onUpdate events can be turned off with `ServerEventsFeature.NotifyChannelOfSubscriptions=false`.

All other messages can be handled with the catch-all:

 - **onMessage** - fired when any other message is sent

### Server Event Client Events

Other top-level events the `ServerEventClient` fires that can be handled include: 

 - **onException** - Invoked on each error the client receives
 - **onReconnect** - Invoked after each time the client had to auto-reconnect

## Selectors

A selector is a string that identifies what should handle the message, it's used by the client to route the message to different handlers. The client bindings supports 4 different handlers out of the box:

### Global Event Handlers

The easiest way to handle a custom event is to define a handler, e.g:

```java
ServerEventsClient client = new AndroidServerEventsClient(baseUrl, "home")
    .registerHandler("paint", (client, e) -> {
        String color = JsonUtils.fromJson(e.getJson(), String.class);
        Log.d("Painting the " + e.getCssSelector() + " " + color);
    })
    .registerHandler("chat", (client, e) -> {
        ChatMessage chatMsg = JsonUtils.fromJson(e.getJson(), ChatMessage.class);
        Log.d("Received " + chatMsg.getMessage() + " from " + chatMsg.getFromName());
    })
    .start();
```

The selector to invoke a global event handler is:

```
cmd.{handler} {message}
```

Which can be sent in ServiceStack with:

```csharp
ServerEvents.NotifyChannel("home", "cmd.paint$#town", "red");
ServerEvents.NotifyChannel("home", "cmd.chat", new ChatMessage { ... });
```

Where `{handler}` is the name of the handler you want to invoke, e.g `cmd.paint`. The first argument is
the `ServerEventsClient` instance whilst the 2nd argument a structured `ServerEventMessage` which for 
the above Server Event is populated with:

```java
.registerHandler("paint", (client, e) -> {
    e.getChannel()     //= home
    e.getData()        //= home@cmd.paint$#town "red"
    e.getSelector()    //= cmd.paint
    e.getJson()        //= "red"
    e.getOp()          //= cmd
    e.getTarget()      //= paint
    e.getCssSelector() //= #town
})
```

The message body is serialized as JSON and accessible from `e.getJson()` and can be extracted using `JsonUtils`,e.g:

```java
String color = JsonUtils.fromJson(e.getJson(), String.class); //Simple string message body
ChatMessage chatMsg = JsonUtils.fromJson(e.getJson(), ChatMessage.class); //Complex Type body
```

### Postfix CSS selector 

All server event handler options also support a postfix CSS selector for specifying what each handler should be bound to with a `$` followed by the CSS selector, e.g:

```
cmd.{handler}${cssSelector} {value}
```

A concrete example for calling the above API would be:

```
cmd.paint$#town red
```

::: info
Spaces in CSS selectors need to be encoded with `%20`
:::

#### Handling Messages with the Default Selector

All `IServerEvents` Notify API's includes [overloads for sending messages without a selector](https://github.com/ServiceStack/ServiceStack/blob/master/src/ServiceStack/ServerEventsFeature.cs#L743-L771) that by convention will take the format `cmd.{TypeName}`. 

As they're prefixed with `cmd.*` these events can be handled with either a handler (as above) or a global receiver **based on Message type name**, e.g:

```java
ServerEventsClient client = new AndroidServerEventsClient(baseUrl, "home")
    .registerReceiver(MyGlobalReceiver.class)
    .start();

public class TestGlobalReceiver extends ServerEventReceiver {
    public void setterType(SetterType value) {
    }
    public void customType(CustomType request) {
    }
}
```

Which will be called when messages are sent without a selector, e.g:

```csharp
public class MyServices : Service
{
    public IServerEvents ServerEvents { get; set; }

    public void Any(Request request)
    {
        ServerEvents.NotifyChannel("home", new CustomType { ... });
        ServerEvents.NotifyChannel("home", new SetterType { ... });
    }
}
```

Whilst Named Receivers are used to handle messages sent to a specific namespaced selector, registering a 
**Global Receiver** allows you to handle messages sent with the `cmd.*` selector which is also the default
selector used when sending messages with **no selector**.

### Receivers

In programming languages based on message-passing like Smalltalk and Objective-C invoking a method is done by sending a message to a receiver. This is conceptually equivalent to invoking a method on an instance in C# where both these statements are roughly equivalent:

```objc
// Objective-C
[receiver method:argument]
```

```csharp
// C#
receiver.method(argument)
```

Support for receivers is available in the following format:

```
{receiver}.{target} {msg}
```

### Registering Receivers

Registering a receiver can be done with a map of the object instance and the name you want it to be exported as. E.g. we can add a "css" receiver to handle with:

```java
ServerEventsClient client = new AndroidServerEventsClient(baseUrl, "home")
    .registerNamedReceiver("css", CssReceiver.class)
    .setResolver(new MyResolver(mainActivity))
    .start();

public class CssReceiver extends ServerEventReceiver {
    private MainActivity parentActivity;
    public CssReceiver(MainActivity parentActivity) {
        this.parentActivity = parentActivity;
    }

    public void backgroundImage(String message){
        String url = message.startsWith("url(")
            ? message.substring(4, message.length() - 1)
            : message;

        App.get().readBitmap(url, bitmap -> {
            ImageView chatBackground = (ImageView)parentActivity.findViewById(R.id.chat_background);
            parentActivity.runOnUiThread(() -> chatBackground.setImageBitmap(bitmap));
        });
    }

    public void background(String message){
        String color = message.replace("#", "#AA");
        String cssSelector = super.getRequest().getCssSelector();
        parentActivity.runOnUiThread(() -> {
            if (Objects.equals(cssSelector, "#top")){
                parentActivity.getSupportActionBar().setBackgroundDrawable(
                    new ColorDrawable(colorVal)
                );
            }
        });
    }
}

public class MyResolver implements IResolver {
    private MainActivity parentActivity;
    public MyResolver(MainActivity parentActivity) {
        this.parentActivity = parentActivity;
    }

    @Override
    public Object TryResolve(Class cls){
        if (cls == CssReceiver.class){
            return new CssReceiver(this.parentActivity);
        }
        return cls.newInstance();
    }
}
```

Which will invoke `backgroundImage` method off a new instance of the `CssReceiver` class that's triggered with:

```
css.background-image url(https://bit.ly/1yIJOBH)
```

and can be sent to all subscriptions on the **home** channel in ServiceStack with:

```csharp
ServerEvents.NotifyChannel("home", "css.background-image", "url(https://bit.ly/1yIJOBH)");
```

This works the same with Global Receivers. 

### Inheriting ServerEventReceiver

By inheriting `ServerEventReceiver`:

```java
class ServerEventReceiver implements IReceiver {
    public client: ServerEventsClient;
    public request: ServerEventMessage;
    noSuchMethod(selector: string, message:any) {}
}
```

Receivers can access additional built-in functionality where it will allow receivers to access the 
`ServerEventsClient` client dependency, the `ServerEventMessage` that was received, it also lets you handle 
any unhandled messages sent by implementing `noSuchMethod()`, e.g:

```java
class JavaScriptReceiver extends ServerEventReceiver {

    public void chat(ChatMessage chatMessage){
        LogMessage request = new LogMessage()
            .setChannel(msg.getChannel())
            .setMessage(msg.getMessage());

        super.client.getServiceClient().post(request);
    }
    
    public void announce(String message){
        Toast.makeText(this.parentActivity, message, Toast.LENGTH_LONG);
    }

    public void toggle(){
        if ("#sidebar".equals(super.request.getCssSelector())){
            LinearLayout sidebarLayout=(LinearLayout)this.findViewById(R.id.sidebarLayout);
            sidebarLayout.setVisibility(sidebarLayout.getVisibility() == LinearLayout.INVISIBLE
                ? LinearLayout.VISIBLE
                : LinearLayout.INVISIBLE
            );
        }
    }

    public void noSuchMethod(String selector, Object message){
        ServerEventMessage msg = (ServerEventMessage)message;
        Log.d("Unhandled " + selector + " was sent message: " + msg.getJson());
    }
}

client.registerReceiver(JavaScriptReceiver.class); //register Global Receiver
```

These can triggered with:

```csharp
ServerEvents.NotifyChannel(channel, new ChatMessage { ... });
ServerEvents.NotifyChannel(channel, "cmd.announce", "Hello, World!");
ServerEvents.NotifyChannel(channel, "cmd.toggle$#sidebar");
ServerEvents.NotifyChannel(channel, "cmd.UnknownSelector", new Message { ... });
```

### Dependency Resolvers

You can control the lifetime of the receivers by injecting a custom resolver which will let you reuse the same
Receiver instance by using a `SingletonInstanceResolver`, e.g:

```java
ServerEventsClient client = new AndroidServerEventsClient(baseUrl, "home")
    .setResolver(new SingletonInstanceResolver())
    .registerReceiver(JavaScriptReceiver.class)
    .start();
```

Which is implemented with:

```java
public class SingletonInstanceResolver implements IResolver {
    ConcurrentMap<Class, Object> cache = new ConcurrentHashMap<>();
    @Override
    public Object TryResolve(Class cls) {
        Object instance = cache.get(cls);
        if (instance == null){
            try {
                Object newInstance = cls.newInstance();
                instance = (instance = cache.putIfAbsent(cls, newInstance)) == null
                        ? newInstance
                        : instance;
            } catch (Exception e) {
                throw new RuntimeException(e);
            }
        }
        return instance;
    }
}
```

Custom Resolvers are also useful configuring the dependencies in your Receiver classes, e.g. we use this 
above to inject our `MainActivity` into our `CssReceiver` class.

```java
ServerEventsClient client = new AndroidServerEventsClient(baseUrl, "home")
    .setResolver(new MyResolver())
    .registerReceiver(CssReceiver.class)
    .start();

public class MyResolver implements IResolver {
    private MainActivity parentActivity;
    public MyResolver(MainActivity parentActivity) {
        this.parentActivity = parentActivity;
    }

    @Override
    public Object TryResolve(Class cls){
        if (cls == CssReceiver.class){
            return new CssReceiver(this.parentActivity);
        }
        return cls.newInstance();
    }
}
```

### Event Triggers

Triggers enable a pub/sub event model where multiple listeners can subscribe and be notified of an event.

Registering an event handler can be done at anytime using the `addListener()` API, e.g:

```java
Action<ServerEventMessage> handler = e -> {
    Log.d("received event " + e.getTarget() + " with arg: " + e.getJson());
};

ServerEventsClient client = new AndroidServerEventsClient(baseUrl, "home")
    .addListener("customEvent", handler)
    .start();

//Register another listener to 'customEvent' event
List<ServerEventMessage> msgs1 = new ArrayList<>();
client.addListener("customEvent", msgs1::add);
```

The selector to trigger this custom event is:

```
trigger.customEvent arg
trigger.customEvent {json}
```

Which can be sent in ServiceStack with a simple or complex type argument, e.g:

```csharp
ServerEvents.NotifyChannel(channel, "trigger.customEvent", "arg");
ServerEvents.NotifyChannel(channel, "trigger.customEvent", new ChatMessage { ... });
```

#### Removing Listeners

Use `removeListener()` to stop listening for an event, e.g:

```java
//Remove first event listener
client.removeListener("customEvent", handler);
```

### Channel Subscriber APIs

You can use any of the APIs below to update an active Subscriptions Channels:

```java
client.subscribeToChannels("chan3","chan4");
client.unsubscribeFromChannels("chan1","chan2");

//Alternatively subscribe/unsubscribe to channels in the same request with:
UpdateEventSubscriber request = new UpdateEventSubscriber()
    .setSubscribeChannels(Func.toList("chan3","chan4"))
    .setUnsubscribeChannels(Func.toList("chan1","chan2"));

client.updateSubscriber(request);
```

All Service Client APIs in `AndroidServiceClient` also have non-blocking versions with an an `Async` suffix
that utilize Android's Async Task and optional callbacks for performing non-blocking Service Client requests, e.g:

```java
client.updateSubscriberAsync(request, () -> {
    Log.d("SUCCESS!");
}, e -> {
    Log.d("FAILED: " + e.toString());
});
```

### Get Channel Subscribers

Once connected, you can get a list of channel subscribers the `ServerEventsClient` is currently connected
to with:

```java
List<ServerEventUser> channelUsers = client.getChannelSubscribers();
Func.each(channelUsers, user -> {
    Log.d(user.getUserId() + " @" + user.getDisplayName() + " " + user.getProfileUrl());
});
```

### Accessing ServiceClient

Alternatively you can access the channel subscribers using the built-in `JsonServiceClient`, e.g:

```java
client.getServiceClient().get(new GetEventSubscribers()
    .setChannels(Func.toList("chan1","chan2")));
```

Which you can also use to call your own Services:

```java
client.getServiceClient().post(new MyRequest());
```

### Integration Test Examples

More examples of `ServerEventClient` usage can be found in the Test Suites below:

 - [Java 8 / JVM Integration Tests](https://github.com/ServiceStack/ServiceStack.Java/blob/master/src/AndroidClient/client/src/test/java/net/servicestack/client/ServerEventClientTests.java)

 - [Java 7 / Android Integration Tests](https://github.com/ServiceStack/ServiceStack.Java/blob/master/src/AndroidClient/android/src/androidTest/java/net/servicestack/android/ServerEventClientTests.java)

# Java ServerEvents Examples

## [Android Java Chat](https://github.com/ServiceStackApps/AndroidJavaChat)

Java Chat client utilizing [Server Events](/java-server-events-client) for real-time notifications and enabling seamless OAuth Sign In's using Facebook, Twitter and Google's native SDKs:

[![](/img/pages/java/java-android-chat-screenshot-540x960.png)](https://github.com/ServiceStackApps/AndroidJavaChat)


# JavaScript Server Events Client
Source: https://docs.servicestack.net/javascript-server-events-client

Like ServiceStack's other JavaScript interop libraries, the client bindings for ServiceStack's Server Events is in ServiceStack's JavaScript client bindings [/js/ss-utils.js](https://github.com/ServiceStack/ServiceStack/blob/master/src/ServiceStack/js/ss-utils.js) that's embedded in `ServiceStack.dll` and available from any page with:

```html
<script src="/js/ss-utils.js"></script>
```

To configure Server Sent Events on the client create a [native EventSource object](http://www.html5rocks.com/en/tutorials/eventsource/basics/) with:

```javascript
var source = new EventSource(
    '/event-stream?channel=channel&t=' + new Date().getTime());
```

::: info
The default url `/event-stream` can be modified with `ServerEventsFeature.StreamPath`
:::

As this is the native `EventSource` object, you can interact with it directly, e.g. you can add custom error handlers with:

```javascript
source.addEventListener('error', function (e) { 
        console.log("ERROR!", e); 
    }, false);
```

The ServiceStack binding itself is just a thin jQuery plugin that extends `EventSource`, e.g:

```javascript
$(source).handleServerEvents({
    handlers: {
        onConnect: function (sub) {
            console.log("You've connected! welcome " + sub.displayName);
        },
        onJoin: function (user) {
            console.log("Welcome, " + user.displayName);
        },
        onLeave: function (user) {
            console.log(user.displayName + " has left the building");
        },        
        onMessage: function (msg, e) { // fired after every message
            console.log(msg);
        },
        //... Register custom handlers
    },
    receivers: { 
        //... Register any receivers
    },
});
```

ServiceStack Server Events has 4 built-in events sent during a subscriptions life-cycle: 

 - **onConnect** - sent when successfully connected, includes the subscriptions private `subscriptionId` as well as heartbeat and unregister urls that's used to automatically setup periodic heartbeats.
 - **onJoin** - sent when a new user joins the channel.
 - **onLeave** - sent when a user leaves the channel.
 - **onUpdate** - sent when a users channels subscription was updated

::: info
The onJoin/onLeave/onUpdate events can be turned off with `ServerEventsFeature.NotifyChannelOfSubscriptions=false`
:::

All other messages can be handled with the catch-all:

 - **onMessage** - fired when any other message is sent

## Selectors

A selector is a string that identifies what should handle the message, it's used by the client to route the message to different handlers. The client bindings in [/js/ss-utils.js](https://github.com/ServiceStack/EmailContacts/#servicestack-javascript-utils---jsss-utilsjs) supports 4 different handlers out of the box:

### Global Event Handlers

To recap [Declarative Events](https://github.com/ServiceStackApps/EmailContacts#declarative-events) allow you to define global handlers on a html page which can easily be applied on any element by decorating it with `data-{event}='{handler}'` attribute, eliminating the need to do manual bookkeeping of DOM events. 

The example below first invokes the `paintGreen` handler when the button is clicked and fires the `paintRed` handler when the button loses focus:

```javascript
$(document).bindHandlers({
    paintGreen: function(){
        $(this).css("background","green");
    }, 
    paintRed: function(){
        $(this).css("background","red");
    }, 
});
```

```html
<button id="btnPaint" data-click="paintGreen" data-focusout="paintRed">
    Paint Town
</button>
```

The selector to invoke a global event handler is:

```
cmd.{handler}
```

Where `{handler}` is the name of the handler you want to invoke, e.g `cmd.paintGreen`. When invoked from a server event the message (deserialized from JSON) is the first argument, the Server Sent DOM Event is the 2nd argument and `this` by default is assigned to `document.body`.

```javascript
function paintGreen(msg /* JSON object msg */, e /*SSE Event*/){
    this // HTML Element or document.body
    $(this).css("background","green");
},
```


#### Handling Messages with the Default Selector

All `IServerEvents` Notify API's includes [overloads for sending messages without a selector](https://github.com/ServiceStack/ServiceStack/blob/master/src/ServiceStack/ServerEventsFeature.cs#L743-L771) that by convention will take the format `cmd.{TypeName}`. 

As they're prefixed with `cmd.*` these events can be handled with a handler **based on Message type name**, e.g:

```javascript
$(source).handleServerEvents({
    handlers: {
        CustomType: function (msg, e) { ... },
        SetterType: function (msg, e) { ... }
    },
});
```

Which will be called when messages are sent without a selector, e.g:

```csharp
public class MyServices : Service
{
    public IServerEvents ServerEvents { get; set; }

    public void Any(Request request)
    {
        ServerEvents.NotifyChannel("home", new CustomType { ... });
        ServerEvents.NotifyChannel("home", new SetterType { ... });
    }
}
```

### Postfix jQuery selector 

All server event handler options also support a postfix jQuery selector for specifying what each handler should be bound to with a `$` followed by the jQuery selector, e.g:

```
cmd.{handler}${jQuerySelector}
```

A concrete example for calling the above API would be:

```
cmd.paintGreen$#btnPaint
```

Which will bind `this` to the `#btnSubmit` HTML Element, retaining the same behavior as if it were called with `data-click="paintGreen"`.

::: info
Spaces in jQuery selectors need to be encoded with `%20`
:::

### Modifying CSS via jQuery

As it's a popular use-case Server Events also has native support for modifying CSS properties with:

```
css.{propertyName}${jQuerySelector} {propertyValue}
```

Where the message is the property value, which roughly translates to:

```js
$({jQuerySelector}).css({propertyName}, {propertyValue})
```

When no jQuery selector is specified it falls back to `document.body` by default.

```
/css.background #eceff1
```

Some other examples include:

```
/css.background$#top #673ab7   // $('#top').css('background','#673ab7')
/css.font$li bold 12px verdana // $('li').css('font','bold 12px verdana')
/css.visibility$a,img hidden   // $('a,img').css('visibility','#673ab7')
/css.visibility$a%20img hidden // $('a img').css('visibility','hidden')
```

### jQuery Events

A popular approach in building loosely-coupled applications is to have components interact with each other by raising events. It's similar to channels in Pub/Sub where interested parties can receive and process custom events on components they're listening on. jQuery supports this model by simulating DOM events that can be raised with [$.trigger()](http://api.jquery.com/trigger/). 

You can subscribe to custom events in the same way as normal DOM events, e.g:

```javascript
$(document).on('customEvent', function(event, arg, msgEvent){
    var target = event.target;
});
```

The selector to trigger this event is:

```
trigger.customEvent arg
trigger.customEvent$#btnPaint arg
```

Where if no jQuery selector is specified it defaults to `document`. These selectors are equivalent to:

```javascript
$(document).trigger('customEvent', 'arg')
$("#btnPaint").trigger('customEvent', 'arg')
```

### Receivers

In programming languages based on message-passing like Smalltalk and Objective-C invoking a method is done by sending a message to a receiver. This is conceptually equivalent to invoking a method on an instance in C# where both these statements are roughly equivalent:

```objc
// Objective-C
[receiver method:argument]
```

```csharp
// C#
receiver.method(argument)
```

Support for receivers is available in the following format:

```
{receiver}.{target} {msg}
```

### Registering Receivers

Registering a receiver can be either be done by adding it to the global `$.ss.eventReceivers` map with the object instance and the name you want it to be exported as. E.g. The `window` and `document` global objects can be setup to receive messages with:

```javascript
$.ss.eventReceivers = { 
    "window": window, 
    "document": document 
};
```

Once registered you can set any property or call any method on a receiver with:

```
document.title New Window Title
window.location http://google.com
```

Where if `{target}` was a function it will be invoked with the message, otherwise its property will be set.
By default when no `{jQuerySelector}` is defined, `this` is bound to the **receiver** instance.

The alternative way to register a receiver is at registration with:

```javascript
$(source).handleServerEvents({
  ...
  receivers: {
    tv: {
      watch: function (id) {
        if (id.indexOf('youtu.be') >= 0) {
            var v = $.ss.splitOnLast(id, '/')[1];
            $("#tv").html(templates.youtube.replace("{id}", v)).show();
        } else {
            $("#tv").html(templates.generic.replace("{id}", id)).show();
        }
      },
      off: function () {
        $("#tv").hide().html("");
      }
   }
}
});
```

This registers a custom `tv` receiver that can now be called with:

```
tv.watch http://youtu.be/518XP8prwZo
tv.watch https://servicestack.net/img/logo-220.png
tv.off
```

### Un Registering a Receiver

As receivers are maintained in a simple map, they can be disabled at anytime with:

```javascript
$.ss.eventReceivers["window"] = null; 
```

and re-enabled with:

```javascript
$.ss.eventReceivers["window"] = window;
```

Whilst Named Receivers are used to handle messages sent to a specific namespaced selector, the client also supports registering a **Global Receiver** for handling messages sent with the special `cmd.*` selector.

### UpdateSubscriber APIs

You can use any of the APIs below in the
[ss-utils JavaScript library](/ss-utils-js)
to update an active Subscriptions Channels:

```javascript
$.ss.updateSubscriber({ 
    SubscribeChannels: "chan1,chan2",
    UnsubscribeChannels: "chan3,chan4"
});

$.ss.subscribeToChannels(["chan1","chan2"], response => ..., error => ...);
$.ss.unsubscribeFromChannels(["chan3","chan4"], response => ..., error => ...);
```


# ServerEvent JavaScript Examples

## [Gistlyn](https://github.com/ServiceStack/Gistlyn)

Gistlyn is a C# Gist IDE for creating, running and sharing stand-alone, executable C# snippets.

[![](https://raw.githubusercontent.com/ServiceStack/Assets/master/img/livedemos/gistlyn/home-screenshot.png)](http://gistlyn.com)

> Live Demo: http://gistlyn.com

## [React Chat](https://github.com/ServiceStackApps/ReactChat)

React Chat is a port of [ServiceStack Chat](https://github.com/ServiceStackApps/Chat) ES5, jQuery Server Events 
demo into a [TypeScript](http://www.typescriptlang.org/), [React](http://facebook.github.io/react/) and 
[Redux](https://github.com/reactjs/redux) App:

![](https://raw.githubusercontent.com/ServiceStack/Assets/master/img/livedemos/chat-react/screenshot.png)

## [Networked Time Traveller Shape Creator](https://github.com/ServiceStackApps/typescript-redux#example-9---real-time-networked-time-traveller)

A network-enhanced version of the
[stand-alone Time Traveller Shape Creator](https://github.com/ServiceStackApps/typescript-redux#example-8---time-travelling-using-state-snapshots)
that allows users to **connect to** and **watch** other users using the App in real-time similar 
to how users can use Remote Desktop to watch another computer's screen: 

![](https://raw.githubusercontent.com/ServiceStack/Assets/master/img/livedemos/redux-chrome-safari.png)

> Live demo: http://redux.servicestack.net

## [Chat](https://github.com/ServiceStackApps/Chat)

> Feature-rich Single Page Chat App, showcasing Server Events support in 170 lines of JavaScript!

[![](https://raw.githubusercontent.com/ServiceStack/Assets/master/img/livedemos/chat.png)](http://chat.netcore.io)

## [React Chat Desktop](https://github.com/ServiceStackApps/ReactChatApps)

> Built with [React Desktop Apps](https://github.com/ServiceStackApps/ReactDesktopApps)
VS.NET template and packaged into a native Desktop App for Windows and OSX - showcasing synchronized 
real-time control of multiple Windows Apps:

[![](https://raw.githubusercontent.com/ServiceStack/Assets/master/img/livedemos/react-desktop-apps/dancing-windows.png)](https://youtu.be/-9kVqdPbqOM)

> Downloads for [Windows, OSX, Linux and Web](https://github.com/ServiceStackApps/ReactChatApps#downloads)


# gRPC Server Events
Source: https://docs.servicestack.net/server-events-grpc

## Server Stream gRPC Services

In addition to standard Services which gRPC Refers to as **Unary RPC**, i.e. where clients sends a single request to the server and 
gets a single response back. Another very useful communication style supported by gRPC is **Server streaming**:

::: info
the client sends a request to the server and gets a stream to read a sequence of messages back. The client reads from the returned stream 
until there are no more messages. gRPC guarantees message ordering within an individual RPC call
:::

### StreamServerEvents

This communication channel is especially useful in [Server Events](/server-events) which operates in a similar style with clients connecting to 
a long-lived HTTP connection that streams back "real-time Events" over the light and efficient 
[SSE](https://www.html5rocks.com/en/tutorials/eventsource/basics/) standard natively supported in modern browsers.

Although as HTTP Requests are not normally used for maintaining long-lived connections they're susceptible to issues like buffering 
from App Servers, middleware and proxies and require implementing a bespoke health-check and auto-reconnect solution in order to maintain
interrupted service.

As a first class supported communication channel clients can instead leverage gRPC's library infrastructure which is perfectly suited for
streaming real-time Server Events over an efficient persistent HTTP/2 channel that's available from the `StreamServerEvents` gRPC Service:

```proto
rpc ServerStreamServerEvents(StreamServerEvents) returns (stream StreamServerEventsResponse) {}
```

Which gives all `protoc` supported languages a Typed Client for consuming your [Server Events](/server-events).

### GrpcServiceClient Streams

When using the generic `GrpcServiceClient` you're able to take advantage of C#'s 8 new `await foreach` syntax sugar for consuming gRPC Server Streams.

Its usage is analogous to all Server Events clients where your initial connection contains the channels you want to subscribe to receive notifications
from, e.g:

```csharp
var stream = client.StreamAsync(new StreamServerEvents {
    Channels = new[] { "todos" }
});
```

Then you can use `await foreach` to consume an endless stream of Server Events. Use `Selector` to identify the type of Server Event
whilst the complex-type body of each event message can be parsed from its JSON body, e.g:

```csharp
await foreach (var msg in stream)
{
    if (msg.Selector.StartsWith("todos.")) //custom todos.* events
    {
        var obj = JSON.parse(msg.Json); //body of message in JSON
        if (obj is Dictionary<string, object> map)
        {
            //todos.create + todos.update properties
            var id = map["id"];
            var title = map["title"];
            $"EVENT {msg.Selector} [{msg.Channel}]: #{id} {title}".Print(); 
        }
        else
        {
            //todos.delete id
            $"EVENT {msg.Selector} [{msg.Channel}]: {obj}".Print();
        }
    }
    else
    {
        // general server events, e.g cmd.onConnect, cmd.onJoin, cmd.onLeave
        $"EVENT {msg.Selector} [{msg.Channel}]: #{msg.UserId} {msg.DisplayName}".Print();
    }
}
```

If connected whilst running the [TodoWorld CRUD Example](https://todoworld.servicestack.net/#user-content-c-local-development-grpc-ssl-crud-example)
this stream will output something similar to:

```
EVENT cmd.onConnect []: #-1 user1
EVENT cmd.onJoin [todos]: #-1 user1
EVENT todos.create [todos]: #1 ServiceStack
EVENT todos.update [todos]: #1 gRPC
EVENT todos.delete [todos]: 1
```

### protoc Dart Streams

Other `protoc` languages will require using their own language constructs for consuming gRPC Streams,
here's the [example for Dart](https://todoworld.servicestack.net/#dart) that also has a pleasant API for consuming Server Streams:

```dart
var stream = client.serverStreamServerEvents(StreamServerEvents()..channels.add('todos'));
await for (var r in stream) {
    var obj = jsonDecode(r.json);
    if (r.selector.startsWith('todos')) {
        if (obj is Map) {
            print('EVENT ${r.selector} [${r.channel}]: #${obj['id']} ${obj['title']}');
        } else {
            print('EVENT ${r.selector} [${r.channel}]: ${obj}');
        }
    } else {
        print('EVENT ${r.selector} ${r.channels}: #${obj['userId']} ${obj['displayName']}');
    }
}
```


# Redis ServerEvents
Source: https://docs.servicestack.net/redis-server-events

One limitation the default `MemoryServerEvents` implementation has is being limited for use within a single App Server where all client connections are maintained. This is no longer a limitation with the new **Redis ServerEvents back-end** which utilizes a distributed redis-server back-end to provide a scale-out option capable of serving fan-out/load-balanced App Servers. If you're familiar with SignalR, this is akin to [SignalR's scaleout with Redis back-end](http://www.asp.net/signalr/overview/signalr-20/performance-and-scaling/scaleout-with-redis).

`RedisServerEvents` is a drop-in replacement for the built-in `MemoryServerEvents` that's effectively a transparent implementation detail, invisible to Server or Client API's where both implementations even [share the same integration Tests](https://github.com/ServiceStack/ServiceStack/blob/b9eb34eb80ff64fa1171d2f7f29ef359c3580eed/tests/ServiceStack.WebHost.Endpoints.Tests/ServerEventTests.cs#L169-L189).

![Redis ServerEvents Scale Out](https://raw.githubusercontent.com/ServiceStack/Assets/master/img/gap/Chat/redis-scaleout.png)

## Enable Redis ServerEvents

As a drop-in replacement it can easily be configured with just a few lines of code, as seen in the updated Chat App which can run on either [Memory or Redis ServerEvents providers](https://github.com/ServiceStackApps/Chat/blob/326617e88272d7cc0a8b7513272cf055378957e2/src/Chat/Global.asax.cs#L46-L54):

```csharp
var redisHost = AppSettings.GetString("RedisHost");
if (redisHost != null)
{
    container.Register<IRedisClientsManager>(
        new RedisManagerPool(redisHost));

    container.Register<IServerEvents>(c => 
        new RedisServerEvents(c.Resolve<IRedisClientsManager>()));
    
    container.Resolve<IServerEvents>().Start();
}
```

The above configuration will use Redis ServerEvents if there's a `RedisHost` **appSetting** in Chat's [Web.config](https://github.com/ServiceStackApps/Chat/blob/326617e88272d7cc0a8b7513272cf055378957e2/src/Chat/Web.config#L21):

```xml
<add key="RedisHost" value="localhost:6379" />
```

RedisServerEvents is in the [ServiceStack.Server](http://www.nuget.org/packages/ServiceStack.Server) NuGet Package:

:::copy
`<PackageReference Include="ServiceStack.Redis" Version="8.*" />`
:::

### Cross-platform Memory and Redis ServerEvent Enabled Chat.exe

To showcase Redis ServerEvents in action, we've prepared a stand-alone [ServiceStack.Gap](https://github.com/ServiceStack/ServiceStack.Gap) version of [Chat](http://chat.netcore.io) compiled down into a single **Chat.exe** that can run on either Windows and OSX with Mono which can be downloaded from: 

### [Chat.zip](https://github.com/ServiceStack/ServiceStack.Gap/raw/master/deploy/Chat.zip) (1.2MB)

[![Redis ServerEvents Preview](https://raw.githubusercontent.com/ServiceStack/Assets/master/img/release-notes/redis-server-events.gif)](https://github.com/ServiceStack/ServiceStack.Gap/raw/master/deploy/Chat.zip)

### Redis ServerEvents Chat Usage

Running **Chat.exe** without any arguments will run Chat using the default **Memory ServerEvents**. This can be changed to use **Redis ServerEvents** by [un-commenting this line in appsettings.txt](https://github.com/ServiceStack/ServiceStack.Gap/blob/master/src/Chat/Chat/appsettings.txt#L5):

```
#redis localhost
```

This will require a **redis-server** running on `localhost`. If you don't have redis yet, [download redis-server for Windows](https://github.com/ServiceStack/redis-windows).

Alternatively you can specify which **port** to run Chat on and change it to use Redis ServerEvents by specifying the **redis** instance it should connect to on the command-line with:

```
Chat.exe /port=1337 /redis=localhost
```

Also included in `Chat.zip` are [test-fanout-redis-events.bat](https://github.com/ServiceStack/ServiceStack.Gap/blob/master/src/Chat/build/test-fanout-redis-events.bat) and equivalent [test-fanout-redis-events.sh](https://github.com/ServiceStack/ServiceStack.Gap/blob/master/src/Chat/build/test-fanout-redis-events.sh) helper scripts for **spawning multiple versions of Chat.exe** on different ports (and backgrounds) for **Windows or OSX**, showing how multiple clients are able to send messages to each other via Redis whilst being subscribed to different HTTP Servers:

```
START Chat.exe /port=1337 /redis=localhost /background=/port-1337.jpg
START Chat.exe /port=2337 /redis=localhost /background=/port-2337.jpg
START Chat.exe /port=3337 /redis=localhost /background=/port-3337.jpg
```

This script was used to create the animated gif above to launch **3 self-hosting instances of Chat.exe** running on **different ports**, all connected to each other via Redis. This enables some interesting peer-to-peer scenarios where users are able to run a network of (CPU/resource isolated) decentralized stand-alone HTTP Servers on their local machines, but can still communicate with each other via redis.


# Background Jobs
Source: https://docs.servicestack.net/background-jobs

ServiceStack.Jobs is our solution for queueing and managing background jobs and scheduled tasks in .NET 8 Apps. It's a easy to use library that seamlessly integrates into existing ServiceStack Apps with a built-in Management UI to provide real-time monitoring, inspection and management of background jobs.

:::youtube 2Cza_a_rrjA
Durable Background Jobs and Scheduled Tasks for .NET 8 Apps
:::

### Durable and Infrastructure-Free

Prior to Background Jobs we've been using [Background MQ](/background-mq) for executing
our background tasks which lets you queue any Request DTO to execute its API in a background worker.
It's been our preferred choice as it didn't require any infrastructure dependencies since its concurrent
queues are maintained in memory, this also meant they were non-durable that didn't survive across App restarts. 
Whilst [ServiceStack MQ](/messaging) enables an additional endpoint for your APIs our main use-case for using 
it was for executing background tasks which would be better suited by purpose-specific software 
designed for the task.

#### SQLite Persistence

It uses SQLite as the backing store for its durability since it's low latency, 
[fast disk persistence](https://www.sqlite.org/fasterthanfs.html) and embeddable file-based 
database makes it ideally suited for the task which allows creation of naturally partition-able 
and archivable monthly databases on-the-fly without any maintenance overhead or infrastructure 
dependencies making it easy to add to any .NET App without impacting or adding increased load to 
their existing configured databases.

### Queue APIs or Commands

For even greater reuse you're able to queue your existing ServiceStack APIs
as a Background Job in addition to [Commands](/commands) added in the 
[last v8.3 release](/releases/v8_03) for encapsulating units of logic
into internal invokable, inspectable and auto-retryable building blocks.

### Real Time Admin UI

The Background Jobs Admin UI provides a real time view into the status of all background jobs including 
their progress, completion times, Executed, Failed and Cancelled Jobs, etc. which is useful for monitoring 
and debugging purposes. 

![](/img/pages/jobs/jobs-dashboard.webp)

View Real-time progress of queued Jobs

![](/img/pages/jobs/jobs-queue.webp)

View real-time progress logs of executing Jobs

![](/img/pages/jobs/jobs-logs.webp)

View Job Summary and Monthly Databases of Completed and Failed Jobs

![](/img/pages/jobs/jobs-completed.webp)

View full state and execution history of each Job

![](/img/pages/jobs/jobs-failed.webp)

Cancel Running jobs and Requeue failed jobs

### Feature Overview

Despite being a v1 release it packs all the features we wanted to use in a Background Jobs solution including:

 - No infrastructure dependencies
   - Monthly archivable rolling Databases with full Job Execution History
 - Execute existing APIs or versatile Commands
   - Commands auto registered in IOC
 - Scheduled Reoccurring Tasks
   - Track Last Job Run
 - Serially execute jobs with the same named Worker
 - Queue Jobs dependent on successful completion of parent Job
 - Queue Jobs to be executed after a specified Date
 - Execute Jobs within the context of an Authenticated User
 - Auto retry failed jobs on a default or per-job limit
 - Timeout Jobs on a default or per-job limit
 - Cancellable Jobs
 - Requeue Failed Jobs
 - Execute custom callbacks on successful execution of Job
 - Maintain Status, Logs and Progress of Executing Jobs
 - Execute transitive (i.e. non-durable) jobs using named workers
 - Attach optional `Tag`, `BatchId`, `CreatedBy`, `ReplyTo` and `Args` with Jobs

Please [let us know](https://servicestack.net/ideas) if there are any other missing features
you would love to see implemented.

## Install

As it's more versatile and better suited, we've replaced the usage of Background MQ with
ServiceStack.Jobs in all **.NET 8 Identity Auth Templates** for sending Identity Auth Confirmation 
Emails when SMTP is enabled. So the easiest way to get started with ServiceStack.Jobs is to 
[create a new Identity Auth Project](https://servicestack.net/start), e.g:

:::sh
x new blazor-vue MyApp
:::

### Exiting .NET 8 Templates

Existing .NET 8 Projects can configure their app to use **ServiceStack.Jobs** by mixing in:

:::sh
x mix jobs
:::

Which adds the `Configure.BackgroundJobs.cs` [Modular Startup](https://docs.servicestack.net/modular-startup)
configuration and a **ServiceStack.Jobs** NuGet package reference to your project.

## Usage

Any API, Controller or Minimal API can execute jobs with the `IBackgroundJobs` dependency, e.g.
here's how you can run a background job to send a new email when an API is called in 
any new Identity Auth template:

```csharp
class MyService(IBackgroundJobs jobs) : Service 
{
    public object Any(MyOrder request)
    {
        var jobRef = jobs.EnqueueCommand<SendEmailCommand>(new SendEmail {
            To = "my@email.com",
            Subject = $"Received New Order {request.Id}",
            BodyText = $"""
                       Order Details:
                       {request.OrderDetails.DumptTable()}
                       """,
        });
        //...
    }
}
```

Which records and immediately executes a worker to execute the `SendEmailCommand` with the specified
`SendEmail` Request argument. It also returns a reference to a Job which can be used later to query
and track execution of a job.

Alternatively a `SendEmail` API could be executed with just the Request DTO: 

```csharp
var jobRef = jobs.EnqueueApi(new SendEmail {
    To = "my@email.com",
    Subject = $"Received New Order {request.Id}",
    BodyText = $"""
               Order Details:
               {request.OrderDetails.DumptTable()}
               """,
});
```

Although Sending Emails is typically not an API you want to make externally available and would 
want to either [Restrict access](/auth/restricting-services) or [limit usage to specified users](/auth/identity-auth#declarative-validation-attributes).

In both cases the `SendEmail` Request is persisted into the Jobs SQLite database for durability 
that gets updated as it progresses through the queue.

For execution the API or command is resolved from the IOC before being invoked with the Request.
APIs are executed via the [MQ Request Pipeline](/order-of-operations)
and commands executed using the [Commands Feature](/commands) where
it will be also visible in the [Commands Admin UI](/commands#command-admin-ui).

### Background Job Options

The behavior for each `Enqueue*` method for executing background jobs can be customized with 
the following options: 

 - `Worker` - Serially process job using a named worker thread 
 - `Callback` - Invoke another command with the result of a successful job 
 - `DependsOn` - Execute jobs after successful completion of a dependent job
   - If parent job fails all dependent jobs are cancelled
 - `UserId` - Execute within an Authenticated User Context
 - `RunAfter` - Queue jobs that are only run after a specified date
 - `RetryLimit` - Override default retry limit for how many attempts should be made to execute a job
 - `TimeoutSecs` - Override default timeout for how long a job should run before being cancelled
 - `RefId` - Allow clients to specify a unique Id (e.g Guid) to track job
 - `Tag` - Group related jobs under a user specified tag
 - `CreatedBy` - Optional field for capturing the owner of a job
 - `BatchId` - Group multiple jobs with the same Id
 - `ReplyTo` - Optional field for capturing where to send notification for completion of a Job
 - `Args` - Optional String Dictionary of Arguments that can be attached to a Job


### Executing non-durable jobs

`IBackgroundJobs` also supports `RunCommand` methods to be able to execute jobs transiently 
(i.e. non-durable), which is useful for commands that want to be serially executed by a named worker 
but don't need to be persisted.

You could use this to queue system emails to be sent by the same **smtp** worker and are happy to 
avoid tracking its state and execution history in the Jobs database.

```csharp
var job = jobs.RunCommand<SendEmailCommand>(new SendEmail { ... }, 
    new() {
        Worker = "smtp"
    });
```

In this case `RunCommand` returns the actual `BackgroundJob` instance that will be updated by 
the worker. 

You can also use `RunCommandAsync` if you prefer to wait until the job has been executed. Instead
of a Job it returns the **Result** of the command if it returned one. 

```csharp
var result = await jobs.RunCommandAsync<SendEmailCommand>(new SendEmail {...}, 
    new() {
        Worker = "smtp"
    });
```

### Serially Execute Jobs with named Workers

By default jobs are executed immediately in a new Task, we can also change the behavior to
instead execute jobs one-by-one in a serial queue by specifying them to use the same named 
worker as seen in the example above.

Alternatively you can annotate the command with the `[Worker]` attribute if you **always** want 
all jobs executing the command to use the same worker:

```csharp
[Worker("smtp")]
public class SendEmailCommand(IBackgroundJobs jobs) : SyncCommand<SendEmail>
{
    //...
}
```

### Use Callbacks to process the results of Commands

Callbacks can be used to extend the lifetime of a job to include processing a callback to process its results.
This is useful where you would like to reuse the the same command but handle the results differently,
e.g. the same command can email results or invoke a webhook by using a callback:

```csharp
jobs.EnqueueCommand<CheckUrlsCommand>(new CheckUrls { Urls = allUrls },
    new() {
        Callback = nameof(EmailUrlResultsCommand),
    });

jobs.EnqueueCommand<CheckUrlsCommand>(new CheckUrls { Urls = criticalUrls },
    new() {
        Callback = nameof(WebhookUrlResultsCommand),
        ReplyTo = callbackUrl
    });
```

Callbacks that fail are auto-retried the same number of times as their jobs, which if they all fail then 
the entire job is also marked as failed. 

### Run Job dependent on successful completion of parent

Jobs can be queued to only run after the successful completion of another job, this is useful 
for when you need to kick off multiple jobs after a long running task has finished like
generating monthly reports after monthly data has been aggregated, e.g: 

```csharp
var jobRef = jobs.EnqueueCommand<AggregateMonthlyDataCommand>(new Aggregate {
    Month = DateTime.UtcNow
});

jobs.EnqueueCommand<GenerateSalesReportCommand>(new () {
   DependsOn = jobRef.Id,
});

jobs.EnqueueCommand<GenerateExpenseReportCommand>(new () {
   DependsOn = jobRef.Id,
});
```

Inside your command you can get a reference to your current job with `Request.GetBackgroundJob()`
which will have its `ParentId` populated with the parent job Id and `job.ParentJob` containing
a reference to the completed Parent Job where you can access its Request, Results and other job 
information:

```csharp
public class GenerateSalesReportCommand(ILogger<MyCommandNoArgs> log) 
    : SyncCommand
{
    protected override void Run()
    {
        var job = Request.GetBackgroundJob();
        var parentJob = job.ParentJob;
    }
}
```

### Atomic Batching Behavior

We can also use `DependsOn` to implement atomic batching behavior where from inside our
executing command we can queue new jobs that are dependent on the successful execution
of the current job, e.g:

```csharp
public class CheckUrlsCommand(IHttpClientFactory factory, IBackgroundJobs jobs)
    : AsyncCommand<CheckUrls>
{
    protected override async Task RunAsync(CheckUrls req, CancellationToken ct)
    {
        var job = Request.GetBackgroundJob();

        var batchId = Guid.NewGuid().ToString("N");
        using var client = factory.CreateClient();
        foreach (var url in req.Urls)
        {
            var msg = new HttpRequestMessage(HttpMethod.Get, url);
            var response = await client.SendAsync(msg, ct);
            response.EnsureSuccessStatusCode();
      
            jobs.EnqueueCommand<SendEmailCommand>(new SendEmail {
                To = "my@email.com",
                Subject = $"{new Uri(url).Host} status",
                BodyText = $"{url} is up",
            }, new() {
                DependsOn = job.Id,
                BatchId = batchId,
            });
        }
    }
}
```

Where any dependent jobs are only executed if the job was successfully completed. 
If instead an exception was thrown during execution, the job will be failed and
all its dependent jobs cancelled and removed from the queue.

### Executing jobs with an Authorized User Context

If you have logic dependent on an Authenticated `ClaimsPrincipal` or ServiceStack
`IAuthSession` you can have your APIs and Commands also be executed with that user context
by specifying the `UserId` the job should be executed as:

```csharp
var openAiRequest = new CreateOpenAiChat {
   Request = new() {
       Model = "gpt-4",
       Messages = [
           new() {
               Content = request.Question
           }
       ]
   },
}; 

// Example executing API Job with User Context
jobs.EnqueueApi(openAiRequest, 
    new() {
      UserId = Request.GetClaimsPrincipal().GetUserId(),
      CreatedBy = Request.GetClaimsPrincipal().GetUserName(),
   });

// Example executing Command Job with User Context
jobs.EnqueueCommand<CreateOpenAiChatCommand>(openAiRequest, 
    new() {
      UserId = Request.GetClaimsPrincipal().GetUserId(),
      CreatedBy = Request.GetClaimsPrincipal().GetUserName(),
   });
```

Inside your API or Command you access the populated User `ClaimsPrincipal` or
ServiceStack `IAuthSession` using the same APIs that you'd use inside your ServiceStack APIs, e.g:

```csharp
public class CreateOpenAiChatCommand(IBackgroundJobs jobs) 
    : AsyncCommand<CreateOpenAiChat>
{
    protected override async Task RunAsync(
        CreateOpenAiChat request, CancellationToken token)
    {
        var user = Request.GetClaimsPrincipal();
        var session = Request.GetSession();
        //...
    }
}
```

### Queue Job to run after a specified date

Using `RunAfter` lets you queue jobs that are only executed after a specified `DateTime`, 
useful for executing resource intensive tasks at low traffic times, e.g: 

```csharp
var jobRef = jobs.EnqueueCommand<AggregateMonthlyDataCommand>(new Aggregate {
       Month = DateTime.UtcNow
   }, 
   new() {
       RunAfter = DateTime.UtcNow.Date.AddDays(1)
   });
```

### Attach Metadata to Jobs

All above Background Job Options have an effect on when and how Jobs are executed.
There are also a number of properties that can be attached to a Job that can be useful
in background job processing despite not having any effect on how jobs are executed.

These properties can be accessed by commands or APIs executing the Job and are visible
and can be filtered in the Jobs Admin UI to help find and analyze executed jobs.

```csharp
var jobRef = jobs.EnqueueCommand<CreateOpenAiChatCommand>(openAiRequest, 
   new() {
      // Group related jobs under a common tag
      Tag = "ai",

      // A User-specified or system generated unique Id to track the job
      RefId = request.RefId,
      
      // Capture who created the job
      CreatedBy = Request.GetClaimsPrincipal().GetUserName(),
      
      // Link jobs together that are sent together in a batch
      BatchId = batchId,
      
      // Capture where to notify the completion of the job to
      ReplyTo = "https:example.org/callback",
      
      // Additional properties about the job that aren't in the Request  
      Args = new() {
          ["Additional"] = "Metadata"
      }
   });
```

### Querying a Job

A job can be queried by either it's auto-incrementing `Id` Primary Key or by a unique `RefId`
that can be user-specified.

```csharp
var jobResult = jobs.GetJob(jobRef.Id);

var jobResult = jobs.GetJobByRefId(jobRef.RefId);
```

At a minimum a `JobResult` will contain the Summary Information about a Job as well as the 
full information about a job depending on where it's located:

```csharp
class JobResult
{
    // Summary Metadata about a Job in the JobSummary Table 
    JobSummary Summary
    // Job that's still in the BackgroundJob Queue
    BackgroundJob? Queued
    // Full Job information in Monthly DB CompletedJob Table
    CompletedJob? Completed
    // Full Job information in Monthly DB FailedJob Table
    FailedJob? Failed
    // Helper to access full Job Information
    BackgroundJobBase? Job => Queued ?? Completed ?? Failed 
}
```

### Job Execution Limits

Default Retry and Timeout Limits can be configured on the Backgrounds Job plugin:

```csharp
services.AddPlugin(new BackgroundsJobFeature
{
   DefaultRetryLimit = 2,
   DefaultTimeout = TimeSpan.FromMinutes(10),
});
```

These limits are also overridable on a per-job basis, e.g: 

```csharp
var jobRef = jobs.EnqueueCommand<AggregateMonthlyDataCommand>(new Aggregate {
       Month = DateTime.UtcNow
   }, 
   new() {
      RetryLimit = 3,
      Timeout = TimeSpan.FromMinutes(30),
   });
```

### Logging, Cancellation an Status Updates

We'll use the command for checking multiple URLs to demonstrate some recommended patterns
and how to enlist different job processing features.

```csharp
public class CheckUrlsCommand(
    ILogger<CheckUrlsCommand> logger,
    IBackgroundJobs jobs,
    IHttpClientFactory clientFactory) : AsyncCommand<CheckUrls>
{
    protected override async Task RunAsync(CheckUrls req, CancellationToken ct)
    {
        // 1. Create Logger that Logs and maintains logging in Jobs DB
        var log = Request.CreateJobLogger(jobs,logger);

        // 2. Get Current Executing Job
        var job = Request.GetBackgroundJob();

        var result = new CheckUrlsResult {
            Statuses = new()
        };
        using var client = clientFactory.CreateClient();
        for (var i = 0; i < req.Urls.Count; i++)
        {
            // 3. Stop processing Job if it's been cancelled 
            ct.ThrowIfCancellationRequested();

            var url = req.Urls[i];
            try
            {
                var msg = new HttpRequestMessage(HttpMethod.Get,url);
                var response = await client.SendAsync(msg, ct);

                result.Statuses[url] = response.IsSuccessStatusCode;
                log.LogInformation("{Url} is {Status}",
                    url, response.IsSuccessStatusCode ? "up" : "down");

                // 4. Optional: Maintain explicit progress and status updates
                log.UpdateStatus(i/(double)req.Urls.Count,$"Checked {i} URLs");
            }
            catch (Exception e)
            {
                log.LogError(e, "Error checking {Url}", url);
                result.Statuses[url] = false;
            }
        }

        // 5. Send Results to WebHook Callback if specified
        if (job.ReplyTo != null)
        {
            jobs.EnqueueCommand<NotifyCheckUrlsCommand>(result,
                new() {
                    ParentId = job.Id,
                    ReplyTo = job.ReplyTo,
                });
        }
    }
}
```

We'll cover some of the notable parts useful when executing Jobs:

#### 1. Job Logger

We can use a Job logger to enable database logging that can be monitored in real-time in the 
Admin Jobs UI. Creating it with both `BackgroundJobs` and `ILogger` will return a combined 
logger that both Logs to standard output and to the Jobs database:

```csharp
var log = Request.CreateJobLogger(jobs,logger);
```

Or just use `Request.CreateJobLogger(jobs)` to only save logs to the database.

#### 2. Resolve Executing Job

If needed the currently executing job can be accessed with:

```csharp
var job = Request.GetBackgroundJob();
```

Where you'll be able to access all the metadata the jobs were created with including `ReplyTo`
and `Args`.

#### 3. Check if Job has been cancelled

To be able to cancel a long running job you'll need to periodically check if a Cancellation
has been requested and throw a `TaskCanceledException` if it has to short-circuit the command
which can be done with:

```csharp
ct.ThrowIfCancellationRequested();
```

You'll typically want to call this at the start of any loops to prevent it from doing any more work.

#### 4. Optionally record progress and status updates

By default Background Jobs looks at the last API or Command run and worker used to estimate 
the duration and progress for how long a running job will take.

If preferred your command can explicitly set a more precise progress and optional status update
that should be used instead, e.g:

```csharp
log.UpdateStatus(progress:i/(double)req.Urls.Count, $"Checked {i} URLs");
```

Although generally the estimated duration and live logs provide a good indication for the progress
of a job.

#### 5. Notify completion of Job

Calling a Web Hook is a good way to notify externally initiated job requests of the completion
of a job. You could invoke the callback within the command itself but there are a few benefits
to initiating another job to handle the callback:

 - Frees up the named worker immediately to process the next task
 - Callbacks are durable, auto-retried and their success recorded like any job
 - If a callback fails the entire command doesn't need to be re-run again

We can queue a callback with the result by passing through the `ReplyTo` and link it to the
existing job with:

```csharp
if (job.ReplyTo != null)
{
   jobs.EnqueueCommand<NotifyCheckUrlsCommand>(result,
       new() {
           ParentId = job.Id,
           ReplyTo = job.ReplyTo,
       });
}
```

Which we can implement by calling the `SendJsonCallbackAsync` extension method with the
Callback URL and the Result DTO it should be called with:

```csharp
public class NotifyCheckUrlsCommand(IHttpClientFactory clientFactory) 
    : AsyncCommand<CheckUrlsResult>
{
    protected override async Task RunAsync(
        CheckUrlsResult request, CancellationToken token)
    {
        await clientFactory.SendJsonCallbackAsync(
            Request.GetBackgroundJob().ReplyTo, request, token);
    }
}
```

#### Callback URLs

`ReplyTo` can be any URL which by default will have the result POST'ed back to the URL with a JSON
Content-Type. Typically URLs will contain a reference Id so external clients can correlate a callback
with the internal process that initiated the job. If the callback API is publicly available you'll
want to use an internal Id that can't be guessed (like a Guid) so the callback can't be spoofed, e.g:

`$"https://api.example.com/callback?refId={RefId}"`

If needed the callback URL can be customized on how the HTTP Request callback is sent.

If the URL contains a space, the text before the space is treated as the HTTP method:

`"PUT https://api.example.com/callback"`

If the auth part contains a colon `:` it's treated as Basic Auth:

`"username:password@https://api.example.com/callback"`

If name starts with `http.` sends a HTTP Header

`"http.X-API-Key:myApiKey@https://api.example.com/callback"`

Otherwise it's sent as a Bearer Token:

`"myToken123@https://api.example.com/callback"`

Bearer Token or HTTP Headers starting with `$` is substituted with Environment Variable if exists:

`"$API_TOKEN@https://api.example.com/callback"`

When needed headers, passwords and tokens can be URL encoded if they contain any delimiter characters.

## Implementing Commands

At a minimum a command need only implement the simple [IAsyncCommand interface](/commands#commands-feature): 

```csharp
public interface IAsyncCommand<in T>
{
    Task ExecuteAsync(T request);
}
```

Which is the singular interface that can execute any command.

However commands executed via Background Jobs have additional context your commands may need to 
access during execution, including the `BackgroundJob` itself, the `CancellationToken` and
an Authenticated User Context.

::include command-types.md::


# Schedule Recurring Tasks
Source: https://docs.servicestack.net/recurring-tasks

In addition to queueing jobs to run in the background, it also supports scheduling recurring tasks 
to execute APIs or Commands at fixed intervals.

:::youtube DtB8KaXXMCM
Schedule your Reoccurring Tasks with Background Jobs!
:::

APIs and Commands can be scheduled to run at either a `TimeSpan` or
[CRON Expression](https://github.com/HangfireIO/Cronos?tab=readme-ov-file#cron-format) interval, e.g:


## CRON Expression Examples

```csharp
// Every Minute Expression
jobs.RecurringCommand<CheckUrlsCommand>(Schedule.Cron("* * * * *"));

// Every Minute Constant
jobs.RecurringCommand<CheckUrlsCommand>(Schedule.EveryMinute, new CheckUrls {
    Urls = urls
});
```

### CRON Format

You can use any **unix-cron format** expression supported by the [HangfireIO/Cronos](https://github.com/HangfireIO/Cronos) library:

```txt
|------------------------------- Minute (0-59)
|     |------------------------- Hour (0-23)
|     |     |------------------- Day of the month (1-31)
|     |     |     |------------- Month (1-12; or JAN to DEC)
|     |     |     |     |------- Day of the week (0-6; or SUN to SAT; or 7 for Sunday)
|     |     |     |     |
|     |     |     |     |
*     *     *     *     *
```

The allowed formats for each field include:

| Field            | Format of valid values                     |
|------------------|--------------------------------------------|
| Minute           | 0-59                                       |
| Hour             | 0-23                                       |
| Day of the month | 1-31                                       |
| Month            | 1-12 (or JAN to DEC)                       |
| Day of the week  | 0-6 (or SUN to SAT; or 7 for Sunday)       |

### Matching all values

To match all values for a field, use the asterisk: `*`, e.g here are two examples in which the minute field is left unrestricted:

- `* 0 1 1 1` - the job runs every minute of the midnight hour on January 1st and Mondays.
- `* * * * *` - the job runs every minute (of every hour, of every day of the month, of every month, every day of the week, because each of these fields is unrestricted too).

### Matching a range

To match a range of values, specify your start and stop values, separated by a hyphen (-). Do not include spaces in the range. Ranges are inclusive. The first value must be less than the second.

The following equivalent examples run at midnight on Mondays, Tuesdays, Wednesdays, Thursdays, and Fridays (for all months):

- `0 0 * * 1-5`
- `0 0 * * MON-FRI`

### Matching a list

Lists can contain any valid value for the field, including ranges. Specify your values, separated by a comma (,). Do not include spaces in the list, e.g:

- `0 0,12 * * *` - the job runs at midnight and noon.
- `0-5,30-35 * * * *` - the job runs in each of the first five minutes of every half hour (at the top of the hour and at half past the hour).

## TimeSpan Interval Examples

```csharp
jobs.RecurringCommand<CheckUrlsCommand>(Schedule.Interval(TimeSpan.FromMinutes(1)));

// With Example
jobs.RecurringApi(Schedule.Interval(TimeSpan.FromMinutes(1)), new CheckUrls {
    Urls = urls
});
```

That can be registered with an optional **Task Name** and **Background Options**, e.g:

```csharp
jobs.RecurringCommand<CheckUrlsCommand>("Check URLs", Schedule.EveryMinute, 
   new() {
       RunCommand = true // don't persist job
   });
```

:::info
If no name is provided, the Command's Name or APIs Request DTO will be used
:::

## Idempotent Registration

Scheduled Tasks are idempotent where the same registration with the same name will
either create or update the scheduled task registration without losing track of the
last time the Recurring Task, as such it's recommended to always define your App's 
Scheduled Tasks on Startup:

```csharp
public class ConfigureBackgroundJobs : IHostingStartup
{
   public void Configure(IWebHostBuilder builder) => builder
     .ConfigureServices((context,services) => {
         services.AddPlugin(new CommandsFeature());
         services.AddPlugin(new BackgroundsJobFeature());
         services.AddHostedService<JobsHostedService>();
     }).ConfigureAppHost(afterAppHostInit: appHost => {
         var services = appHost.GetApplicationServices();

         var jobs = services.GetRequiredService<IBackgroundJobs>();
         
         // App's Scheduled Tasks Registrations:
         jobs.RecurringCommand<MyCommand>(Schedule.Hourly);
     });
}
```

## Background Jobs Admin UI

The last job the Recurring Task ran is also viewable in the Jobs Admin UI: 

![](/img/pages/jobs/jobs-scheduled-tasks-last-job.webp)


# Commands Feature
Source: https://docs.servicestack.net/commands

### Utilizing Commands to build more robust and observable systems

Much of ServiceStack has been focused on providing a productive [API First Development](/api-first-development) experience and adding value-added features around your System's external APIs.

### Internal API Implementation

Thus far little attention has been given to internal implementations of APIs since it can use anything that fulfils its 
service contract by returning the APIs populated Response DTO. 

How code-bases are structured is largely a matter of developer preference, however we believe we've also been able 
to add value in this area with the new appealing managed **Commands Feature**.

:::youtube SXPdBHbncPc
Use Commands to build robust and observable systems with Admin UI
:::

## Code Architecture 

Ultimately nothing beats the simplicity of "No Architecture" by maintaining all logic within a Service Implementation 
which just needs to call a few App dependencies to implement its functionality and return a populated Response DTO:

```csharp
public object Any(MyRequest request) => new MyResponse { ... };
```

This is still the best option for small implementations where the Service is the only consumer of the logic that should
be run on the HTTP Worker Request Thread.

#### When to restructure

Times when you may want to consider moving logic out of your Service into separate classes include:

- **Code Reuse**: Make it easier to reuse your Service logic in other Services
- **Complexity**: Break down complex logic into smaller more manageable pieces
- **Testability**: Make it easier to test your Logic in isolation
- **Observability**: Make it easier to log and monitor
- **Robustness**: Make it easier to handle, retry and recover from errors
- **Flexibility**: Make it easier to run in parallel or in a different managed thread

We'll look at how the new **Commands Feature** can help in these areas.

### Code Reuse

Following principles of YAGNI in doing the simplest thing that could possibly work, whenever we want to reuse logic
across Services we'd first start by moving it to an extension method on the dependency that it uses, e.g. 

```csharp
public static async Task<List<Contact>> GetActiveSubscribersAsync(
    this IDbConnection db, MailingList mailingList)
{        
    return await db.SelectAsync(db.From<Contact>(db.TableAlias("c"))
        .Where(x => x.DeletedDate == null && x.UnsubscribedDate == null && 
            x.VerifiedDate != null && (mailingList & x.MailingLists) == mailingList)
        .WhereNotExists(db.From<InvalidEmail>()
            .Where<Contact,InvalidEmail>((c,e) => 
                e.EmailLower == Sql.TableAlias(c.EmailLower, "c"))
            .Select(x => x.Id))
    );
}
```

Which does a great job at encapsulating logic and making it reusable and readable:

```csharp
foreach (var sub in await Db.GetActiveSubscribersAsync(MailingList.Newsletter)) {
    //...
}
```

Where it can be reused without referencing any external classes whilst also being easily discoverable via intelli-sense.    

This works great for 1 or 2 dependencies, but becomes more cumbersome as the number of dependencies grows, e.g: 

```csharp
public static async Task<List<Contact>> GetActiveSubscribersAsync(
    this IDbConnection db, ILogger log, ICacheClient cache, MailingList mailingList)
```

In which the complexity of the extension method dependencies leaks and impacts all calling classes that need to include
them and also starts to impact its readability, e.g:

```csharp
public class MyService(ILogger<MyService> log, ICacheClient cache, IDbConnection db) 
    : Service
{
    public object Any(MyRequest request)
    {
        var subs = await Db.GetActiveSubscribersAsync(log, cache, request.MailList);
    }
}
```

### Refactoring Logic into separate classes

The solution to this is to refactor the logic into a separate class and leverage the IOC to inject the dependencies it needs,
fortunately with Primary Constructors this now requires minimal boilerplate code, e.g:

```csharp
class MyLogic(ILogger<MyService> log, ICacheClient cache, IDbConnection db)
{
    //...
}
```

But it still requires manual registration adding additional complexity to 
your Host project `Program.cs` or [Modular Configurations](/modular-startup) which needs to 
manage registration for all these new logic classes, e.g: 

```csharp
builder.Services.AddTransient<MyLogic>();
```

## Commands Feature

Which touches on the first benefit of the **Commands Feature** which like ServiceStack Services auto registers
all classes implementing the intentionally simple and impl-free `IAsyncCommand` interface, e.g:

```csharp
public interface IAsyncCommand<in T>
{
    Task ExecuteAsync(T request);
}
```

Allowing for maximum flexibility in how to implement your logic classes, which are essentially encapsulated
units of logic with a single method to execute it, e.g:

```csharp
public class AddTodoCommand(ILogger<AddTodoCommand> log, IDbConnection db) 
    : IAsyncCommand<CreateTodo>
{
    public async Task ExecuteAsync(CreateTodo request)
    {
        var newTodo = request.ConvertTo<Todo>();
        newTodo.Id = await db.InsertAsync(newTodo, selectIdentity:true);
        log.LogDebug("Created Todo {Id}: {Text}", newTodo.Id, newTodo.Text);
    }
}
```

Where we immediately get the benefits of code reuse, encapsulation, and readability without needing to manually 
register and pollute your App's configuration with them.

By default Commands are registered as transient dependencies, but you can also register them with a different lifetime
scope using the `[Lifetime]` attribute, e.g:

```csharp
[Lifetime(Lifetime.Scoped)]
public class AddTodoCommand(ILogger<AddTodoCommand> log, IDbConnection db)
    : IAsyncCommand<CreateTodo> {}
```

Or by manually registering them, if you need a custom registration:

```csharp
services.AddTransient<AddTodoCommand>(c => CreateAddTodoCommand(c));
```

### Commands with Results

For maximum flexibility, we want to encourage temporal decoupling by separating initiating a command from its execution, 
so instead of adding a different method to execute commands with results, we're instead recommending the convention of
storing the result of a command in a `Result` property, e.g:

```csharp
public interface IAsyncCommand<in TRequest, out TResult> 
    : IAsyncCommand<TRequest>, IHasResult<TResult> { }

public interface IHasResult<out T>
{
    T Result { get; }
}
```

So we could implement a command with a result like:

```csharp
public class AddTodoCommand(ILogger<AddTodoCommand> log, IDbConnection db) 
    : IAsyncCommand<CreateTodo, Todo>
{
    public Todo Result { get; private set; }
    
    public async Task ExecuteAsync(CreateTodo request)
    {
        Result = request.ConvertTo<Todo>();
        Result.Id = await db.InsertAsync(newTodo, selectIdentity:true);
        log.LogDebug("Created Todo {Id}: {Text}", Result.Id, Result.Text);
    }
}
```

### Ergonomic Base Classes

Often you'll also need to make additional Request Context available to the command that's not apart of the
Command Request or registered from the IOC like an Authenticated User Context or `CancellationToken`.

::include command-types.md::


## Messaging Workflow

For greater resilience and scalability we recommend utilizing a messaging pattern to notify the outputs of a 
command by publishing messages to invoke dependent logic instead of returning a result, e.g:

### Background Jobs

```csharp
public class AddTodoCommand(IDbConnection db, IBackgroundJobs jobs) : SyncCommand<MyArgs>
{
    protected override void Run(MyArgs request)
    {
        var newTodo = request.ConvertTo<Todo>();
        newTodo.Id = db.Insert(newTodo, selectIdentity:true);
        
        // Non Durable Example
        jobs.RunCommand<SendNotificationCommand>(
            new SendNotification { TodoCreated = newTodo });

        // Durable Example
        jobs.EnqueueCommand<SendNotificationCommand>(
            new SendNotification { TodoCreated = newTodo });
    }
}
```

### Background MQ

```csharp
public class AddTodoCommand(IDbConnection db, IMessageProducer mq) : SyncCommand<MyArgs>
{
    protected override void Run(MyArgs request)
    {
        var newTodo = request.ConvertTo<Todo>();
        newTodo.Id = db.Insert(newTodo, selectIdentity:true);
        mq.Publish(new SendNotification { TodoCreated = newTodo });
    }
}
```

Which decouples the sender and receiver of the message, allowing it to finish without needing to wait and concern itself 
on how subsequent logic is processed, e.g. how to handle errors, whether to execute it in a different managed thread, in parallel, etc.

Messaging encourages adopting a more reliable asynchronous one-way workflow instead of implementing logic serially where 
the sender is timely coupled to the successful execution of all subsequent logic before being able to complete, e.g:

```csharp
await cmd.ExecuteAsync(createTodo);
var newTodo = cmd.Result;
await SendNewTodoNotificationAsync(newTodo);
```

It allows for more reliable and observable workflows that removes the temporal coupling between components where each 
execution step can be executed on different threads, independently monitored and retried if needed.

```txt
[A] -> [B] -> [C]
```

### Commands as Application Building Blocks

As they're not dependent on any framework and can support multiple execution patterns, we believe Commands make great 
building blocks for insulating units of logic as they're simple and testable and allow for managed execution which can 
easily add logging, monitoring, and resilience around your logic.

### Background Jobs or MQ

It should be noted adopting a messaging pattern doesn't require additional infrastructure complexity of an external MQ Server as you can use [Background Jobs](/background-jobs) or [Background MQ](/background-mq) to execute messages in managed background threads.

### Executing Commands

Commands are effectively a pattern to structure your logic that doesn't depend on any implementation assembly or 
framework, so they can just be executed directly, e.g:

```csharp
using var db = dbFactory.Open();
var cmd = new AddTodoCommand(new NullLogger<AddTodoCommand>(), db);
await cmd.ExecuteAsync(new CreateTodo { Text = "New Todo" });
```

### Command Executor

They also allow for a managed execution which the **CommandsFeature** provides with its `ICommandExecutor` which
can be executed like:

```csharp
public class MyService(ICommandExecutor executor) : Service
{
    public object Any(MyRequest request)
    {
        var cmd = executor.Command<AddTodoCommand>(); 
        await cmd.ExecuteAsync(new AddTodoCommand { Text = "New Todo" });
    }
}
```

This still results in the same behavior where exceptions are bubbled but also adds observability and resilience and
other niceties like executing any Fluent or Declarative Validation on Command Requests.

### Retry Failed Commands

We can make commands more resilient by adding the `[Retry]` attribute to opt into auto retrying failed commands:

```csharp
[Retry]
public class AddTodoCommand() : IAsyncCommand<CreateTodo> {}
```

Which will automatically retry the command as per the default Retry Policy:

```csharp
services.AddPlugin(new CommandsFeature
{
    DefaultRetryPolicy = new(
        Times: 3,
        Behavior: RetryBehavior.FullJitterBackoff,
        DelayMs: 100,
        MaxDelayMs: 60_000,
        DelayFirst: false
    )
});
```

That can be overridden on a per-command basis with the `[Retry]` attribute, e.g:

```csharp
[Retry(Times=4, MaxDelayMs=300_000, Behavior=RetryBehavior.LinearBackoff)]
public class AddTodoCommand() : IAsyncCommand<CreateTodo> {}
```

The different Retry Behaviors available include:

```csharp
public enum RetryBehavior
{
    // Use the default retry behavior
    Default,
    
    // Always retry the operation after the same delay
    Standard,
    
    // Should be retried with a linear backoff delay strategy
    LinearBackoff,

    // Should be retried with an exponential backoff strategy
    ExponentialBackoff,

    // Should be retried with a full jittered exponential backoff strategy
    FullJitterBackoff,
}
```

## Command Admin UI 

Which can be inspected in the new **Command Admin UI** where you can view summary stats of all executed Commands and **APIs** 
in the **Summary** tab, e.g:

[![](/img/pages/commands/AddTodoCommand-summary.png)](/img/pages/commands/AddTodoCommand-summary.png)

### Latest Command Executions

It also maintains a rolling log of the latest executed commands in the **Latest** tab:

[![](/img/pages/commands/AddTodoCommand-latest.png)](/img/pages/commands/AddTodoCommand-latest.png)

### Failed Command Executions

Whilst the **Errors** tab shows a list of all failed **Command** and **API** executions:

[![](/img/pages/commands/AddTodoCommand-errors.png)](/img/pages/commands/AddTodoCommand-errors.png)

### Execute Internal Commands

A benefit of using Commands as the building block for your internal logic is that they enjoy many of the same benefits
of ServiceStack's message-based Services where they can be invoked using just the Command **Name** and a **Request** Body
which allows them to be discovered and executed from the **Explore** Tab:

[![](/img/pages/commands/AddTodoCommand-execute.png)](/img/pages/commands/AddTodoCommand-execute.png)

In this way they can be treated like **Internal APIs** for being able to invoke internal functionality that's only accessible 
by **Admin** Users.

### Group Commands by Tag

Just like ServiceStack Services they can be grouped by **Tag** which can be used to group related commands: 

```csharp
[Tag("Todos")]
public class AddTodoCommand() : IAsyncCommand<CreateTodo> {}
```

## Execute Commands in Durable Background Jobs

In addition to being able to execute **Commands** with the `ICommandExecutor` or from the UI, they can also be executed as part of a [Durable Background Job](/background-jobs) where you'll be able to track and monitor 
their progress in real-time.

Background Jobs is already configured in all new [Identity Auth Templates](https://servicestack.net/start)
in order to send all Identity Auth Emails. Whilst existing Projects can enable it in their .NET 8 Apps with:

:::sh
x mix jobs
:::

Which adds a reference to the [ServiceStack.Jobs](https://www.nuget.org/packages/ServiceStack.Jobs) NuGet package
and includes the [Modular Startup](/modular-startup) configuration below:

```csharp
public class ConfigureBackgroundJobs : IHostingStartup
{
    public void Configure(IWebHostBuilder builder) => builder
        .ConfigureServices(services => {
            services.AddPlugin(new CommandsFeature());
            services.AddPlugin(new BackgroundsJobFeature());
            services.AddHostedService<JobsHostedService>();
         }).ConfigureAppHost(afterAppHostInit: appHost => {
            var services = appHost.GetApplicationServices();
            var jobs = services.GetRequiredService<IBackgroundJobs>();
            // Example of registering a Recurring Job to run Every Hour
            //jobs.RecurringCommand<MyCommand>(Schedule.Hourly);
        });
}

public class JobsHostedService(ILogger<JobsHostedService> log, IBackgroundJobs jobs) 
    : BackgroundService
{
    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
    {
        await jobs.StartAsync(stoppingToken);
        
        using var timer = new PeriodicTimer(TimeSpan.FromSeconds(3));
        while (!stoppingToken.IsCancellationRequested && 
            await timer.WaitForNextTickAsync(stoppingToken))
        {
            await jobs.TickAsync();
        }
    }
}
```

## Background MQ Integration

Although `CommandsFeature` is a standalone feature it can also be configured and used along with [Background MQ](/background-mq) which is a good option if you intend on adopting another [Message Queue Broker](/messaging) in
your App's in future.

```csharp
public class ConfigureMq : IHostingStartup
{
    public void Configure(IWebHostBuilder builder) => builder
        .ConfigureServices((context, services) => {
            services.AddSingleton<IMessageService>(c => new BackgroundMqService());
            services.AddPlugin(new CommandsFeature());
        })
        .ConfigureAppHost(afterAppHostInit: appHost => {
            var mqService = appHost.Resolve<IMessageService>();

            //Register ServiceStack APIs you want to be able to invoke via MQ
            mqService.RegisterHandler<SendEmail>(appHost.ExecuteMessage);
            mqService.Start();
        });
}
```

Despite being 2 independent features, they work well together as the Background MQ can be used to execute Commands in
managed background threads of which a single thread is used to execute each Request Type by default (configurable per request).

You'd typically want to use queues to improve scalability by reducing locking and concurrency contention of heavy resources by having requests queued and executed in a managed background thread where it's able to execute requests as fast as it can without contention. Queues are also a great solution for working around single thread limitations of resources like writes to SQLite databases.

## Use Case - SQLite Writes

As we've started to [use server-side SQLite databases](/ormlite/scalable-sqlite) for our new Apps given its [many benefits](/ormlite/litestream) we needed a solution to workaround its limitation of not being able to handle multiple writes concurrently.

One of the benefits of using SQLite is creating and managing [multiple databases](/ormlite/scalable-sqlite#multiple-sqlite-databases) is relatively cheap, so we can mitigate this limitation somewhat by maintaining different subsystems in separate databases, e.g:

[![](/img/pages/commands/pvq-databases.png)](/img/pages/commands/pvq-databases.png)

But each database can only be written to by a single thread at a time, which we can now easily facilitate with 
**Background Jobs** or **MQ Command DTOs**.

In all cases we recommend using [Sync DB APIs for SQLite](/ormlite/scalable-sqlite#always-use-synchronous-apis-for-sqlite) since their underlying implementation always blocks.

### Queuing DB Writes with SyncCommand Background Jobs

One way to remove contention is to serially execute DB Writes which we can do by executing DB Writes within `SyncCommand*` and using a named `[Worker(Workers.AppDb)]` attribute for Writes to the primary database, e.g: 

```csharp
[Worker(Workers.AppDb)]
public class DeleteCreativeCommand(IDbConnection db) 
    : SyncCommand<DeleteCreative>
{
    protected override void Run(DeleteCreative request)
    {
        var artifactIds = request.ArtifactIds;
        db.Delete<AlbumArtifact>(x => artifactIds.Contains(x.ArtifactId));
        db.Delete<ArtifactReport>(x => artifactIds.Contains(x.ArtifactId));
        db.Delete<ArtifactLike>(x => artifactIds.Contains(x.ArtifactId));
        db.Delete<Artifact>(x => x.CreativeId == request.Id);
        db.Delete<CreativeArtist>(x => x.CreativeId == request.Id);
        db.Delete<CreativeModifier>(x => x.CreativeId == request.Id);
        db.Delete<Creative>(x => x.Id == request.Id);
    }
}
```

Other databases should use its named connection for its named worker, e.g: 

```csharp
[Worker(Databases.Search)]
public class DeleteSearchCommand(IDbConnectionFactory dbFactory) 
    : SyncCommand<DeleteSearch>
{
    protected override void Run(DeleteSearch request)
    {
        using var db = dbFactory.Open(Databases.Search);
        db.DeleteById<ArtifactFts>(request.Id);
        //...
    }
}
```

Example of a DB Write command with result:

```csharp
[Worker(Databases.Albums)]
public class CreateAlbumCommand(IDbConnectionFactory dbFactory) 
    : SyncCommandWithResult<CreateAlbum,Album>
{
    protected override Album Run(CreateAlbum request)
    {
        using var db = dbFactory.Open(Databases.Albums);
        var album = request.ConvertTo<Album>();
        album.Id = db.Insert(album, selectIdentity:true);
        foreach (var artifact in request.Artifacts)
        {
            artifact.AlbumId = album.Id;
            db.Insert(artifact);
        }
        return album;
    }
}
```

Where it will be executed within its Database Lock. 

### Running Commands

You'll typically want to run DB Write Commands with `RunCommand*` APIs which are a faster and lighter weight 
alternative then durable jobs which are persisted in the **jobs.db** before execution.

Everytime commands are executed they'll be added to a ConcurrentQueue of the specified worker. Commands delegated to different named workers execute concurrently, whilst commands with the same worker are executed serially.

When using any `SyncCommand*` base class, its execution still uses database locks
but any contention is alleviated as they're executed serially by a single worker thread.

```csharp
public class MyServices(IBackgroundJobs jobs) : Service
{
    // Returns immediately with a reference to the Background Job
    public object Any(DeleteCreative request)
    {
        // Queues a durable job to execute the command with the AppDb Worker
        var jobRef = jobs.EnqueueCommand<DeleteCreativeCommand>(request);

        // Executes Command with Databases.Search worker
        jobs.EnqueueCommand<DeleteSearchCommand>(new DeleteSearch {
            Id = request.ArtifactId
        });

        return jobRef;
    }

    // Returns after the command is executed with its result (if any)
    public async Task Any(CreateAlbum request)
    {
        // Executes a transient (i.e. non-durable) job with the named worker
        var album = await jobs.RunCommandAsync<CreateAlbumCommand>(request);
        return album;
    }
}
```

### MQ Command DTOs

If using **Background MQ** we can use the `[Command]` attribute to be able to execute multiple commands on a single Request DTO Properties:

```csharp
[Tag(Tag.Tasks)]
[Restrict(RequestAttributes.MessageQueue), ExcludeMetadata]
public class DbWrites : IGet, IReturn<EmptyResponse>
{
    [Command<CreatePostVoteCommand>]
    public Vote? CreatePostVote { get; set; }
    
    [Command<CreateCommentVoteCommand>]
    public Vote? CreateCommentVote { get; set; }
    
    [Command<CreatePostCommand>]
    public Post? CreatePost { get; set; }
    
    [Command<UpdatePostCommand>]
    public Post? UpdatePost { get; set; }
    
    [Command<DeletePostsCommand>]
    public DeletePosts? DeletePosts { get; set; }
    
    [Command<DeleteAnswersCommand>]
    public DeleteAnswers? DeleteAnswers { get; set; }
    
    [Command<CreateAnswerCommand>]
    public Post? CreateAnswer { get; set; }
    
    [Command<PostSubscriptionsCommand>]
    public PostSubscriptions? PostSubscriptions { get; set; }
    
    [Command<TagSubscriptionsCommand>]
    public TagSubscriptions? TagSubscriptions { get; set; }    
    //...
}
```

Then to execute the commands we can use the `Request.ExecuteCommandsAsync` extension method for its 
Background MQ API implementation:

```csharp
public class BackgroundMqServices : Service
{
    public Task Any(DbWrites request) => Request.ExecuteCommandsAsync(request);
}
```

Which goes through all Request DTO properties to execute all populated properties with their associated
command, using it as the request for the command.

So after registering the `DbWrites` Command DTO with the MQ Service:

```csharp
mqService.RegisterHandler<DbWrites>(appHost.ExecuteMessage);
```

We can now publish a single `DbWrites` message to execute multiple commands in a single managed background thread:

```csharp
public class NotificationServices(MessageProducer mq) : Service
{
    public object Any(Watch request)
    {
        var userName = Request.GetClaimsPrincipal().GetUserName();

        mq.Publish(new DbWrites
        {
            PostSubscriptions = request.PostId == null ? null : new()
            {
                UserName = userName,
                Subscriptions = [request.PostId.Value],
            },
            TagSubscriptions = request.Tag == null ? null : new()
            {
                UserName = userName,
                Subscriptions = [request.Tag],
            },
        });
        
        mq.Publish(new AnalyticsTasks {
            WatchRequest = request,
        });
    }
}
```

We also benefit from its natural parallelism where write requests to different Databases are executed in parallel.


# Messaging API
Source: https://docs.servicestack.net/messaging

ServiceStack provides a [high-level Messaging API](https://github.com/ServiceStack/ServiceStack/blob/master/src/ServiceStack.Interfaces/Messaging/) exposing a number of essential messaging features in order to publish and receive messages as well as registering and processing handlers for different message types. A class diagram of the core interfaces is below:

![Messaging API](https://raw.github.com/mythz/rabbitmq-windows/master/img/messaging-api.png)

There are currently 5 supported MQ Server options:

  - [Background MQ Service](/background-mq)
  - [Rabbit MQ Server](/rabbit-mq)
  - [Redis MQ Server](/redis-mq)
  - [Amazon SQS MQ Server](/amazon-sqs-mq)
  - [Azure Service Bus MQ](/azure-service-bus-mq)

Like other ServiceStack providers, all MQ Servers are interchangeable, visible in the shared MQ Server tests below:

  - [MqServerIntroTests.cs](https://github.com/ServiceStack/ServiceStack/blob/master/tests/ServiceStack.Server.Tests/Messaging/MqServerIntroTests.cs)
  - [MqServerAppHostTests.cs](https://github.com/ServiceStack/ServiceStack/blob/master/tests/ServiceStack.Common.Tests/Messaging/MqServerAppHostTests.cs)

## Mix in MQ Server

In ASP.NET Core Apps we recommend using [mix](/mix-tool) to configure your preferred MQ Service, other than being quicker to add,
it proposes adopting a naming convention in app settings and file names that other `mix` features can also make use of:

:::sh
x mix [mq]
:::

Currently available list of MQ Services:

```
Results matching tag [mq]:

   1. backgroundmq  Use Memory Background MQ                    to: $HOST  by @ServiceStack  [mq]
   2. rabbitmq      Use RabbitMQ                                to: $HOST  by @ServiceStack  [mq]
   3. sqs           Use AWS SQS MQ                              to: $HOST  by @ServiceStack  [mq]
   4. servicebus    Use Azure Service Bus MQ                    to: $HOST  by @ServiceStack  [mq]
   5. redismq       Use Redis MQ                                to: $HOST  by @ServiceStack  [mq]
   6. feature-mq    Simple MQ Feature to test sending Messages  to: $HOST  by @ServiceStack  [feature,mq,sharp]
```

## Worker Service Templates

If you'd instead prefer to develop stand-alone MQ Servers (i.e. without HTTP access) then it can be beneficial to run the MQ Server in an ASP.NET Core Worker Service by starting from a pre-configured project template:

<worker-templates></worker-templates>

|| .NET Core C# Worker Service Templates |
|-|-|
| [worker-rabbitmq](https://github.com/NetCoreTemplates/worker-rabbitmq)        | .NET 6.0 Rabbit MQ Worker Service |
| [worker-redismq](https://github.com/NetCoreTemplates/worker-redismq)        | .NET 6.0 Redis MQ Worker Service |
| [worker-servicebus](https://github.com/NetCoreTemplates/worker-servicebus)        | .NET 6.0 Azure Service Bus MQ Worker Service |
| [worker-sqs](https://github.com/NetCoreTemplates/worker-sqs)        | .NET 6.0 AWS SQS MQ Worker Service |

## MQ Stats on Admin UI Dashboard

The health and activity of your MQ Services can be monitored from the [Admin UI Dashboard](/admin-ui) which maintains aggregate stats for how many messages have been received, processed or failed as well as detailed stats on each MQ Worker:

[![](/img/pages/messaging/mq-stats.png)](/admin-ui)

## Benefits of Message Queues

One of the benefits of using ServiceStack is its integrated support for hosting MQ Servers
allowing your Services to be invoked via a MQ Broker. There are a number of reasons why you'd want 
to use a MQ as an alternative to HTTP including:
    
  - Sender is decoupled from Receiver, eliminating point-to-point coupling and configuration
  - Allows no-touch deploy of new clients and servers without updating any configuration
  - Removes time-coupling allowing clients and servers to be deployed independently without downtime
  - Better reliability, consumers can still send messages when servers are down and vice-versa
  - Durable, messages can be persisted and survive application or server reboots
  - Allows for CPU Intensive or long operations without disrupting message workflow
  - Instant response times by queuing slow operations and executing them in the background
  - Allows for natural load-balancing where throughput can be increased by simply adding more processors or servers
  - Message-based design allows for easier parallelization and introspection of computations
  - Greater throttling and control of message throughput, message execution can be determined by server
  - Reduces request contention and can defer execution of high load spikes over time
  - Better recovery, messages generating server exceptions can be retried and maintained in a dead-letter-queue
  - DLQ messages can be introspected, fixed and later replayed after server updates and rejoin normal message workflow

More details of these and other advantages can be found in the definitive
[Enterprise Integration Patterns](http://www.eaipatterns.com).

Likewise the HTTP Service Clients implement the Messaging API `IMessageProducer`:

```csharp
void Publish<T>(T requestDto);
void Publish<T>(IMessage<T> message);
```

When publishing a `IMessage<T>` the message metadata are sent as HTTP Headers with an `X-` prefix.

## MQ Client Architecture

By promoting clean (endpoint-ignorant and dependency-free) Service and DTO classes, your web services are instantly re-usable from non-http contexts like MQ Services. 

Within MQ Services, Request DTO's get wrapped and sent within the [IMessage](https://github.com/ServiceStack/ServiceStack/blob/master/src/ServiceStack.Interfaces/Messaging/IMessage.cs) body, which looks like:

![ServiceStack MQ Client Architecture](/img/pages/messaging/servicestack-mqclients.png) 

## MQ Server Architecture

The Server Architecture shows where MQ Hosts (in green) fits within the context of ServiceStack's Request Pipeline.
Effectively MQ Services are treated as "internal Services" bypassing HTTP Web Services Content Negotiation and Global Request/Response Filters:

![ServiceStack Logical Architecture View](/img/pages/overview/servicestack-logical-view-02.png) 

MQ Services also have their own distinct `GlobalMessageRequestFilters` and `GlobalMessageResponseFilters` for registering custom logic that only applies to MQ Requests. Plugins like [Validation Feature](/validation#validation-feature) can execute custom behavior for both HTTP and MQ Services by registering it in [both HTTP GlobalRequestFilters and MQ GlobalMessageRequestFilters](https://github.com/ServiceStack/ServiceStack/blob/fc191835d97e5b6d89d3cd7a4742793af44eb8c3/src/ServiceStack/Validation/ValidationFeature.cs#L25-L29), e.g:

```csharp
appHost.GlobalRequestFilters.Add(ValidationFilters.RequestFilter);
appHost.GlobalMessageRequestFilters.Add(ValidationFilters.RequestFilter);
```

## Message Workflow

By default, MQ Servers will send a response message after it's processed each message, 
what the response is and which Queue (or HTTP url) the response is published to is dependent 
on the outcome of the message handler, i.e:

![MQ Flowchart](https://raw.githubusercontent.com/ServiceStack/Assets/master/img/wikis/message-flow.png) 

### Messages with no responses are sent to '.outq' Topic

When a handler returns a `null` response, the incoming message is re-published as a 
"transient" message to the out queue, e.g: `mq:Hello.outq` having the effect of notifying 
any subscribers to `mq:Hello.outq` each time a message is processed. 

We can use this behavior to block until a message gets processed with:

```csharp
IMessage<Hello> msgCopy = mqClient.Get<Hello>(QueueNames<Hello>.Out);
mqClient.Ack(msgCopy);
msgCopy.GetBody().Name //= World
```

Also shown in this example is an explicit **Ack** (which should be done for each message 
you receive) to tell the MQ Broker that you've taken responsibility of the message so it can 
safely remove it off the queue.

### Messages with Responses are published to the Response .inq

Often message handlers will just return a POCO response after it processes a message, e.g:

```csharp
mqServer.RegisterHandler<Hello>(m =>
    new HelloResponse { Result = $"Hello, {m.GetBody().Name}!" });
```

Whenever there's a response, then instead of the .outq the response message is sent to 
the **.inq** of the response message type, which for a `HelloResponse` type is just 
**mq:HelloResponse.inq**, e.g:

```csharp
mqClient.Publish(new Hello { Name = "World" });

var responseMsg = mqClient.Get<HelloResponse>(QueueNames<HelloResponse>.In);
mqClient.Ack(responseMsg);
responseMsg.GetBody().Result //= Hello, World!
```

::: info
this behavior can be limited to only publish responses for types in the 
`mqServer.PublishResponsesWhitelist`, otherwise all response messages can be disabled 
entirely by setting `mqServer.DisablePublishingResponses = true`.
:::

### Responses from Messages with ReplyTo are published to that address

Whilst for the most part you'll only need to publish POCO messages, you can also alter the 
default behavior by providing a customized `IMessage<T>` wrapper which ServiceStack will 
send instead, e.g. you can specify your own **ReplyTo** address to change the queue where 
the response gets published, e.g:

```csharp
const string replyToMq = mqClient.GetTempQueueName();
mqClient.Publish(new Message<Hello>(new Hello { Name = "World" }) {
    ReplyTo = replyToMq
});

IMessage<HelloResponse> responseMsg = mqClient.Get<HelloResponse>(replyToMq);
mqClient.Ack(responseMsg);
responseMsg.GetBody().Result //= Hello, World!
```

#### ReplyTo addresses can be URLs

A nice feature unique in ServiceStack is that the ReplyTo address can even be a **HTTP Uri**, 
in which case ServiceStack will attempt to **POST** the raw response at that address. 
This works nicely with ServiceStack Services which excel at accepting serialized DTO's.

```csharp
mqClient.Publish(new Message<Hello>(new Hello { Name = "World" }) {
    ReplyTo = "http://example.org/hello/callback"
});
```

### Messages with exceptions are re-tried then published to the dead-letter-queue (.dlq)

By default Mq Servers lets you specify whether or not you want messages that cause 
an exception to be retried by specifying a RetryCount of 1 (default), or if you don't want 
any messages re-tried, specify a value of 0, e.g:

```csharp
var mqServer = new RabbitMqServer { RetryCount = 1 };
```

To illustrate how this works we'll keep a counter of how many times a message handler 
is invoked, then throw an exception to force an error condition, e.g:

```csharp
var called = 0;
mqServer.RegisterHandler<Hello>(m => {
    called++;
    throw new ArgumentException("Name");
});
```

Now when we publish a message the response instead gets published to the messages **.dlq**, 
after it's first transparently retried. We can verify this behavior by checking `called=2`:

```csharp
mqClient.Publish(new Hello { Name = "World" });

IMessage<Hello> dlqMsg = mqClient.Get<Hello>(QueueNames<Hello>.Dlq);
mqClient.Ack(dlqMsg);

Assert.That(called, Is.EqualTo(2));
```

DLQ Messages retains the original message in their body as well as the last exception 
serialized in the `IMessage.Error` ResponseStatus metadata property, e.g:

```csharp
dlqMsg.GetBody().Name   //= World
dlqMsg.Error.ErrorCode  //= typeof(ArgumentException).Name
dlqMsg.Error.Message    //= Name
```

Since the body of the original message is left in-tact, you're able to retry failed messages 
by removing them from the dead-letter-queue then re-publishing the original message, e.g:

```csharp
IMessage<Hello> dlqMsg = mqClient.Get<Hello>(QueueNames<Hello>.Dlq);

mqClient.Publish(dlqMsg.GetBody());

mqClient.Ack(dlqMsg);
```

This is useful for recovering failed messages after identifying and fixing bugs that were 
previously causing exceptions, where you can replay and re-process DLQ messages and continue 
processing them as normal.

### Priority Queues

MQ Servers spawns 2 threads for each handler, one to listen to the Message Inbox `mq:<Message>.inq` and another to listen on the Priority Queue located at `mq:<Message>.priorityq`. 

You can white-list which messages to enable Priority Queue's for with `mqServer.PriorityQueuesWhitelist` or disable them all by setting:

```cs
mqServer.DisablePriorityQueues = true;
```

### OneWay HTTP Requests are published to MQ then executed

Using the `SendOneWay()` Service Client APIs will publish DTO's to the `/oneway` [Pre-defined Route](/routing#pre-defined-routes):

```csharp
var client = new JsonApiClient(BaseUrl);
client.SendOneWay(new RequestDto { ... }); //POST's to /json/oneway/RequestDto
```

Where if there is an MQ Server is registered in the AppHost it will instead publish the Request DTO to the registered MQ Server who then pulls it from the MQ Broker and executes the message in a background thread like a normal MQ Message. If no MQ Server is registered then the Request is executed in the HTTP Handler like a normal HTTP Request.

### OneWay MQ and HTTP Service Clients are Substitutable

Service Clients and MQ Clients are also interoperable where all MQ Clients implement the Service Clients `IOneWayClient` API which enables writing code that works with both HTTP and MQ Clients:

```csharp
IOneWayClient client = GetClient();
client.SendOneWay(new RequestDto { ... });
```

### Disable 'outq' notification messages

All MQ Servers support the ability to specify a whitelist of Requests you **only** want to publish `.outq` for:

```csharp
PublishToOutqWhitelist = new[]{ nameof(MyRequest) }
```

Alternatively all `.outq` messages can be disabled with:

```csharp
DisablePublishingToOutq = true
```

### Flexible Queue Name strategies

There are more flexible options for specifying the Queue Names where you can categorize queue names or avoid conflicts with 
other MQ services by specifying a global prefix to be used for all Queue Names, e.g:

```csharp
QueueNames.SetQueuePrefix("site1.");

QueueNames<Hello>.In //= site1.mq:Hello.inq
```

Or to gain complete control of each queue name used, provide a custom QueueName strategy, e.g:

```csharp
QueueNames.ResolveQueueNameFn = (typeName, suffix) =>
    $"SITE.{typeName.ToLower()}{suffix.ToUpper()}";

QueueNames<Hello>.In  //= SITE.hello.INQ
```

> Note: Custom QueueNames need to be declared on both MQ Client in addition to ServiceStack Hosts.  


## Authenticated Requests via MQ

As MQ Requests aren't executed within the Context of a HTTP Request they don't have access to any HTTP Info like HTTP Cookies, Headers, FormData, etc. This also means the Users Session isn't typically available as it's based on the [ss-id Session Ids in Cookies](/auth/sessions).

### Embedding Auth Info in MQ Request DTO

The easiest way to publish Authenticated MQ Requests is using the [same approach as Encrypted Messaging](/auth/encrypted-messaging#authentication-with-encrypted-messaging) by embedding the Auth Info in the Request DTO by implementing `IHasSessionId` if using
session-based Authentication or `IHasBearerToken` if using token-based Auth, e.g:

```csharp
public class AuthSessionMq : IHasSessionId
{
    public string SessionId { get; set; }
    //...
}

public class AuthTokenMq : IHasBearerToken
{
    public string BearerToken { get; set; }
    //...
}

public class MqServices : Service
{
    public void Any(PublishSessionMq request)
    {
        var mqRequest = request.ConvertTo<AuthSessionMq>();
        mqRequest.SessionId = Request.GetSessionId();
        PublishMessage(mqRequest);
    }

    public void Any(PublishTokenMq request)
    {
        var mqRequest = request.ConvertTo<AuthTokenMq>();
        mqRequest.BearerToken = Request.GetJwtToken();
        PublishMessage(mqRequest);
    }
}
```

### Overriding MQ Request Headers

Alternatively as ServiceStack also lets you specify a Users Session ids using HTTP Headers (with `X-` prefix), we can instead specify Session Ids using 
Request Headers. To do this we can create a custom Request Context that the MQ Service is executed within and set the SessionId in the Headers:

```csharp
var req = new BasicRequest { Verb = HttpMethods.Post };
req.Headers["X-ss-id"] = sessionId;
```

Alternatively we can inject the Session itself. As a Users Session is just a `AuthUserSession` POCO persisted against the SessionId, we can access the 
Users Session from the CacheClient directly ourselves, e.g:

```csharp
//i.e. urn:iauthsession:{sessionId}
var sessionKey = SessionFeature.GetSessionKey(sessionId); 
var usersSession  = HostContext.TryResolve<ICacheClient>()
    .Get<IAuthUserSession>(sessionKey);
```

And inject to use this Session with:

```csharp
req.Items[Keywords.Session] = usersSession;
```

We can then Execute the MQ Service with this custom Request Context with:

```csharp
return this.ExecuteMessage(m, req);
```

> See the [Session docs](/auth/sessions) for more info about Sessions in ServiceStack

We'll walk-through a minimal example using this approach to make authenticated Requests and access the Users Session in a Service that's accessible via both HTTP and MQ transports.

To start we'll configure an Authentication-enabled ServiceStack MQ and HTTP Self-Hosted Application:

```csharp
public class AppHost : AppSelfHostBase
{
    public override void Configure(Container container)
    {
        //Enable Authentication
        Plugins.Add(new AuthFeature(() => new AuthUserSession(), 
            new IAuthProvider[] { 
                // Enable Username/Password Authentication
                new CredentialsAuthProvider(AppSettings), 
            }));

        //Use an InMemory Repository to persist User Authenticaiton Info
        container.Register<IUserAuthRepository>(c => new InMemoryAuthRepository());

        //Create a new User on Startup
        var authRepo = container.Resolve<IUserAuthRepository>();
        authRepo.CreateUserAuth(new UserAuth {
            Id = 1,
            UserName = "mythz",
            FirstName = "John",
            LastName = "Doe",
            DisplayName = "John Doe",
        }, "p@55word");

        //Register to use a Rabbit MQ Server
        container.Register<IMessageService>(c => new RabbitMqServer());

        var mqServer = container.Resolve<IMessageService>();

        mqServer.RegisterHandler<AuthOnly>(m => {
            var req = new BasicRequest { Verb = HttpMethods.Post };
            req.Headers["X-ss-id"] = m.GetBody().SessionId;
            var response = ExecuteMessage(m, req);
            return response;
        });

        //Start the Rabbit MQ Server listening for incoming MQ Requests
        AfterInitCallbacks.Add(appHost => mqServer.Start());
    }
}
```

and now add the Service Implementation:

```csharp
public class AuthOnly : IReturn<AuthOnlyResponse>
{
    public string Name { get; set; }
    public string SessionId { get; set; }
}

public class AuthOnlyResponse
{
    public string Result { get; set; }
}

public class AuthOnlyService : Service 
{
    [Authenticate] //Only allow Authenticated Requests
    public object Any(AuthOnly request)
    {
        // Get the User Session for this Request
        var session = base.SessionAs<AuthUserSession>();

        return new AuthOnlyResponse {
            Result = $"Hello, {request.Name}! Your UserName is {session.UserAuthName}";
        };
    }
}
```

With the ServiceStack Host and Service implemented, we can start listening to both HTTP and Rabbit MQ Requests by starting the AppHost:

```csharp
new AppHost().Start("http://localhost:1337/");
```

Then on the Client we can authenticate using UserName/Password credentials using the HTTP [Service Client](/csharp-client), e.g:

```csharp
var client = new JsonApiClient("http://localhost:1337/");

var response = client.Post(new Authenticate {
    UserName = "mythz",
    Password = "p@55word",
    RememberMe = true,
});

var sessionId = response.SessionId;
```

The above Request establishes an authenticated Session with the `JsonServiceClient` instance which has its Cookies populated with the Users SessionIds - allowing it to make subsequent authenticated requests as that User. 

To make Authenticated Requests via MQ we can pass the returned `sessionId` into the MQ Request:

```csharp
var mqFactory = RabbitMqMessageFactory();
using (var mqClient = mqFactory.CreateMessageQueueClient())
{
    mqClient.Publish(new AuthOnly {                        
        Name = "RabbitMQ Request",
        SessionId = sessionId,
    });

    //Block until the Response is Received:
    var responseMsg = mqClient.Get<AuthOnlyResponse>(QueueNames<AuthOnlyResponse>.In);
    mqClient.Ack(responseMsg); //Acknowledge the message was received
    
    //"Hello, RabbitMQ Request! Your UserName is mythz"
    Console.WriteLine(responseMsg.GetBody().Result); 
}
```

This works since we're extracting the SessionId and injecting into a Custom Request Context used by the MQ Service:

```csharp
mqServer.RegisterHandler<AuthOnly>(m => {
    var req = new BasicRequest { Verb = HttpMethods.Post };
    req.Headers["X-ss-id"] = m.GetBody().SessionId;
    var response = ExecuteMessage(m, req);
    return response;
});
```

### Global Filters vs Action Filters

One important difference worth re-iterating is that Filter Attribute declared on the Service class are top-level filters executed during Global Request filters which are only executed for HTTP Requests:

```csharp
[Authenticate] //Top-level Filter Attribute - only executed for HTTP Requests
public class MqAuthOnlyService : Service 
{
    public object Any(AuthOnly request)
    {
        var session = base.SessionAs<AuthUserSession>();
        return new AuthOnlyResponse {
            Result = $"Hello, {request.Name}! Your UserName is {session.UserAuthName}";
        };
    }
}
```

This will allow you to separate behavior for external HTTP Requests from internal MQ Requests.

To validate both HTTP and MQ Requests, place the `[Authenticate]` attribute on the method itself, e.g:

```csharp
public class AuthOnlyService : Service 
{
    [Authenticate] //Authenticate both HTTP and MQ Requests
    public object Any(AuthOnly request)
    {
        var session = base.SessionAs<AuthUserSession>(); 
        return new AuthOnlyResponse {
            Result = $"Hello, {request.Name}! Your UserName is {session.UserAuthName}";
        };
    }
}
```

### feature-mq

The `feature-mq` adds MQ support to your App, complete with UI and includes 2 different ways of calling MQ Services in ServiceStack, just like 
[example-validation UI](/mix-tool#mix-in-prebuilt-recipes-and-working-examples), `feature-mq` is another complete working example with both UI and Service implementation in the following files:

  - [Configure.Mq.cs?](https://gist.github.com/gistlyn/355338cd60a32ee9c9fc4761269f7782#file-configure-mq-cs)
  - [Feature.Mq.cs](https://gist.github.com/gistlyn/355338cd60a32ee9c9fc4761269f7782#file-feature-mq-cs)
  - [ServiceInterface\MqServices.cs ](https://gist.github.com/gistlyn/355338cd60a32ee9c9fc4761269f7782#file-serviceinterface-mqservices-cs)
  - [ServiceModel\Mq.cs](https://gist.github.com/gistlyn/355338cd60a32ee9c9fc4761269f7782#file-servicemodel-mq-cs)
  - [wwwroot\messaging.html](https://gist.github.com/gistlyn/355338cd60a32ee9c9fc4761269f7782#file-wwwroot-messaging-html)
  
As `Configure.Mq.cs?` is optional it will only add it if doesn't already exist, so it will either use your existing MQ configuration
or configure your App to use the In Memory `BackgroundMqService` implementation.

Add `feature-mq` to your project with:

:::sh
x mix feature-mq
:::

![](/img/pages/nav/feature-mq.png)

This will add the `TestMq` Service and make it available to your MQ endpoint. `TestMq` is a regular service that updates values in the 
App's registered `ICacheClient` and returns the Cache's current values as well as the internal Stats of the MQ:

```csharp
public class MqServices : Service
{
    public IMessageService MqService { get; set; }

    public void Any(PublishMq request)
    {
        PublishMessage(request.ConvertTo<TestMq>());
    }

    public object Any(TestMq request)
    {
        if (!string.IsNullOrEmpty(request.Name))
            Cache.Set("mq.name", request.Name);
        
        if (request.Add > 0)
            Cache.Increment("mq.counter", (uint)request.Add);
        else if (request.Add < 0)
            Cache.Decrement("mq.counter", (uint)(request.Add * -1));

        return new TestMqResponse {
            Name = Cache.Get<string>("mq.name"),
            Counter = Cache.Get<long>("mq.counter"),
            StatsDescription = MqService.GetStatsDescription(),
        };
    }
}
```

The 2 ways to call a MQ Service is directly using the `publish` or `sendOneWay` APIs (available in all ServiceStack Service Clients) where 
it send the request to the Service's `/oneway` endpoint which will automatically publish it to the registered MQ. 

Alternatively you can publish the Request DTO yourself from a different Service Implementation as done in `PublishMq`, as-is typical for
Services that queues sending emails without blocking Service Execution.

The feature's UI allows you to publish `TestMq` messages using either approach:

```js
client = new JsonServiceClient('/');

var oneway = document.querySelector('input[name=mq-publish]:checked').value === "OneWay";
if (oneway) {
    client.publish(new TestMq({ name: $txtName.value, add: parseInt(add) }))
} else {
    client.post(new PublishMq({ name: $txtName.value, add: parseInt(add) }))
}
```

Both approaches end with the same result with the `TestMq` Request DTO published and executed by the registered MQ Service as shown in the
UI which is periodically updated with the current state in the Cache and the internal stats of the MQ Service showing how many messages it processed.


# Background MQ Service
Source: https://docs.servicestack.net/background-mq

The `BackgroundMqService` is a full-featured `IMessageService` implementation that provides the functionality of [distributed MQ Server](/messaging) but doesn't require any infrastructure dependencies. It's ideal for **queueing long-running background tasks** by publishing Request DTOs, control execution throughput by creating different sized Thread Pools per message type, inspect the status and statistics of different MQ Workers, stop and restart processing messages, etc. It's a complete implementation implementing the same [MQ Message flow](/messaging#message-workflow) and passes the existing MQ Test suites so you'll be able to substitute it for any of the other MQ Servers. But it still doesn't persist messages across App restarts so we recommend using it in combination with persistence to an external data source - generally a good idea for tracking the status of long-running jobs.

To illustrate an example we'll walkthrough TechStacks implementation of what's likely the most popular use of background job in Web Apps - sending emails... 

## Using Background Service to send Emails

Configuring the `BackgroundMqService` is the same as every other MQ Server, i.e. register it in the IOC and register handlers for the Request DTO of each Service you want to be able to run in the background:

```csharp
container.Register<IMessageService>(c => new BackgroundMqService());
var mqServer = container.Resolve<IMessageService>();

mqServer.RegisterHandler<SendNotification>(ExecuteMessage, 4);
mqServer.RegisterHandler<SendSystemEmail>(ExecuteMessage);

AfterInitCallbacks.Add(host => {
    mqServer.Start();
    ExecuteService(new RetryPendingNotifications());
});
```

The one difference is that we also register an `AfterInitCallbacks` to Execute the [RetryPendingNotifications](https://github.com/NetCoreApps/TechStacks/blob/c89920d92e1e11a5495bf88a45fea60aea9d199e/src/TechStacks.ServiceInterface/Admin/NotificationServices.cs#L51) Service after the AppHost has started. We'll look at the implementation later, but it's for re-queueing any incomplete Background Jobs that failed to complete.

With the handlers registered, any Service can queue any of these Services to Execute in the background by publishing a populated Request DTO of that Type. One place where TechStacks does this is to notify all subscribers when someone creates a post, which it does by [calling SendNotificationAsync()](https://github.com/NetCoreApps/TechStacks/blob/973eecdc334687e13008aa9f07444e7c6affcfd9/src/TechStacks.ServiceInterface/PostServices.cs#L62):

```csharp
await SendNotificationAsync(nameof(CreatePost), nameof(Post), id);
```

A common API that inserts an entry in the `Notification` table and publishes a `SendNotification` message to have the Service executed in the background by 1 of the 4 MQ Workers configured at Startup:

```csharp
public async Task SendNotificationAsync(string eventName, string refType, long refId)
{
    var notificationId = await Db.InsertAsync(ToNotification(eventName, refType, refId), selectIdentity:true);
    PublishMessage(new SendNotification { Id = notificationId });
}

Notification ToNotification(string eventName, string refType, long refId) => new Notification {
    Event = eventName,
    RefId = refId,
    RefType = refType,
    RefUrn = $"urn:{refType}:{refId}",
    Created = DateTime.Now,
}; 
```

`SendNotification` is a regular ServiceStack Service except we only want it accessible to Admin Users so it's annotated with `[ExcludeMetadata]` to hide it from the public metadata services. 

```csharp
[ExcludeMetadata]
[Route("/notifications/{Id}/send")]
public class SendNotification : IReturnVoid
{
    public long Id { get; set; }
}
```

For the complete reference [NotificationServices.cs](https://github.com/NetCoreApps/TechStacks/blob/master/src/TechStacks.ServiceInterface/Admin/NotificationServices.cs) contains all the background Email Services and bespoke code to send the different Email types whilst [NotificationServices.Utils.cs](https://github.com/NetCoreApps/TechStacks/blob/master/src/TechStacks.ServiceInterface/Admin/NotificationServices.Utils.cs) contains reusable functionality shared by the different email implementations. 

The `SendNotification` Service sends a different Email based on the Notification Event Type which are all executed within the same managed implementation below where it takes care of marking the completion of the notification, either with the time it successfully completed or the Exception the notification it failed with:

```csharp
[RequiredRole("Admin")]
public partial class NotificationServices : Service
{
    private static ILog log = LogManager.GetLogger(typeof(NotificationServices));

    Func<Notification, Task> GetEventHandler(string eventName)
    {
        switch (eventName)
        {
            case nameof(CreatePost):
                return SendNewPostEmail;
            case nameof(UserPostReport):
                return SendReportPostEmail;
            case nameof(UserPostCommentReport):
                return SendReportCommentEmail;
        }
        return null;
    }

    public async Task Any(SendNotification request)
    {
        var notification = AssertNotification(request.Id);

        var eventHandler = GetEventHandler(notification.Event);
        if (eventHandler != null)
        {
            try
            {
                await eventHandler(notification);

                await Db.UpdateOnlyAsync(() => new Notification {
                        Completed = DateTime.Now
                    },
                    where: x => x.Id == notification.Id);
            }
            catch (Exception ex)
            {
                await Db.UpdateOnlyAsync(() => new Notification {
                        Failed = DateTime.Now,
                        Error = ex.Message + Environment.NewLine + ex
                    },
                    where:x => x.Id == notification.Id);
                throw;
            }
        }
        else
        {
            log.Warn($"Received notification of unknown Event Type: {notification.Event}");
        }
    }
}
```

The creation of Email Template is split into different steps to ensure all users are sent the same rendered Email snapshot, even if the task failed midway through and had to be replayed. 

Each template follows the same approach:

 - Work out all users the email should be sent to 

 - Retrieve all data required by the template and inject it into a new [ServiceStack ScriptContext](https://sharpscript.net/docs/installation) 
 - Use the context to render the specified [email template](https://github.com/NetCoreApps/TechStacks/tree/master/src/TechStacks/emails). 
 
 In this case it renders the [post-new.html](https://github.com/NetCoreApps/TechStacks/blob/master/src/TechStacks/emails/post-new.html) Template inside the [_layout.html](https://github.com/NetCoreApps/TechStacks/blob/master/src/TechStacks/emails/_layout.html) - which is based on the [Email Bootstrap Template](https://github.com/seanpowell/Email-Boilerplate/blob/master/email_commentsremoved.html) and used as the layout for all email templates.

```csharp    
private async Task SendNewPostEmail(Notification notification)
{
    EmailTemplate template = null;

    if (notification.EmailTemplateId == null)
    {
        var post = await AssertPost(notification.RefId);
        var org = await Db.SingleByIdAsync<Organization>(post.OrganizationId);
        var user = await Db.SingleByIdAsync<CustomUserAuth>(post.UserId);

        var q = Db.From<OrganizationSubscription>()
            .Where(x => x.OrganizationId == post.OrganizationId)
            .And("ARRAY[{0}] && post_types", post.Type)
            .Select(x => x.UserId);
        var postTypeSubscriberUserIds = await Db.ColumnAsync<int>(q);

        var context = CreateEmailTemplateContext();
        var templatePath = "emails/post-new";
        var page = context.GetPage(templatePath);
        var result = new PageResult(page) {
            Args = {
                ["baseUrl"] = AppSettings.GetString("PublicBaseUrl"),
                ["post"] = post,
                ["organization"] = org,
            }
        };

        template = await CreateAndSaveEmailTemplate(notification, nameof(SendNewPostEmail), templatePath, 
            toUserIds: postTypeSubscriberUserIds, 
            fromName:  user.DisplayName ?? user.UserName, 
            ccName:    org.Name + " Subscribed", 
            subject:   $"[{post.Type}] {post.Title}", 
            html:      await result.RenderToStringAsync());
    }
    else
    {
        template = await Db.SingleByIdAsync<EmailTemplate>(notification.EmailTemplateId);
    }

    await SendEmailsToRemainingUsers(notification, template);
}
```

The end result of each email is to create an entry in the generic [EmailTemplate](https://github.com/NetCoreApps/TechStacks/blob/master/src/TechStacks.ServiceInterface/DataModel/EmailTemplate.cs) table with the rendered email to send and all users to send it to. It's then handed to the managed `SendEmailsToRemainingUsers` routine to send the emails.

The final step is to send the email to all designated users, which is ultimately done by the [EmailProvider](https://github.com/NetCoreApps/TechStacks/blob/master/src/TechStacks.ServiceInterface/Notifications/EmailProvider.cs) which uses an `SmtpClient` to send the Email to the AWS SES endpoint.

To handle cases where the long-running process can fail at any point, the email template keeps a record of each user that emails were sent to by updating the `emailed_user_ids` PostgreSQL Array after each email is sent. So if the `SendNotification` message is replayed it will start back where it left off and only sends emails to the remaining users.

```csharp
private async Task SendEmailsToRemainingUsers(Notification notification, EmailTemplate template)
{
    var remainingUserIds = notification.UserIds.Where(x => !notification.EmailedUserIds.Contains(x)).ToList();
    if (remainingUserIds.Count > 0)
    {
        var users = await Db.SelectAsync<UserEmailInfo>(Db.From<CustomUserAuth>()
            .Where(x => remainingUserIds.Contains(x.Id)));

        var userMap = users.ToDictionary(x => x.Id);

        foreach (var userId in remainingUserIds)
        {
            var user = userMap[userId];
            if (!string.IsNullOrEmpty(user.Email))
            {
                Email.Send(template.ToEmailMessage(user.Email, user.DisplayName ?? user.UserName));
            }

            await RecordEmailSentToUser(notification.Id, userId);
        }
    }
    else
    {
        SendNotificationEmail(template, $"{notification.UserIds.Length} subscribers");
    }
}

private void SendNotificationEmail(EmailTemplate template, string toName)
{
    var notificationsEmail = AppSettings.GetString("NotificationsFromEmail");
    var email = template.ToEmailMessage(notificationsEmail, toName);
    Email.Send(email);
}

private async Task RecordEmailSentToUser(long notificationId, int userId)
{
    await Db.ExecuteSqlAsync(@"UPDATE notification SET emailed_user_ids = emailed_user_ids || @userId
        WHERE id = @id", new { userId, id = notificationId });
}
```

## Replaying Messages

The `RetryPendingNotifications` Service replays incomplete notifications by publishing new `SendNotification` messages which are executed by the `BackgroundMqService` as normal. 
This also lets you replay failed notifications by setting `Failed` to `null` and recalling the Service. As the state of each task is persisted after each step, it can fail at any point and the replayed task will be able to restart where it left off.

```csharp
public object Any(RetryPendingNotifications request)
{
    var pendingNotificationIds = Db.Column<long>(Db.From<Notification>()
            .Where(x => x.Completed == null && x.Failed == null)
            .Select(x => x.Id))
        .ToArray();

    if (pendingNotificationIds.Length > 0)
    {
        log.Info($"Resending {pendingNotificationIds.Length} pending notifications: {pendingNotificationIds}");

        foreach (var notificationId in pendingNotificationIds)
        {
            PublishMessage(new SendNotification { Id = notificationId });
        }
    }
    
    return new RetryPendingNotificationsResponse {
        ResentIds = pendingNotificationIds
    };
}
```

## MQ Status

The other benefit from persisting the status of each tasks is being able to inspect the `Notification` and `EmailTemplate` table to be able to monitor the progress of each Task. 

We can also call the [IMessageService](https://github.com/ServiceStack/ServiceStack/blob/master/src/ServiceStack.Interfaces/Messaging/IMessageService.cs) APIs to inspect the state of the Background MQ Service. We can use the Service below to make the APIs accessible remotely:

```csharp
[Route("/mq/stop")]  // Stop the Background Service and all MQ Workers from processing more messages
public class MqStop : IReturn<string> {}

[Route("/mq/start")] // Start the Background Service and process any queued messages
public class MqStart : IReturn<string> {}

[Route("/mq/stats")]
public class MqStats : IReturn<string> {}

[Route("/mq/status")]
public class MqStatus : IReturn<string> {}

public class BackgroundAdminServices : Service
{
    public IMessageService MqService { get; set; }
    
    [RequiredRole("Admin")]
    public object Any(MqStart request)
    {
        MqService.Start();
        return "OK";
    }
    
    [RequiredRole("Admin")]
    public object Any(MqStop request)
    {
        MqService.Stop();
        return "OK";
    }

    public object Any(MqStats request) => MqService.GetStats();

    [AddHeader(ContentType = MimeTypes.PlainText)]
    public object Any(MqStatus request) => MqService.GetStatsDescription();
}
```

This lets you can call [/mq/stats](https://techstacks.io/mq/stats.json) to view a summary of **all messages processed** since the last time the App was restarted and [/mq/status](https://techstacks.io/mq/status) to view **all Queues** the Background Service is currently listening to and the **statistics of each individual MQ worker**. 

Here's a snapshot of what this looks like for TechStacks with 4 threads listening to `SendNotification` messages and 1 thread listening to `SendSystemEmail`:

```
# MQ SERVER STATS:

STATUS: Started

LISTENING ON: 
  mq:SendNotification.inq
  mq:SendNotification.inq
  mq:SendNotification.inq
  mq:SendNotification.inq
  mq:SendSystemEmail.inq

------------------------------

# COLLECTIONS:

------------------------------
INFO SendNotification:

STATS:
  Thread Count:         4
  Total Messages Added: 27
  Total Messages Taken: 0
  Total .outq Messages: 27
  Total .dlq Messages:  0
QUEUES:
  mq:SendNotification.inq:        0 message(s)
  mq:SendNotification.priorityq:  0 message(s)
  mq:SendNotification.dlq:        0 message(s)
  mq:SendNotification.outq:       27 message(s)
------------------------------
INFO SendSystemEmail:

STATS:
  Thread Count:         1
  Total Messages Added: 1
  Total Messages Taken: 0
  Total .outq Messages: 1
  Total .dlq Messages:  0
QUEUES:
  mq:SendSystemEmail.inq:         0 message(s)
  mq:SendSystemEmail.priorityq:   0 message(s)
  mq:SendSystemEmail.dlq:         0 message(s)
  mq:SendSystemEmail.outq:        1 message(s)
------------------------------

# WORKERS:

------------------------------
WORKER 1 on mq:SendNotification.inq 
STATS for SendNotification:

  TotalNormalMessagesReceived:    7
  TotalPriorityMessagesReceived:  0
  TotalProcessed:                 7
  TotalRetries:                   0
  TotalFailed:                    0
  LastMessageProcessed:           4/9/18 7:44:49 PM
------------------------------
WORKER 2 on mq:SendNotification.inq 
STATS for SendNotification:

  TotalNormalMessagesReceived:    7
  TotalPriorityMessagesReceived:  0
  TotalProcessed:                 7
  TotalRetries:                   0
  TotalFailed:                    0
  LastMessageProcessed:           4/9/18 7:49:17 PM
------------------------------
WORKER 3 on mq:SendNotification.inq 
STATS for SendNotification:

  TotalNormalMessagesReceived:    7
  TotalPriorityMessagesReceived:  0
  TotalProcessed:                 7
  TotalRetries:                   0
  TotalFailed:                    0
  LastMessageProcessed:           4/9/18 8:28:59 PM
------------------------------
WORKER 4 on mq:SendNotification.inq 
STATS for SendNotification:

  TotalNormalMessagesReceived:    6
  TotalPriorityMessagesReceived:  0
  TotalProcessed:                 6
  TotalRetries:                   0
  TotalFailed:                    0
  LastMessageProcessed:           4/9/18 7:41:18 PM
------------------------------
WORKER 5 on mq:SendSystemEmail.inq 
STATS for SendSystemEmail:

  TotalNormalMessagesReceived:    1
  TotalPriorityMessagesReceived:  0
  TotalProcessed:                 1
  TotalRetries:                   0
  TotalFailed:                    0
  LastMessageProcessed:           4/9/18 7:44:47 PM
------------------------------
```


### MQ Collection Stats

You can also get info on the Queue Collection for a specific DTO Type with:

```csharp
var bgService = (BackgroundMqService)HostContext.Resolve<IMessageService>();
var mqCollection = bgService.GetCollection(typeof(Poco));
Dictionary<string, long> statsMap = mqCollection.GetDescriptionMap();
```

Which returns the text info that [mqCollection.GetDescription()](/background-mq#mq-status) returns, but in a structured Dictionary using the keys:

 - `ThreadCount`
 - `TotalMessagesAdded`
 - `TotalMessagesTaken`
 - `TotalOutQMessagesAdded`
 - `TotalDlQMessagesAdded`

The dictionary also includes each the snapshot counts of each queue in the MQ Collection, e.g:

 - `mq:Poco.inq`
 - `mq:Poco.priorityq`
 - `mq:Poco.outq`
 - `mq:Poco.dlq`

You can also get the Stats of each MQ Worker, or if you have multiple workers for a Request Type you can access them with:

```csharp
IMqWorker[] workers = bgService.GetWorkers(QueueNames<Type>.In);
List<IMessageHandlerStats> stats = workers.Map(x => x.GetStats());
```

Then combine them to get their cumulative result:

```csharp
IMessageHandlerStats combinedStats = stats.CombineStats();
```


# Rabbit MQ
Source: https://docs.servicestack.net/rabbit-mq

## Enable in an existing Web App

Use the `rabbitmq` mixin to register an [MQ Server](/messaging) for Amazon SQS with an existing .NET App:

:::sh
x mix rabbitmq
:::

## Worker Service Template

To start usingRabbit MQ in stand-alone MQ Servers (i.e. without HTTP access) is to run the MQ Server in an ASP.NET Core Worker Service by starting from a pre-configured project template:

<worker-templates template="worker-rabbitmq"></worker-templates>

## ServiceStack.RabbitMq

A nice advantage of ServiceStack's message-based design is its ability to host its Services on a variety of different endpoints. This design makes it possible to host Services via [MQ Servers](/messaging), enable [SOAP support](/soap-support) in addition to ServiceStack's strong HTTP Web Services story. One MQ Server we support is the extremely popular and robust Open Source AMQP messaging broker: [Rabbit MQ](http://www.rabbitmq.com).

## Getting Started

A great way to get started with Rabbit MQ on Windows is by following the 
[Rabbit MQ Windows Installation guide](https://github.com/mythz/rabbitmq-windows)
which also includes sample source code for accessing Rabbit MQ Server using the .NET [RabbitMQ.Client](https://www.nuget.org/packages/RabbitMQ.Client) on NuGet.

ServiceStack builds on top of **RabbitMQ.Client** to provide concrete implementations for 
[ServiceStack's high-level Messaging APIs](https://github.com/ServiceStack/ServiceStack/blob/master/src/ServiceStack.Interfaces/Messaging/)
enabling a number of messaging features including publishing and receiving messages as well as registering and processing message handlers. Like other ServiceStack providers, all MQ Servers are interchangeable, visible in the shared common [MqServerIntroTests.cs](https://github.com/ServiceStack/ServiceStack/blob/master/tests/ServiceStack.Server.Tests/Messaging/MqServerIntroTests.cs) and [MqServerAppHostTests.cs](https://github.com/ServiceStack/ServiceStack/blob/master/tests/ServiceStack.Common.Tests/Messaging/MqServerAppHostTests.cs).

![Messaging API](https://raw.github.com/mythz/rabbitmq-windows/master/img/messaging-api.png)

ServiceStack's Rabbit MQ bindings is available on NuGet at:

:::copy
`<PackageReference Include="ServiceStack.RabbitMq" Version="8.*" />`
:::

#### RabbitMqServer

The package includes **RabbitMqServer**, the Rabbit MQ implementation of ServiceStack's MQ
[IMessageService](https://github.com/ServiceStack/ServiceStack/blob/master/src/ServiceStack.Interfaces/Messaging/IMessageService.cs) Server API.

RabbitMqServer is basically a high-level POCO-based MQ server library that's de-coupled and can operate independently from the ServiceStack web framework.
Given this, we're able to learn its functionality by exploring the library on its own. By default, RabbitMqServer looks for a Rabbit MQ Server instance 
on **localhost** at Rabbit MQ's default port **5672**:

```csharp
var mqServer = new RabbitMqServer();
```

Which is equivalent to these other configurations:

```csharp
var mqServer = new RabbitMqServer("localhost");
var mqServer = new RabbitMqServer("localhost:5672");
var mqServer = new RabbitMqServer("amqp://localhost:5672");
```

More connection strings examples are available on [Rabbit MQ's URI Specification](http://www.rabbitmq.com/uri-spec.html) page.

::: info
Run-able examples of these code-samples are available in the [RabbitMqServerIntroTests](https://github.com/ServiceStack/ServiceStack/blob/master/tests/ServiceStack.Server.Tests/Messaging/MqServerIntroTests.cs)
:::

#### Message Filters

There are optional `PublishMessageFilter` and `GetMessageFilter` callbacks which can be used to intercept outgoing and incoming messages. The Type name of the message body that was published is available in `IBasicProperties.Type`, e.g:

```csharp
var mqServer = new RabbitMqServer("localhost") 
{
    PublishMessageFilter = (queueName, properties, msg) => {
        properties.AppId = $"app:{queueName}";
    },
    GetMessageFilter = (queueName, basicMsg) => {
        var props = basicMsg.BasicProperties;
        receivedMsgType = props.Type; //automatically added by RabbitMqProducer
        receivedMsgApp = props.AppId;
    }
};

using (var mqClient = mqServer.CreateMessageQueueClient())
{
    mqClient.Publish(new Hello { Name = "Bugs Bunny" });
}

receivedMsgApp.Print();   // app:mq:Hello.In
receivedMsgType.Print();  // Hello
```

### POCO Messages

Just like the rest of ServiceStack, you can use any POCO for your messages (aka Request DTOs) which are serialized with ServiceStack's JSON Serializer and embedded as the body payload, a simple example is just: 

```csharp
public class Hello
{
    public string Name { get; set; }
}
```

### Registering Message Handlers

Now that we have a message we can use, we can start listening to any of these messages sent via the broker by registering handlers for it.
Here's how to register a simple handler that just prints out each message it receieves:

```csharp
mqServer.RegisterHandler<Hello>(m => {
    Hello request = m.GetBody();
    "Hello, {0}!".Print(request.Name);
    return null;
});
```

Each handler receives an [IMessage](https://github.com/ServiceStack/ServiceStack/blob/master/src/ServiceStack.Interfaces/Messaging/IMessage.cs)
which is just the body of the message that was sent (i.e. `T`) wrapped inside an `IMessage` container containing the metadata of the received message.
Inside your handler you can use `IMessage.GetBody()` to extract the typed body, and in this case we signify the service has no response by returning `null`. 

### Starting the Rabbit MQ Server

Once all your handlers are registered you can start listening to messages by starting the MQ Server:

```csharp
mqServer.Start();
```

Starting the MQ Server spawns 2 threads for each handler, one to listen to the Message Inbox `mq:Hello.inq` and another to listen on the Priority Queue located at `mq:Hello.priorityq`. 

::: info
You can white-list which messages to enable Priority Queue's for with `mqServer.PriorityQueuesWhitelist` or disable them all by setting `mqServer.DisablePriorityQueues = true`.
:::

### Allocating multiple threads for specific operations

By default only 1 thread is allocated to handle each message type, but this is easily configurable at registration. E.g. you can spawn 4 threads to handle a CPU-intensive operation with:

```csharp
mqServer.RegisterHandler<Hello>(m => { .. }, noOfThreads:4);
```

### Publishing messages 

With the mqServer started, you're now ready to start publishing messages, you can do with a message queue client that you can get
from a new **RabbitMqMessageFactory** or the mqServer directly, e.g:

```csharp
using (var mqClient = mqServer.CreateMessageQueueClient())
{
    mqClient.Publish(new Hello { Name = "World" });
}
```

The above shows the most common usage where you can publish POCO's directly, behind the scenes this gets serialized as JSON and embedded as the payload of a new persistent message that's sent using a **routing key** of the same name as the destination queue which by convention is mapped 1:1 to a queue of the same name, i.e: **mq:Hello.inq**. In effect, publishing messages are sent to a distinct **Inbox Queue** that's reserved for each message type, essentially behaving as a work queue.

## Message Workflow

By default, RabbitMqServer will send a response message after it's processed each message, what the response is and which Queue (or HTTP url) the response is published to is dependent on the outcome of the message handler, i.e:

![Rabbit MQ Flowchart](https://docs.google.com/drawings/d/1gsyhAyVxJg37tFlHX1CfwH88OX8Mkt8nTlAIOae1_x0/pub?w=1033&h=653) 

### Messages with no responses are sent to '.outq' Topic

When a handler returns a `null` response, the incoming message is re-published as a "transient" message to the out queue, e.g: `mq:Hello.outq` via the Rabbit MQ "fanout" exchange `mx.servicestack.topic` having the effect of notifying any subscribers to `mq:Hello.outq` each time a message is processed. 

We can use this behavior to block until a message gets processed with:

```csharp
IMessage<Hello> msgCopy = mqClient.Get<Hello>(QueueNames<Hello>.Out);
mqClient.Ack(msgCopy);
msgCopy.GetBody().Name //= World
```

Also shown in this example is an explicit **Ack** (which should be done for each message you receive) to tell Rabbit MQ that you've taken responsibility of the message so it can safely remove it off the queue.

### Messages with Responses are published to the Response .inq

Often message handlers will just return a POCO response after it processes a message, e.g:

```csharp
mqServer.RegisterHandler<Hello>(m =>
    new HelloResponse { Result = $"Hello, {m.GetBody().Name}!" });
```

Whenever there's a response, then instead of the .outq the response message is sent to the **.inq** of the response message type, which for a `HelloResponse` type is just **mq:HelloResponse.inq**, e.g:

```csharp
mqClient.Publish(new Hello { Name = "World" });

var responseMsg = mqClient.Get<HelloResponse>(QueueNames<HelloResponse>.In);
mqClient.Ack(responseMsg);
responseMsg.GetBody().Result //= Hello, World!
```

::: info
this behavior can be limited to only publish responses for types in the `mqServer.PublishResponsesWhitelist`, otherwise all response messages can be disabled entirely by setting `mqServer.DisablePublishingResponses = true`.
:::

### Responses from Messages with ReplyTo are published to that address

Whilst for the most part you'll only need to publish POCO messages, you can also alter the default behavior by providing a customized `IMessage<T>` wrapper which ServiceStack will send instead, e.g. you can specify your own **ReplyTo** address to change the queue where the response gets published, e.g:

```csharp
const string replyToMq = mqClient.GetTempQueueName();
mqClient.Publish(new Message<Hello>(new Hello { Name = "World" }) {
    ReplyTo = replyToMq
});

IMessage<HelloResponse> responseMsg = mqClient.Get<HelloResponse>(replyToMq);
mqClient.Ack(responseMsg);
responseMsg.GetBody().Result //= Hello, World!
```

#### ReplyTo addresses can be URLs

A nice feature unique in ServiceStack is that the ReplyTo address can even be a **HTTP Uri**, in which case ServiceStack will attempt to **POST** the raw response at that address. This works nicely with ServiceStack Services which excel at accepting serialized DTO's.

```csharp
mqClient.Publish(new Message<Hello>(new Hello { Name = "World" }) {
    ReplyTo = "http://example.org/hello/callback"
});
```

### Messages that generate exceptions can be re-tried, then published to the dead-letter-queue (.dlq)

By default Rabbit Mq Server lets you specify whether or not you want messages that cause an exception to be retried by specifying a RetryCount of 1 (default), or if you don't want any messages re-tried, specify a value of 0, e.g:

```csharp
var mqServer = new RabbitMqServer { RetryCount = 1 };
```

To illustrate how this works we'll keep a counter of how many times a message handler is invoked, then throw an exception to force an error condition, e.g:

```csharp
var called = 0;
mqServer.RegisterHandler<Hello>(m => {
    called++;
    throw new ArgumentException("Name");
});
```

Now when we publish a message the response instead gets published to the messages **.dlq**, after it's first transparently retried. We can verify this behavior by checking `called=2`:

```csharp
mqClient.Publish(new Hello { Name = "World" });

IMessage<Hello> dlqMsg = mqClient.Get<Hello>(QueueNames<Hello>.Dlq);
mqClient.Ack(dlqMsg);

Assert.That(called, Is.EqualTo(2));
```

DLQ Messages retains the original message in their body as well as the last exception serialized in the `IMessage.Error` ResponseStatus metadata property, e.g:

```csharp
dlqMsg.GetBody().Name   //= World
dlqMsg.Error.ErrorCode  //= typeof(ArgumentException).Name
dlqMsg.Error.Message    //= Name
```

Since the body of the original message is left in-tact, you're able to retry failed messages by removing them from the dead-letter-queue then re-publishing the original message, e.g:

```csharp
IMessage<Hello> dlqMsg = mqClient.Get<Hello>(QueueNames<Hello>.Dlq);

mqClient.Publish(dlqMsg.GetBody());

mqClient.Ack(dlqMsg);
```

This is useful for recovering failed messages after identifying and fixing bugs that were previously causing exceptions, where you can replay and re-process DLQ messages and continue processing them as normal.

## Adding Rabbit MQ support to ServiceStack

Whilst `RabbitMqServer` is useful on its own, it also has the distinct advantage of being able to directly Execute ServiceStack Services which you can do by just routing the handler for each **Request DTO** you want to process through to ServiceStack's AppHost **ExecuteMessage**, e.g:

```csharp
public class AppHost : AppHostHttpListenerBase
{
    public AppHost() : base("Rabbit MQ Test Host", typeof(HelloService).Assembly) {}

    public override void Configure(Container container)
    {
        container.Register<IMessageService>(c => new RabbitMqServer());

        var mqServer = container.Resolve<IMessageService>();

        mqServer.RegisterHandler<Hello>(ExecuteMessage);
        mqServer.Start();
    }
}
```

Now each message will instead be executed by the best matching ServiceStack Service that handles the message with either a **Post** or **Any** fallback verb, e.g:

```csharp
public class HelloService : Service
{
    public object Any(Hello request)
    {
        return new HelloResponse { Result = $"Hello, {request.Name}!" };
    }
}
```

In addition to executing your service implementation, all Services processed via a MQ Server goes through ServiceStack's standard [MQ Request Pipeline](/order-of-operations#wiki-mq-non-http-custom-hooks).

With everything in place, initialize ServiceStack's AppHost to start the Rabbit MQ Server to listen for any messages published to the Request DTO's **.inq**:

```csharp
var appHost = new AppHost().Init();

using (var mqClient = appHost.Resolve<IMessageService>().CreateMessageQueueClient())
{
    mqClient.Publish(new Hello { Name = "World" });

    var responseMsg = mqClient.Get<HelloResponse>(QueueNames<HelloResponse>.In);
    mqClient.Ack(responseMsg);
    responseMsg.GetBody().Result //= Hello, World!     
}
```

### Process ServiceStack MQ Services without a HTTP host

Whilst it's unlikely to be a common use-case, you can even run a ServiceStack MQ Server without a HTTP host by configuring the mqServer inside the generic BasicAppHost, e.g: 

```csharp
var appHost = new BasicAppHost(typeof(HelloService).Assembly) {
    ConfigureAppHost = host => {
        host.Container.Register<IMessageService>(c => new RabbitMqServer());

        var mqServer = host.Container.Resolve<IMessageService>();

        mqServer.RegisterHandler<Hello>(host.ExecuteMessage);
        mqServer.Start();
    }
}.Init();

using (var mqClient = appHost.Resolve<IMessageService>().CreateMessageQueueClient())
{
    mqClient.Publish(new Hello { Name = "World" });

    var msg = mqClient.Get<HelloResponse>(QueueNames<HelloResponse>.In);
    mqClient.Ack(msg);
    Assert.That(msg.GetBody().Result, Is.EqualTo("Hello, World!"));
}
```

In this way, ServiceStack's AppHost is being used as a pure "logic server", hosting auto-wired services within [its MQ Request Pipeline](/order-of-operations#wiki-mq-non-http-custom-hooks), whilst taking advantage of ServiceStack's flexibility and extensibility options and its plugin ecosystem.

Run-able examples of these code-samples are available in the [RabbitMqServerIntroTests](https://github.com/ServiceStack/ServiceStack/blob/master/tests/ServiceStack.Server.Tests/Messaging/MqServerIntroTests.cs#L13).

### Rabbit MQ Filters

The new `CreateQueueFilter` and `CreateTopicFilter` filters let you customize what options Rabbit MQ Queue's and topics are created with. The filters can be used to [declare a queue with a custom TTL](https://www.rabbitmq.com/ttl.html) and have messages automatically expire after 60 seconds with:

```csharp
container.Register<IMessageService>(c => new RabbitMqServer(ConnectionString) {
    CreateQueueFilter = (queueName, args) => {
        if (queueName == QueueNames<MyRequest>.In)
            args["x-message-ttl"] = 60000;
    }
});
```

## Rabbit MQ Features

The [Rabbit MQ Server](https://github.com/ServiceStack/ServiceStack/blob/master/src/ServiceStack.RabbitMq/RabbitMqServer.cs) have some configuration options that are unique to Rabbit MQ:

  - `ConnectionFactory` **ConnectionFactory** - The [RabbitMQ.Client](https://github.com/mythz/rabbitmq-windows) Connection factory to introspect connection properties and create low-level connections
  - `bool` **AutoReconnect** - Whether Rabbit MQ should auto-retry connecting when a connection to Rabbit MQ Server instance is dropped
  - `bool` **UsePolling** - Whether to use polling for consuming messages instead of a long-term subscription
  - `int` **RetryCount** - How many times a message should be retried before sending to the DLQ. Valid range for Rabbit MQ: 0-1.

In addition to sharing a similar architecture to [Redis MQ](/redis-mq), it also shares a number of common features:

  - `int?` **KeepAliveRetryAfterMs** - Wait before Starting the MQ Server after a restart
  - `IMessageFactory` **MessageFactory** - The MQ Message Factory used by this MQ Server
  - `Func<IMessage, IMessage>` **RequestFilter** - Execute global transformation or custom logic before a request is processed. Must be thread-safe.
  - `Func<object, object>` **ResponseFilter** - Execute global transformation or custom logic on the response. Must be thread-safe.
  - `Action<Exception>` **ErrorHandler** - Execute global error handler logic. Must be thread-safe.
  - `string[]` **PriorityQueuesWhitelist** - If you only want to enable priority queue handlers (and threads) for specific msg types.
  - `bool` **DisablePriorityQueues** - Don't listen on any Priority Queues
  - `string[]` **PublishResponsesWhitelist** - Opt-in to only publish responses on this white list. Publishes all responses by default.
  - `bool` **DisablePublishingResponses** - Don't publish any response messages


# Redis MQ
Source: https://docs.servicestack.net/redis-mq

## Enable in an existing Web App

Use the `redismq` mixin to register an [MQ Server](/messaging) for Amazon SQS with an existing .NET App:

:::sh
x mix redismq
:::

## Worker Service Template

To start using Redis MQ in stand-alone MQ Servers (i.e. without HTTP access) is to run the MQ Server in an ASP.NET Core Worker Service by starting from a pre-configured project template:

<worker-templates template="worker-redismq"></worker-templates>

## MQ Examples

The [Reusability ServiceStack.UseCase](https://github.com/ServiceStack/ServiceStack.UseCases/tree/master/Reusability) contains a good introductory demo of using MQ's(message-queues) in ServiceStack where the same services can be called via Web Service or via MQ. Using MQ's provide instant response times, in addition to reliable and durable execution of your services. 

### The SMessage Service 

The [SMessage Service](https://github.com/ServiceStack/ServiceStack.UseCases/blob/master/Reusability/SMessageService.cs#L63) shows an example of dividing a service into multiple subtasks and dispatching them for instant response times and parallel processing of blocking operations without needing any multi-threading code in your application logic, e.g:

```csharp
public object Any(SMessage request)
{
    var sw = Stopwatch.StartNew();
    if (!request.Defer) //Process sequentially or Defer execution
    {
        //Executes service sequentially: N+1 service calls, times out if N too big
        var results = new List<SMessageReceipt>();
        results.AddRange(Email.Send(request));
        results.AddRange(FacebookR.Send(request));
        results.AddRange(Twitter.Send(request));
        Db.InsertAll(results);
    }
    else
    {
        //Split in smaller tasks and defers messages in MQ broker for parallel processing
        Email.CreateMessages(request).ForEach(MessageProducer.Publish);
        Facebook.CreateMessages(request).ForEach(MessageProducer.Publish);
        Twitter.CreateMessages(request).ForEach(MessageProducer.Publish);
    }

    return new SMessageResponse {
        TimeTakenMs = sw.ElapsedMilliseconds,
    };
}
```

#### Process each service concurrently without holding up the processing of other tasks
Another benefit of dispatching messages into multiple sub tasks is if the Email API is slow, it doesn't hold up the processing of the other tasks which are all running concurrently in the background each individually processing messages as fast as they can.

#### Easily Parallelize and Multiply your services throughput
The RedisMqServer also supports spawning any number of background threads for individual requests, so if Posting to twitter was an IO intensive operation you can double the throughput by simply assigning 2 or more worker threads, e.g:

```csharp
mqService.RegisterHandler<PostStatusTwitter>(ExecuteMessage, noOfThreads:2);
mqService.RegisterHandler<CallFacebook>(ExecuteMessage);
mqService.RegisterHandler<EmailMessage>(ExecuteMessage);
```

## Redis MQ Client / Server

A redis-based message queue client/server that can be hosted in any .NET or ASP.NET application. All Redis MQ Hosts lives in the [ServiceStack.Server](https://github.com/ServiceStack/ServiceStack/tree/master/src/ServiceStack.Server/Messaging/Redis) project and brings the many benefits of using a Message Queue. 

:::copy
`<PackageReference Include="ServiceStack.Server" Version="8.*" />`
:::

#### [RedisMqServer](https://github.com/ServiceStack/ServiceStack/tree/master/src/ServiceStack.Server/Messaging/Redis/RedisMqServer.cs)

Works by using a background thread for **each service**. This allows you to process messages from different services concurrently. Recommended if you have any long-running services so other services can still run in parallel.

Major kudos goes to Redis which thanks to its versatility, has Pub/Sub and Lists primitives that makes implementing a Queue trivial.

## MQ Architecture in ServiceStack

The logical architecture of how a MQ Publisher and MQ Host works together in ServiceStack:

![ServiceStack MQ Client Architecture](/img/pages/messaging/servicestack-mqclients.png) 

### Easily testable and swappable

All MQ implementations share the same [IMessageService](https://github.com/ServiceStack/ServiceStack/blob/master/src/ServiceStack.Interfaces/Messaging/IMessageService.cs) so they're easily swappable and testable. There is also an [InMemoryTransientMessageService](https://github.com/ServiceStack/ServiceStack/blob/master/src/ServiceStack/Messaging/InMemoryTransientMessageService.cs) available, useful for development & testing.

These versions already sports the major features you've come to expect from a MQ:

  - Each service maintains its own Standard and Priority MQ's
  - Automatic Retries on messages generating errors with Failed messages sent to a DLQ (Dead Letter Queue) when its Retry threshold is reached.
  - Each message can have a ReplyTo pointing to any Queue, alternatively you can even provide a **ServiceStack endpoint URL** which will send the response to a Web Service instead. If the web service is not available it falls back into publishing it in the default Response Queue so you never lose a message!
MQ/Web Services that don't return any output have their Request DTOs sent to a rolling Out queue which can be monitored by external services (i.e. the publisher/callee) to determine when the request has been processed.

## Re-use your existing Web Services!

Although you can host RedisMqServer in any ASP.NET web app, the benefit of hosting inside ServiceStack is that your web services are **already capable** of processing Redis MQ messages **without any changes required** since they're already effectively designed to work like a Message service to begin with, i.e. C# POCO-in -> C# POCO-out.

This is another example of how ServiceStack's prescribed DTO-first architecture continues to pay dividends since each web service is a DI clean-room allowing your C# logic to be kept pure as it only has to deal with untainted POCO DTOs, allowing your same web service to be re-used in: SOAP, REST (JSON,XML,JSV,CSV,HTML) web services, view models for dynamic HTML pages and now as a MQ service!

## Example

Hooking up a basic send/reply example is as easy as:

```csharp
//DTO messages:
public class Hello { public string Name { get; set; } }
public class HelloResponse { public string Result { get; set; } }

var redisFactory = new PooledRedisClientManager("localhost:6379");
var mqHost = new RedisMqServer(redisFactory, retryCount:2);

//Server - MQ Service Impl:
mqHost.RegisterHandler<Hello>(m =>
    new HelloResponse { Result = "Hello, " + m.GetBody().Name });
mqHost.Start();

...

//Client - Process Response:
mqHost.RegisterHandler<HelloResponse>(m => {
    Console.WriteLine("Received: " + m.GetBody().Result);
});
mqHost.Start();

...

//Producer - Start publishing messages:
var mqClient = mqHost.CreateMessageQueueClient();
mqClient.Publish(new Hello { Name = "ServiceStack" });

```

## Redis

::: info
This is a quote of a [google group topic](https://groups.google.com/d/msg/servicestack/Jl1xjlLH-4E/kz8mL_bq9zMJ) to provide more information about ServiceStack and Redis until more documentation/examples are added
:::

Redis is a  NoSQL datastore that runs as a network server. To start it you need to run an instance of redis-server either locally or remotely accessible.

Probably will help to understand the background concepts behind Redis so you can get a better idea of how it works. This StackOverflow answer has a [good overview about Redis in .NET](http://stackoverflow.com/a/2760282/85785).

The `RedisMqServer` is in [ServiceStack.Server](https://www.nuget.org/packages/ServiceStack.Server) project and can be installed with:

:::copy
`<PackageReference Include="ServiceStack.Server" Version="8.*" />`
:::

Redis MQ works by listening for messages published to the central `mq:topic:in` Redis Channel and processes any messages sent in separate background threads which are started from inside your AppHost when calling `RedisMqServer.Start()`.

For duplex communication each client and server will require its own AppHost + RedisMqServer Host, although unless your server is going to call HTTP services on the client you can use a [BasicAppHost](https://github.com/ServiceStack/ServiceStack/blob/master/src/ServiceStack/Testing/BasicAppHost.cs).

Here is a simple example of a client/server with HTTP + RedisMQ enabled on the server, and just RedisMQ on the client: 

#### Shared.cs

```csharp
using System;

namespace TestMqShared
{
    public class Hello { 
        public string Name { get; set; } 
    }
    public class HelloResponse { 
        public string Result { get; set; } 
    }
}
```

#### Server.cs

```csharp
using System;
using Funq;
using ServiceStack;
using ServiceStack.Messaging.Redis;
using ServiceStack.Redis;
using ServiceStack.Testing;
using TestMqShared;

namespace TestMq
{
    //Server
    public class HelloService : Service 
    {
        public object Any(Hello req) 
        { 
            return new HelloResponse { Result = "Hello, " + req.Name }; 
        }
    }

    public class ServerAppHost : AppHostHttpListenerBase 
    {
        public ServerAppHost() : base("Test Server", typeof(HelloService).Assembly) {}

        public override void Configure(Container container) 
        {
            base.Routes
                .Add<Hello>("/hello")
                .Add<Hello>("/hello/{Name}");

            var redisFactory = new PooledRedisClientManager("localhost:6379");
            container.Register<IRedisClientsManager>(redisFactory); 
            var mqHost = new RedisMqServer(redisFactory, retryCount:2);

            //Server - MQ Service Impl:

            //Listens for 'Hello' messages sent with: mqClient.Publish(new Hello { ... })
            mqHost.RegisterHandler<Hello>(base.ExecuteMessage);
            mqHost.Start(); //Starts listening for messages
        }
    }

    class MainClass
    {
        public static void Main(string[] args)
        {
            var serverAppHost = new ServerAppHost();
            serverAppHost.Init(); 
            serverAppHost.Start("http://localhost:1400/");
            Console.WriteLine("Server running.  Press enter to terminate...");
            //Prevent server from exiting (when running in ConsoleApp)
            Console.ReadLine(); 
        }
    }
}
```

#### Client.cs

```csharp
using System;
using Funq;
using ServiceStack;
using ServiceStack.Messaging;
using ServiceStack.Messaging.Redis;
using ServiceStack.Redis;
using ServiceStack.Testing;
using TestMqShared;

namespace TestMqCli
{
    class MainClass
    {
        public static void Main(string[] args)
        {
            var redisFactory = new PooledRedisClientManager("localhost:6379");
            var mqServer = new RedisMqServer(redisFactory, retryCount:2);

            //Client - MQ Service Impl:
            //Listens for 'HelloResponse' returned by the 'Hello' Service
            mqServer.RegisterHandler<HelloResponse>(m => {  
                Console.WriteLine("Received: " + m.GetBody().Result);
                // See comments below
                // m.Options = (int)MessageOption.None;
                return null;
            });

            //or to call an existing service with:
            //mqServer.RegisterHandler<HelloResponse>(m =>   
            //    this.ServiceController.ExecuteMessage(m));

            mqServer.Start(); //Starts listening for messages

            var mqClient = mqServer.CreateMessageQueueClient();
            mqClient.Publish(new Hello { Name = "Client 1" });

            Console.WriteLine("Client running.  Press any key to terminate...");
            Console.ReadLine(); //Prevent self-hosted Console App from exiting
        }
    }
}
```

The first RedisMQ host listening to the `Hello` message (i.e. the server) will process the message. 

When the server returns a 'HelloResponse' message it gets put on the 'HelloResponse' Inbox Queue and the first RedisMQ Host listening to the 'HelloResponse' message (i.e. Client) will have their callback fired.

Note that the `HelloResponse` will get put back on a 'transient' message queue, `mq.HelloResponse.outq` with a maximum message limit of 100 (by default).  You can subscribe to this queue to get a notification and do further processing, such as recording the number of messages handled.  Or you can clear the message `NotifyOneWay` option to prevent this.

### RedisMQ Client

Clients can use a `RedisMessageProducer` to be able to publish a message, e.g:

```csharp
var redisManager = new RedisManagerPool("localhost:6379");
using (var mqClient = new RedisMessageProducer(redisManager))
{
    mqClient.Publish(new Hello { Name = "Client 1" });
}
```

Or if preferred can instead use a `RedisMessageFactory` which provide access to both [IMessageQueueClient](https://github.com/ServiceStack/ServiceStack/blob/master/src/ServiceStack.Interfaces/Messaging/IMessageQueueClient.cs) and [IMessageProducer](https://github.com/ServiceStack/ServiceStack/blob/master/src/ServiceStack.Interfaces/Messaging/IMessageProducer.cs):

```csharp
IMessageFactory redisMqFactory = new RedisMessageFactory(redisManager);
using (var mqClient = redisMqFactory.CreateMessageQueueClient())
{
    mqClient.Publish(new Hello { Name = "Client 1" });
}
```

### Request + Reply MQ Pattern

However MQ's are normally used for async OneWay messages as any client host listening to 'HelloResponse' could receive the response message, and only 1 will, which is not guaranteed to be the client that sent the original message. For this reason you want to make use of the ReplyTo field of the Message for Request/Reply responses.

```csharp
var uniqueCallbackQ = "mq:c1" + ":" Guid.NewGuid().ToString("N");
var clientMsg = new Message<Hello>(new Hello { Name = "Client 1" }) {
   ReplyTo =  uniqueCallbackQ
};
mqClient.Publish( clientMsg );
//Blocks thread on client until reply message is received
var response = mqClient.Get(clientMsg).ToMessage<HelloResponse>();  
```


Note: The ReplyTo callback url could also be a ServiceStack endpoint that expects a 'HelloResponse' e.g.

```csharp
var clientMsg = new Message<Hello>(new Hello { Name = "Client 1" }) {
   ReplyTo =  "http://clienthost:82/helloresponse"
};
```

In this case the server wont put the response message on the back on the MQ and will instead send the response directly to your client web service host.

There's a few MQ concepts covered above here, I invite you to do your own reading on MQ's in general as it works a little different to normal request/reply web services.

See Also: [Redis Commands (PDF)](http://masonoise.files.wordpress.com/2010/03/redis-cheatsheet-v1.pdf)


# Amazon SQS MQ
Source: https://docs.servicestack.net/amazon-sqs-mq

## Enable in an existing Web App

Use the `sqs` mixin to register an [MQ Server](/messaging) for Amazon SQS with an existing .NET App:

:::sh
x mix sqs
:::

## Worker Service Template

To start using Amazon SQS in stand-alone MQ Servers (i.e. without HTTP access) is to run the MQ Server in an ASP.NET Core Worker Service by starting from a pre-configured project template:

<worker-templates template="worker-sqs"></worker-templates>

## Manual Configuration

Support for registering Amazon Simple Queue Service (SQS) as an [MQ Server](/messaging) is available in [ServiceStack.Aws](https://www.nuget.org/packages/ServiceStack.Aws) NuGet package:

:::copy
`<PackageReference Include="ServiceStack.Aws" Version="8.*" />`
:::

Once installed SQS can be configured the same way as any other [MQ Servers](/messaging), by first registering the ServiceBus `IMessageService` provider followed by registering all ServiceStack Services you want to be able to invoke via MQ’s:

```csharp
container.Register<IMessageService>(c => new SqsMqServer(
    AwsConfig.AwsAccessKey, AwsConfig.AwsSecretKey, RegionEndpoint.USEast1) {
    DisableBuffering = true, // Trade-off latency vs efficiency
});

var mqServer = container.Resolve<IMessageService>();
mqServer.RegisterHandler<MyRequest>(ExecuteMessage);

AfterInitCallbacks.Add(appHost => mqServer.Start());
```

When an MQ Server is registered, ServiceStack automatically publishes Requests accepted on the "One Way" [pre-defined route](/routing#pre-defined-routes) to the registered MQ broker. The message is later picked up and executed by a Message Handler on a background Thread.

## SQS MQ Server Example

The [AWS Email Contacts](https://github.com/ServiceStackApps/AwsApps/tree/master/src/AwsApps/emailcontacts) example shows the same long-running 
[EmailContact Service](https://github.com/ServiceStackApps/AwsApps/blob/4817f5c6ad69defd74d528403bfdb03e5958b0b3/src/AwsApps/emailcontacts/EmailContactServices.cs#L81)
being executed from both HTTP and MQ Server by just 
[changing which url the HTML Form is posted to](https://github.com/ServiceStackApps/AwsApps/blob/4817f5c6ad69defd74d528403bfdb03e5958b0b3/src/AwsApps/emailcontacts/default.cshtml#L203):

```html
//html
<form id="form-emailcontact" method="POST"
    action="@(new EmailContact().ToPostUrl())" 
    data-action-alt="@(new EmailContact().ToOneWayUrl())">
    ...
    <div>
        <input type="checkbox" id="chkAction" data-click="toggleAction" />
        <label for="chkAction">Email via MQ</label>
    </div>
    ...   
</form>
```

> The urls are populated from a typed Request DTO using the [Reverse Routing Extension methods](/routing#reverse-routing)

Checking the **Email via MQ** checkbox fires the JavaScript handler below that's registered as [declarative event in ss-utils.js](/ss-utils-js#declarative-events):

```js
$(document).bindHandlers({
    toggleAction: function() {
        var $form = $(this).closest("form"), action = $form.attr("action");
        $form.attr("action", $form.data("action-alt"))
                .data("action-alt", action);
    }
});
```

The code to configure and start an SQS MQ Server is similar to [other MQ Servers](/messaging): 

```csharp
container.Register<IMessageService>(c => new SqsMqServer(
    AwsConfig.AwsAccessKey, AwsConfig.AwsSecretKey, RegionEndpoint.USEast1) {
    DisableBuffering = true, // Trade-off latency vs efficiency
});

var mqServer = container.Resolve<IMessageService>();
mqServer.RegisterHandler<EmailContacts.EmailContact>(ExecuteMessage);

AfterInitCallbacks.Add(appHost => mqServer.Start());
```

## Intercepting Filters

A number of new filters are available on `SqsMqServer` and `SqsMqClient` which will let you intercept and apply custom logic before SQS messages are 
sent and received:

```csharp
Action<SendMessageRequest,IMessage> SendMessageRequestFilter
Action<ReceiveMessageRequest> ReceiveMessageRequestFilter
Action<Amazon.SQS.Model.Message, IMessage> ReceiveMessageResponseFilter
Action<DeleteMessageRequest> DeleteMessageRequestFilter
Action<ChangeMessageVisibilityRequest> ChangeMessageVisibilityRequestFilter
```

## Polling Duration

The polling duration used to poll SQS queues can be configured with:

```csharp
new SqsMqServer {
    PollingDuration = TimeSpan.FromMilliseconds(1000) //default
}
```


# Azure Service Bus MQ
Source: https://docs.servicestack.net/azure-service-bus-mq

## Enable in an existing Web App

Use the `servicebus` mixin to register an [MQ Server](/messaging) for Azure Service Bus with an existing .NET App:

:::sh
x mix servicebus
:::

## Worker Service Template

To start using Azure Service Bus in stand-alone MQ Servers (i.e. without HTTP access) is to run the MQ Server in an ASP.NET Core Worker Service by starting from a pre-configured project template:

<worker-templates template="worker-servicebus"></worker-templates>

## Manual Configuration

Support for registering Azure Service Bus as an [MQ Server](/messaging) in ServiceStack is available in [ServiceStack.Azure](https://www.nuget.org/packages/ServiceStack.Azure) NuGet package:

:::copy
`<PackageReference Include="ServiceStack.Azure" Version="8.*" />`
:::

Once installed ServiceBus can be configured the same way as any other [MQ Servers](/messaging), by first registering the ServiceBus `IMessageService` provider followed by registering all ServiceStack Services you want to be able to invoke via MQ’s:

```csharp
[assembly: HostingStartup(typeof(MyApp.ConfigureMq))]

namespace MyApp;

public class ConfigureMq : IHostingStartup
{
    public void Configure(IWebHostBuilder builder) => builder
        .ConfigureServices((context, services) => {
            services.AddSingleton<IMessageService>(c => 
                new ServiceBusMqServer(context.Configuration.GetConnectionString("ServiceBus")));
        })
        .ConfigureAppHost(afterAppHostInit: appHost => {
            var mqServer = appHost.Resolve<IMessageService>().Start();
            // Register MQ endpoints for APIs
            mqServer.RegisterHandler<MyRequest>(ExecuteMessage);
            mqServer.Start();
        });
}
```


# Jupyter Notebooks
Source: https://docs.servicestack.net/jupyter-notebooks

[![](./img/pages/apps/jupyter-splash.png)](https://jupyter.org)

Initially forged from the [Interactive Python](https://ipython.org) project, [Jupyter](https://jupyter.org) is an exciting initiative to support an open standards, language agnostic interactive computing platform where it provides the ideal integrated exploratory programming environment for data science and scientific computing as represented by its 3 core languages for these domains in [Julia](https://julialang.org), [Python](https://python.org) and [R](https://www.r-project.org) (Ju-Py-R).

However its popularity, thriving ecosystem and rich tooling has seen it grow to encompass a wide range of interactive computing use-cases including data cleaning and transformation, numerical simulation, statistical modeling, data visualization, machine learning, and much more which now sees it support **over 40 programming languages**.

## Jupyter Notebooks

At the core of Jupyter is the "Notebook" (Nb) - an open JSON document format that contains a complete record of user's sessions including code, narrative text, equations, visualizations and rich output. The culmination of which facilitates the creation and sharing of Live Executable Documents encapsulating an Interactive computing session that provides an ideal visual REPL environment for exploratory programming whose results and findings can be further annotated with Markdown documentation and exported in a number of formats to facilitate knowledge sharing including: HTML, PDF, Markdown, Latex, ReStructured Text, Asciidoc, Reveal.js.

## Create Python, C# and F# Jupyter Notebooks for any ServiceStack API

<lite-youtube class="w-full mx-4 my-4" width="560" height="315" videoid="h6UwDuXt8MA" style="background-image: url('https://img.youtube.com/vi/h6UwDuXt8MA/maxresdefault.jpg')"></lite-youtube>

By leveraging [Add ServiceStack Reference's](/add-servicestack-reference) rich, typed ecosystem we're able to tap into the exciting interactive world of Jupyter Notebooks where ServiceStack API consumers are now able to generate custom-tailored notebooks for ServiceStack API using a [Simple UI](https://apps.servicestack.net) or generated from a single command-line if preferred.

Generating Python Notebooks with [Python ServiceStack Reference](/python-add-servicestack-reference) will let you get the most out of Jupyter Notebooks ecosystem, tooling and free hosting cloud services. 

Alternatively .NET Teams can use [.NET Interactive ](https://github.com/dotnet/interactive) Kernels and [Notebooks VSCode extension](https://marketplace.visualstudio.com/items?itemName=ms-dotnettools.dotnet-interactive-vscode) to generate and execute C# and F# Notebooks:

[![](./img/pages/apps/notebook-py.png)](/jupyter-notebooks-python)
[![](./img/pages/apps/notebook-cs.png)](/jupyter-notebooks-csharp)
[![](./img/pages/apps/notebook-fs.png)](/jupyter-notebooks-fsharp)

## Notebook Apps

The core UX for experiencing Jupyter Notebooks is through a Notebook App which thanks to Jupyter's momentum and vibrant ecosystem there are now many options to choose from, optimizing for different developers use-cases and integrated development workflows.

Delivered and maintained as part of the Jupyter project are 2 self-hosted front-end Web Application UIs for authoring and running Notebooks:

### JupyterLab

JupyterLab is Jupyter's next-gen web-based development environment designed around maintaining an entire Workspace of Notebooks in a multi-tabbed splittable UI whereby many of them can be running at the same time:

![](./img/pages/apps/jupyter-labpreview.png)

An easy way to install JupyterLab is to use the pip package manager installed with Python:

:::sh
pip install jupyterlab
:::

Once installed you can launch JupyterLab's UI from a directory containing your Notebooks where they'll be accessible from its built-in File Explorer UI:

:::sh
jupyter-lab
:::

### Jupyter Notebook

The original Jupyter Notebook Web Application offering a simplified single document UI:

![](./img/pages/apps/jupyter-notebook-preview.png)

Install with Python's pip package manager:

:::sh
pip install notebook
:::

Then launch from any directory containing Notebooks to open them from the Jupyter Notebook App:

:::sh
jupyter notebook
:::

### PyCharm

JetBrains likely offers the most functional and capable IDEs for authoring and viewing Notebooks whose [Notebook support](https://www.jetbrains.com/help/pycharm/jupyter-notebook-support.html) is built-in to their leading Python IDE - [PyCharm](https://www.jetbrains.com/pycharm/).

In addition to all the source code assistance and analysis you can expect from JetBrains smart IDEs to assist in writing Python, it also supports debugging as well as multiple edit and preview modes. 

![](./img/pages/apps/jupyter-pycharm.png)

PyCharm is ideal for Python programmers and maintaining Notebooks as part of a Python project where it takes care of creating a Python virtual environment for the project, installing required local dependencies and executing Notebooks within the projects venv context.

#### JetBrains DataSpell

Jupyter's popularity with Data Scientists has prompted JetBrains to develop a [stand-alone DataSpell IDE](https://www.jetbrains.com/dataspell/) optimized for working with Data with a more refined lightweight UX for working with Notebooks:

![](./img/pages/apps/jupyter-dataspell.png)

### VS Code

Visual Studio Code is another IDE popular with Python Developers that has their own [built-in UX for Jupyter Notebooks](https://code.visualstudio.com/docs/datascience/jupyter-notebooks):

![](./img/pages/apps/jupyter-vscode.png)

It provides a nicer UX over the traditional Notebook UX with niceties like intelli-sense and variable explorer and is better at opening stand-alone Notebooks outside the context of a Python project where its able to make use of pip's global OS packages.

Whilst its Python notebook support is still the most complete, it's the optimal UI for working with **C# and F# Notebooks** with its [.NET Interactive Notebooks](https://marketplace.visualstudio.com/items?itemName=ms-dotnettools.dotnet-interactive-vscode) extension, currently in Preview that's maintained as part of the [github.com/dotnet/interactive](https://github.com/dotnet/interactive) project.

## Cloud Notebook Services

The proliferation of Notebooks as an interactive computing platform, popular in machine learning, data analysis and education has spawned a number of cloud services to facilitate the management, authoring and sharing of Notebooks where as they're run and hosted in the cloud can be easily shared with anyone without requiring a local install or development environment.

### Binder

The JupyterHub team maintain their public Jupyter notebooks service at [mybinder.org](https://mybinder.org) for anyone who wants to share their interactive GitHub repositories publicly. Behind the scenes Notebooks are executed on a collection of [BinderHub Federated services](https://mybinder.readthedocs.io/en/latest/about/federation.html) using resources donated by  [Google Cloud](https://cloud.google.com), [OVH](https://www.ovh.com), [GESIS Notebooks](https://notebooks.gesis.org) and the [Turing Institute](https://turing.ac.uk).

To run your Notebooks on Binder head over to https://mybinder.org and paste the URL of your public GitHub repo containing your Jupyter Notebooks to retrieve the generated URL for your repo.

E.g. our [ServiceStack/jupyter-notebooks](https://github.com/ServiceStack/jupyter-notebooks) GitHub repo is available from:

#### [https://mybinder.org/v2/gh/ServiceStack/jupyter-notebooks/HEAD](https://mybinder.org/v2/gh/ServiceStack/jupyter-notebooks/HEAD)

Where behind-the-scenes Binder will build and host a Docker image of your repo and launch a dedicated `notebook` Web App instance to view an execute your repo's Notebooks:

[![](./img/pages/apps/jupyterlab-mybinder-repo.png)](https://mybinder.org/v2/gh/ServiceStack/jupyter-notebooks/HEAD)

The [ServiceStack/jupyter-notebooks](https://github.com/ServiceStack/jupyter-notebooks) repo contains a couple of API examples generated using our [Instant Client Apps](https://apps.servicestack.net) site to craft a [QueryVaccinationRates API](https://apps.servicestack.net/#covid-vac-watch.netcore.io/python/QueryVaccinationRates(Location:Arizona)) call that can be downloaded in a **Python Notebook**:

[![](./img/pages/apps/apps-covid-vac-QueryVaccinationRates.png)](https://apps.servicestack.net/#covid-vac-watch.netcore.io/python/QueryVaccinationRates(Location:Arizona))

### Covid Vaccinations

In addition to previewing the raw data response in human-friendly markdown and HTML tables, you can also leverage Python's powerful [pandas](https://pandas.pydata.org) and [matplotlib](https://matplotlib.org) libraries to plot a quick visualization of the typed `QueryVaccinationRates` AutoQuery response:

[![](./img/pages/apps/jupyterlab-mybinder-covid-vac.png)](https://github.com/ServiceStack/jupyter-notebooks/blob/main/covid-vac-watch.netcore.io.ipynb)

### TechStacks

The [techstacks.io-FindTechnologies.ipynb](https://github.com/ServiceStack/jupyter-notebooks/blob/main/techstacks.io-FindTechnologies.ipynb) is an example of a Notebook generated by [apps.servicestack.net](https://apps.servicestack.net) which displays results in a HTML table and a human-friendly markdown table for API Responses containing a `Results` resultset, e.g:

[![](./img/pages/apps/apps-techstacks-FindTechnologies.png)](https://apps.servicestack.net/#techstacks.io/python/AutoQuery/FindTechnologies(Ids:[1,2,4,6],VendorName:Google,Take:10,Fields:%22Id,%20Name,%20VendorName,%20Slug,%20Tier,%20FavCount,%20ViewCount%22))

When executed in either a Binder or self-hosted **notebook** web app it will render API responses that looks like:

[![](./img/pages/apps/jupyterlab-mybinder-techstacks.png)](https://github.com/ServiceStack/jupyter-notebooks/blob/main/techstacks.io-FindTechnologies.ipynb)

### GitHub Auto Preview

Thanks to executed Notebooks retaining their executed outputs and GitHub's [built-in support of rendering Jupyter Notebooks](https://docs.github.com/en/github/managing-files-in-a-repository/working-with-non-code-files/working-with-jupyter-notebook-files-on-github), we can also view pre-rendered Notebooks directly in GitHub, e.g. you can view the pre-rendered output of the above Python Notebook directly on GitHub at: [techstacks.io-FindTechnologies.ipynb](https://github.com/ServiceStack/jupyter-notebooks/blob/main/techstacks.io-FindTechnologies.ipynb).

The beauty of Notebook's retaining their executed outputs within the same document is that it makes it possible to share rendered Notebooks on GitHub written in different languages. 

Which we can demonstrate using [apps.servicestack.net](https://apps.servicestack.net) which lets you download Notebooks for any publicly accessible ServiceStack API in **C#**, **Python** and **F#**:

[![](./img/pages/apps/apps-languages.png)](https://apps.servicestack.net)

Then use the languages tab to download the same API in a C# and F# Jupyter Notebook instead:

### C# TechStacks FindTechnologies Notebook

[/csharp/techstacks.io-FindTechnologies.ipynb](https://github.com/ServiceStack/jupyter-notebooks/blob/main/csharp/techstacks.io-FindTechnologies.ipynb)

[![](./img/pages/apps/jupyter-github-csharp.png)](https://github.com/ServiceStack/jupyter-notebooks/blob/main/csharp/techstacks.io-FindTechnologies.ipynb)

### F# TechStacks FindTechnologies Notebook

[/fsharp/techstacks.io-FindTechnologies.ipynb](https://github.com/ServiceStack/jupyter-notebooks/blob/main/fsharp/techstacks.io-FindTechnologies.ipynb)

[![](./img/pages/apps/jupyter-github-fsharp.png)](https://github.com/ServiceStack/jupyter-notebooks/blob/main/fsharp/techstacks.io-FindTechnologies.ipynb)

### Google Colab

Google Colab is another **FREE** hosted Jupyter notebook service that can open Notebooks stored in Google Drive or loaded from GitHub and can be shared just as you would with Google Docs or Sheets, which requires no install to use, while providing free access to computing resources including GPUs where it's executed in a virtual machine private to your account. 

Built into GDrive, you can open any `.ipynb` Jupyter Notebooks with Google's Colab service making it a great way to share private Notebooks between users using Google Drive.

Whilst you can upload your Python Jupyter Notebooks manually, the quickest way to open your ServiceStack API in Colab is to Save it directly in GDrive with the **Save** button:

![](./img/pages/apps/apps-python-notebook-gdrive.png)

Then click on the saved `.ipynb` Notebook to open it in Colab where like other Notebook services will let you see the last pre-executed rendered output. Running a cell with the **Play** icon or `CTRL+Enter` will execute the Notebook in a private virtual machine to update the captured outputs with live results:

![](./img/pages/apps/jupyter-colab-FindTechnologies.png)

## JetBrains Datalore

[Datalore](https://datalore.jetbrains.com) is JetBrains premium cloud hosted service for hosting and running Jupyter Notebooks within a shared team environment. It's online Notebook App features PyCharm's code insights and autocompletion, real-time collaborative editing and also includes built-in Terminal support for running remote commands and `.py` scripts:

[![](./img/pages/apps/jupyter-datalore.png)](https://datalore.jetbrains.com)

## Amazon SageMaker

[Amazon SageMaker](https://aws.amazon.com/sagemaker/) is Amazon's comprehensive ML service that helps data scientists and developers to prepare, build, train, and deploy high-quality machine learning (ML) models.

Included as part of their offering is [Amazon SageMaker Notebook Instances](https://docs.aws.amazon.com/sagemaker/latest/dg/nbi.html) which is a machine learning (ML) compute instance running the Jupyter Notebook App. SageMaker manages creating the instance and related resources. Use Jupyter notebooks in your notebook instance to prepare and process data, write code to train models, deploy models to SageMaker hosting, and test or validate your models.

![](./img/pages/apps/jupyter-sagemaker.png)


# Python Jupyter Notebooks
Source: https://docs.servicestack.net/jupyter-notebooks-python

![](./img/pages/apps/jupyter-python.png)

Whilst the [Jupyter project](https://jupyter.org) has designed its Notebooks to be language agnostic with current support for over 40+ programming languages, the best experience and broadest ecosystem and community support is still centered around Python Jupyter Notebooks.

Thanks to [Python Add ServiceStack Reference](/python-add-servicestack-reference) support for generating typed Python data classes for your ServiceStack Service DTOs, your API consumers are able to tap into the beautiful [interactive world of Jupyter Notebooks](/jupyter-notebooks) who can leverage end-to-end typed APIs with your Services Python DTOs and the generic [servicestack](https://pypi.org/project/servicestack/) Python package containing both the generic `JsonServiceClient` for making typed API requests as well as useful utilities for easily previewing API Responses in human-readable HTML or markdown table formats.

<lite-youtube class="w-full mx-4 my-4" width="560" height="315" videoid="h6UwDuXt8MA" style="background-image: url('https://img.youtube.com/vi/h6UwDuXt8MA/maxresdefault.jpg')"></lite-youtube>

## Instant Client Apps

Easiest way to generate a Python Notebook for a publicly available ServiceStack instance is to use Instant Client Apps UI at:

### [apps.servicestack.net](https://apps.servicestack.net)

Where API Consumers will be able to select an API for a remote ServiceStack Instance and generate a native UI to generate an API Request that can be downloaded in a stand-alone client App in any of the 9 supported programming languages:

[![](./img/pages/apps/apps-languages.png)](https://apps.servicestack.net)

Within seconds after being guided by Instant Client Apps UI, users will be able to select their preferred API and use the Auto form to pre-populate their API 
Request, e.g:

[![](./img/pages/apps/apps-techstacks-FindTechnologies.png)](https://apps.servicestack.net/#techstacks.io/python/AutoQuery/FindTechnologies(Ids:[1,2,4,6],VendorName:Google,Take:10,Fields:%22Id,%20Name,%20VendorName,%20Slug,%20Tier,%20FavCount,%20ViewCount%22))

Which can be run online to display results in a HTML table and a human-friendly markdown table for [AutoQuery Requests](/autoquery/rdbms) or API Responses containing a `Results` resultset. Clicking on **Python Notebook** will download a custom [techstacks.io-FindTechnologies.ipynb](https://github.com/ServiceStack/jupyter-notebooks/blob/main/techstacks.io-FindTechnologies.ipynb) Jupyter Notebook that when executed in either a Binder or self-hosted **notebook** web app will render API responses that looks like:

[![](./img/pages/apps/jupyterlab-mybinder-techstacks.png)](https://github.com/ServiceStack/jupyter-notebooks/blob/main/techstacks.io-FindTechnologies.ipynb)

All populated API Requests are also deep-linkable so they can be easily documented, shared and customized with other team members:

**[apps.servicestack.net/#techstacks.io/python/AutoQuery/FindTechnologies(Ids:[1,2,4,6],VendorName:Google,Take:10)](https://apps.servicestack.net/#techstacks.io/python/AutoQuery/FindTechnologies(Ids:[1,2,4,6],VendorName:Google,Take:10,Fields:%22Id,%20Name,%20VendorName,%20Slug,%20Tier,%20FavCount,%20ViewCount%22))**

### Google Colab

[Google Colab](https://research.google.com/colaboratory/) is a **FREE** hosted Jupyter notebook service from Google that can open Notebooks stored in Google Drive that can be shared just as you would with Google Docs or Sheets, which requires no install to use, while providing free access to computing resources including GPUs where it's executed in a virtual machine private to your account. 

Whilst you can upload your Python Jupyter Notebooks manually, the quickest way to open your ServiceStack API in Colab is to Save it directly in GDrive with the **Save** button:

![](./img/pages/apps/apps-python-notebook-gdrive.png)

Then click on the saved `.ipynb` Notebook to open it in Colab where like other Notebook services will let you see the last pre-executed rendered output. Running a cell with the **Play** icon or `CTRL+Enter` will execute the Notebook in a private virtual machine to update the captured outputs with live results:

![](./img/pages/apps/jupyter-colab-FindTechnologies.png)

### GitHub Auto Preview

Thanks to executed Notebooks retaining their executed outputs and GitHub's [built-in support of rendering Jupyter Notebooks](https://docs.github.com/en/github/managing-files-in-a-repository/working-with-non-code-files/working-with-jupyter-notebook-files-on-github), we can also view pre-rendered Notebooks directly in GitHub, e.g. you can view the pre-rendered output of the above Python Notebook directly on GitHub at: [techstacks.io-FindTechnologies.ipynb](https://github.com/ServiceStack/jupyter-notebooks/blob/main/techstacks.io-FindTechnologies.ipynb).

[![](./img/pages/apps/jupyter-github-python.png)](https://github.com/ServiceStack/jupyter-notebooks/blob/main/techstacks.io-FindTechnologies.ipynb)

### Instant Client Apps command-line generator

For increased flexibility and scriptability Instant Client Apps will also generate a command-line argument of your pre-populated API Request you can use to generate a Python Jupyter Notebook locally, e.g:

![](./img/pages/apps/apps-jupyter-command-line.png)

## Generate Notebook using command-line

Jupyter Commands lets you generate Python Jupyter Notebooks for calling ServiceStack APIs in a single command.

All command line utils used are available in the latest [dotnet tool](/dotnet-tool) which can be installed from:

:::sh
dotnet tool install --global x 
:::

Or if you had a previous version installed, update with:

:::sh
dotnet tool update -g x
:::

### Generate Python Jupyter Notebooks

Use `x jupyter-python` to display different usage examples for generating Python Jupyter Notebooks:

```
Usage: x jupyter-python <base-url>
       x jupyter-python <base-url> <request>
       x jupyter-python <base-url> <request> {js-object}
       x jupyter-python <base-url> <request> < body.json

Options:
 -out <file>            Save notebook to file
 -include <pattern>     Include Types DTOs pattern
```

The same syntax for invoking APIs with the [Post Command HTTP Utils](/post-command) can also be used to generate Python Jupyter Notebooks, e.g:

:::sh
x jupyter-python https://techstacks.io FindTechStacks "{Ids:[1,2,3],VendorName:'Google',Take:5}"
:::

Output:

```
Saved to: techstacks.io-FindTechStacks.ipynb
```


# C# Jupyter Notebooks
Source: https://docs.servicestack.net/jupyter-notebooks-csharp

![](./img/pages/apps/jupyter-csharp.png)

Jupyter Commands lets you generate C# Jupyter Notebooks for calling ServiceStack APIs in a single command.

<lite-youtube class="w-full mx-4 my-4" width="560" height="315" videoid="vt92pbet5bY" style="background-image: url('https://img.youtube.com/vi/vt92pbet5bY/maxresdefault.jpg')"></lite-youtube>

All command line utils used are available in the latest [dotnet tool](/dotnet-tool) which can be installed from:

:::sh
dotnet tool install --global x
:::

Or if you had a previous version installed, update with:

:::sh
dotnet tool update -g x
:::

### Generate C# Jupyter Notebooks

Use `x jupyter-csharp` to display different usage examples for generating C# Jupyter Notebooks:

```
Usage: x jupyter-csharp <base-url>
       x jupyter-csharp <base-url> <request>
       x jupyter-csharp <base-url> <request> {js-object}
       x jupyter-csharp <base-url> <request> < body.json

Options:
 -out <file>            Save notebook to file
 -include <pattern>     Include Types DTOs pattern
```

The same syntax for invoking APIs with the [Post Command HTTP Utils](/post-command) can also be used to generate C# Jupyter Notebooks, e.g:

:::sh
x jupyter-csharp https://techstacks.io FindTechStacks "{Ids:[1,2,3],VendorName:'Google',Take:5}"
:::

Output:

```
Saved to: techstacks.io-FindTechStacks.ipynb
```

::: info
Jupyter Notebooks can also be created with the API Explorer UI at [apps.servicestack.net](https://apps.servicestack.net)
:::

## Setup Jupyter for C# locally

To get working with JupyterLabs to run locally with a C# kernel, there are a few things you'll need to have installed.

- Latest dotnet 5.0+ SDK
- Python 3.7+ with pip

With both dotnet SDK and Python installed, you can then install JupyterLab, Dotnet Interactive and register the dotnet kernels with the following commands.

```bash
# Install jupyterlab to default Python interpreter
pip install jupyterlab
# Install Dotnet Interactive dotnet tool
dotnet tool install -g Microsoft.dotnet-interactive
# Get Dotnet Interactive to register kernels with Jupyter  
dotnet interactive jupyter install
```

To verify these have been installed successfully, you can list the currently registered kernels using the command.

:::sh
jupyter kernelspec list
:::

This should list `.net-csharp` as one of the kernels which is what the C# notebooks will use.

## Running JupyterLab

With everything setup, navigate to a local directory with your notebooks and run:

:::sh
jupyter-lab
:::

The context of where this command is run from matter as JupyterLab will mount list files in the same directory is was run, so make sure your running the `jupyter-lab` command from where your notebooks are located or where you new notebooks to be saved.

## Example generated notebook

From your notebook directory that JupyterLab is using, open a new command prompt/terminal and run:

:::sh
x jupyter-csharp https://covid-vac-watch.netcore.io QueryVaccinationRates
:::

This will generate the file `covid_vac_watch.netcore.io-QueryVaccinationRates.ipynb` in that directory. This file has everything that is needed to call the `QueryVaccinationRates` service and display data in the response.

![](/img/pages/jupyter/jupyter-lab-csharp-example.png)

### Visualize the data

These generated notebooks are designed to be a starting point with all the data plumbing setup done for you. Taking this example further, we can visualize the data using [Plotly.NET](https://plotly.net/), a NuGet library that generates plotly.js visuals using .NET. Run at least the first two cells and then add a new cell at the bottom of the generated notebook with the following code.

```csharp
#r "nuget: Plotly.NET, 2.0.0-preview.6"
#r "nuget: Plotly.NET.Interactive, 2.0.0-preview.6"

using Plotly.NET;

var xData = response.Results.Select(x => x.Date).ToList();
var yData = response.Results.Select(x => x.DailyVaccinations == null ? 0 : (decimal)(x.DailyVaccinations)).ToList();

GenericChart.GenericChart chart = Chart.Point<DateTime,decimal, string>(x: xData, y: yData, Name: "");
chart
    .WithTraceName("Daily Vaccinations", true)
    .WithX_AxisStyle(title: "Vaccinations", Showgrid: false, Showline: true)
    .WithY_AxisStyle(title: "Date", Showgrid: false, Showline: true);
display(chart);
```

The code above does several things.

- Import the 2 required Plotly.NET NuGet dependencies.
- Declares `using` statement.
- Transforms response data into 2 equal list of primitive data.
- Generates a plot with `Date` on the X axis and `DailyVaccinations` on the Y axis.

![](/img/pages/jupyter/jupyter-lab-visual-example.png)

## Try it out yourself using MyBinder with generated notebooks

Another way to work with Jupyter, C# and ServiceStack generated notebooks is to do with via [MyBinder](https://mybinder.org/). MyBinder is a free hosted service that gives you an isolated docker container to run your notebooks if you are just trying something out.

[![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/ServiceStack/jupyter-notebooks/HEAD)
- Click on the `Launch Binder` badge above and wait for it to launch into a Jupyter web UI (it can take a min or two sometimes)
- Goto `New` and select `Terminal`.
- In the terminal use the ServiceStack `x` tool to generate a new C# notebook like before
  - `x jupyter-csharp https://covid-vac-watch.netcore.io QueryVaccinationRates`
- Navigate back to Jupyter file explorer and see your generated notebook.
- Open the new notebook and **run** the generated cells.
- Add a new cell with the same code for Plotly.NET as above and run

![](/img/pages/jupyter/jupyter-mybinder-visual-example.png)


# F# Jupyter Notebooks
Source: https://docs.servicestack.net/jupyter-notebooks-fsharp

![](./img/pages/apps/jupyter-fsharp.png)

Jupyter Commands lets you generate F# Jupyter Notebooks for calling ServiceStack APIs in a single command.

<lite-youtube class="w-full mx-4 my-4" width="560" height="315" videoid="PxH3K5WIDx8" style="background-image: url('https://img.youtube.com/vi/PxH3K5WIDx8/maxresdefault.jpg')"></lite-youtube>

All command line utils used are available in the latest [dotnet tool](/dotnet-tool) which can be installed from:

:::sh
dotnet tool install --global x 
:::

Or if you had a previous version installed, update with:

:::sh
dotnet tool update -g x
:::

### Generate F# Jupyter Notebooks

Use `x jupyter-fsharp` to display different usage examples for generating F# Jupyter Notebooks:

```
Usage: x jupyter-fsharp <base-url>
       x jupyter-fsharp <base-url> <request>
       x jupyter-fsharp <base-url> <request> {js-object}
       x jupyter-fsharp <base-url> <request> < body.json

Options:
 -out <file>            Save notebook to file
 -include <pattern>     Include Types DTOs pattern
```

The same syntax for invoking APIs with the [Post Command HTTP Utils](/post-command) can also be used to generate F# Jupyter Notebooks, e.g:

:::sh
x jupyter-fsharp https://techstacks.io FindTechStacks "{Ids:[1,2,3],VendorName:'Google',Take:5}"
:::

Output:

```
Saved to: techstacks.io-FindTechStacks.ipynb
```

::: info
Jupyter Notebooks can also be created with the API Explorer UI at [apps.servicestack.net](https://apps.servicestack.net)
:::

## Setup Jupyter for F# locally

To get working with JupyterLabs to run locally with a F# kernel, there are a few things you'll need to have installed.

- Latest dotnet 5.0+ SDK
- Python 3.7+ with pip

With both dotnet SDK and Python installed, you can then install JupyterLab, Dotnet Interactive and register the dotnet kernels with the following commands.

```bash
# Install jupyterlab to default Python interpreter
pip install jupyterlab
# Install Dotnet Interactive dotnet tool
dotnet tool install -g Microsoft.dotnet-interactive
# Get Dotnet Interactive to register kernels with Jupyter  
dotnet interactive jupyter install
```

To verify these have been installed successfully, you can list the currently registered kernels using the command.

:::sh
jupyter kernelspec list
:::

This should list `.net-fsharp` as one of the kernels which is what the F# notebooks will use.

## Running JupyterLab

With everything setup, navigate to a local directory with your notebooks and run:

:::sh
jupyter-lab
:::

The context of where this command is run from matter as JupyterLab will mount list files in the same directory is was run, so make sure your running the `jupyter-lab` command from where your notebooks are located or where you new notebooks to be saved.

## Example generated notebook

From your notebook directory that JupyterLab is using, open a new command prompt/terminal and run:

:::sh
x jupyter-fsharp https://covid-vac-watch.netcore.io QueryVaccinationRates
:::

This will generate the file `covid_vac_watch.netcore.io-QueryVaccinationRates.ipynb` in that directory. This file has everything that is needed to call the `QueryVaccinationRates` service and display data in the response.

![](/img/pages/jupyter/jupyter-lab-fsharp-example.png)

### Visualize the data

These generated notebooks are designed to be a starting point with all the data plumbing setup done for you. Taking this example further, we can visualize the data using [Plotly.NET](https://plotly.net/), a NuGet library that generates plotly.js visuals using .NET. Run at least the first two cells and then add a new cell at the bottom of the generated notebook with the following code.

```fsharp
#r "nuget: Plotly.NET, 2.0.0-preview.6"
#r "nuget: Plotly.NET.Interactive, 2.0.0-preview.6"

open Plotly.NET

let xData = response.Results.Map(fun (x:VaccinationData) -> x.Date)
let yData = response.Results.Map(fun (x:VaccinationData) -> x.DailyVaccinations.GetValueOrDefault())

let chart = 
    Chart.Point(xData,yData)
        |> Chart.withTitle "Daily Vaccinations"
        |> Chart.withX_AxisStyle ("Date", Showgrid=false)
        |> Chart.withY_AxisStyle ("Vaccinations", Showgrid=false)
display(chart)
```

The code above does several things.

- Import the 2 required Plotly.NET NuGet dependencies.
- Declares `using` statement.
- Transforms response data into 2 equal list of primitive data.
- Generates a plot with `Date` on the X axis and `DailyVaccinations` on the Y axis.

![](/img/pages/jupyter/jupyter-lab-visual-example.png)

## Try it out yourself using MyBinder with generated notebooks

Another way to work with Jupyter, F# and ServiceStack generated notebooks is to do with via [MyBinder](https://mybinder.org/). MyBinder is a free hosted service that gives you an isolated docker container to run your notebooks if you are just trying something out.

[![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/ServiceStack/jupyter-notebooks/HEAD)
- Click on the `Launch Binder` badge above and wait for it to launch into a Jupyter web UI (it can take a min or two sometimes)
- Goto `New` and select `Terminal`.
- In the terminal use the ServiceStack `x` tool to generate a new F# notebook like before
  - `x jupyter-fsharp https://covid-vac-watch.netcore.io QueryVaccinationRates`
- Navigate back to Jupyter file explorer and see your generated notebook.
- Open the new notebook and **run** the generated cells.
- Add a new cell with the same code for Plotly.NET as above and run

![](/img/pages/jupyter/jupyter-mybinder-visual-example.png)


# Jupyter Notebooks for Reporting
Source: https://docs.servicestack.net/jupyter-notebooks-reporting

Jupyter Notebooks provide a rich set of interactive computing tools that can be used for many different use cases.
Incorporating data from web services means you can rerun/update your notebooks for ease of reuse for things like generating reports and testing.

For reporting tasks, we want to have the ability to save the output of our notebooks as a PDF, so there are a few setup steps that are needed to get Jupyter working with PDF using LaTeX. 
LaTeX has quite a few implicit dependencies that need to be installed locally to get this output to work. One way to make this a bit easier to repeat your results is by using a Docker environment setup to be used by the hosted MyBinder.org service.

## MyBinder

The JupyterHub team maintain their public Jupyter notebooks service at [mybinder.org](https://mybinder.org) for anyone who wants to share their interactive GitHub repositories publicly. Behind the scenes Notebooks are executed on a collection of [BinderHub Federated services](https://mybinder.readthedocs.io/en/latest/about/federation.html) using resources donated by  [Google Cloud](https://cloud.google.com), [OVH](https://www.ovh.com), [GESIS Notebooks](https://notebooks.gesis.org) and the [Turing Institute](https://turing.ac.uk).

To run your Notebooks on Binder head over to https://mybinder.org and paste the URL of your public GitHub repo containing your Jupyter Notebooks to retrieve the generated URL for your repo.

E.g. our [ServiceStack/jupyter-notebooks](https://github.com/ServiceStack/jupyter-notebooks) GitHub repo is available from:

#### [https://mybinder.org/v2/gh/ServiceStack/jupyter-notebooks/HEAD](https://mybinder.org/v2/gh/ServiceStack/jupyter-notebooks/HEAD)

Where behind-the-scenes Binder will build and host a Docker image of your repo and launch a dedicated `notebook` Web App instance to view an execute your repo's Notebooks.
This Docker image is built has on a `Dockerfile` in the root of the repository. Starting with a [base image from the Jupyter Docker docs](https://jupyter-docker-stacks.readthedocs.io/en/latest/using/selecting.html)

```dockerfile
# LaTeX dependencies (as root)
RUN apt-get install -y texlive-xetex \
        texlive-fonts-recommended \
        texlive-latex-recommended \
        texlive-latex-extra \
        texlive-plain-generic

# Install nbconvert (as user)
RUN pip install nbconvert
```

A full example of a `Dockerfile` which also includes support for .NET notebooks can be found in [our `mix` repository](#get-link), this can be built and run locally as well as used with MyBinder by creating a new GitHub repository and committing it in the root of the repository.

To run this locally, build the Dockerfile first using `docker build . -t <my-tag>`, followed by running the docker image using `docker run`.

Running locally, it is most useful to edit notebooks on the local host machine rather than the docker containers storage. To do this, we want to use a few options when using `docker run`. For example, the following command can run and expose local notebooks within `/mnt/c/projects/my-notebooks`.

```shell
docker run -it --rm -p 8888:8888 -v /mnt/c/projects/my-notebooks:/home/jovyan/Notebooks -e CHOWN_HOME=yes <my-tag>
```

Once running, use the `127.0.0.1` url in the command line output and open the full link with your browser. Editing and saving notebooks will update your notebooks on your host file system allowing you to iterate quickly.

## Combining local and MyBinder workflow

Being able to run the same Docker container locally to iterate on host notebooks that are in the same GitHub repository and then commit those changes to share with others and to run on MyBinder creates a great way of getting the most out of the repeatability that is a part of the Binder solution as well as having the same functionality locally to generate reports and share as PDF without needing to regularly rebuild the docker image which will slow down iteration.

### Things you will need

- ServiceStack dotnet tool `x`.
- Docker
- GitHub Account

### Setup

We've created a `mix` template to setup this workflow more straight forward.

All command line utils used are available in the latest [dotnet tool](/dotnet-tool) which can be installed from:

:::sh
dotnet tool install --global x 
:::

Or if you had a previous version installed, update with:

:::sh
dotnet tool update -g x
:::

### Create a new GitHub repository
To work with MyBinder.org service, you will need to create a *public* GitHub repository so the service can build and host your notebook environment.

::: info
For private repositories to work, you will need to host and run your own infrastructure for your BinderHub environment. More information can be found on the steps required for this on the BinderHub docs "[Zero to BinderHub](https://binderhub.readthedocs.io/en/latest/zero-to-binderhub/index.html)"
:::

Clone your newly created *public* GitHub repository locally and run the following command in the root directory of the repository.

:::sh
x mix docker-jupyter-reports
:::

Commit the generated `Dockerfile` and push your changes to GitHub.

### Build the Docker image locally

Since we want to be able to work on notebook reports both locally and on MyBinder, we will need to build the Docker image locally.

From the root of your local git repository, run the following command where `jupyter-reports` can be replaced with your preferred tag.

:::sh
docker build . -t jupyter-reports
:::

::: info
This will likely take a few minutes locally due to all the required packages and size of the numerous dependencies
:::

```
[+] Building 572.3s (25/25) FINISHED
 => [internal] load build definition from Dockerfile                                                               0.1s
 => => transferring dockerfile: 3.68kB                                                                             0.0s
 => [internal] load .dockerignore                                                                                  0.0s
 => => transferring context: 2B                                                                                    0.0s
 => [internal] load metadata for docker.io/jupyter/base-notebook:latest                                            7.2s
 => [auth] jupyter/base-notebook:pull token for registry-1.docker.io                                               0.0s
 => [ 1/19] FROM docker.io/jupyter/base-notebook:latest@sha256:5a942551e592d9ee167c353dec8015f5781fa69fece97a093  15.6s
 => => resolve docker.io/jupyter/base-notebook:latest@sha256:5a942551e592d9ee167c353dec8015f5781fa69fece97a0934f6  0.0s
...
 => => extracting sha256:67bf56c81c699383f5a229fdc62a2664c94a7798d35511454e29df1c6a1afd05                          0.0s
 => [internal] load build context                                                                                  0.0s
 => => transferring context: 3.67kB                                                                                0.0s
 => [ 2/19] WORKDIR /home/jovyan                                                                                   1.4s
 => [ 3/19] RUN apt-get update                                                                                    73.9s
 => [ 4/19] RUN apt-get install -y curl                                                                           22.2s
 => [ 5/19] RUN apt-get install -y texlive-xetex         texlive-fonts-recommended         texlive-latex-recomm  375.2s
 => [ 6/19] RUN apt-get update     && DEBIAN_FRONTEND=noninteractive apt-get install -y --no-install-recommends    5.1s
 => [ 7/19] RUN dotnet_sdk_version=5.0.102     && curl -SL --output dotnet.tar.gz https://dotnetcli.azureedge.net  8.2s
 => [ 8/19] COPY ./ /home/jovyan/Notebooks/                                                                        0.3s
 => [ 9/19] RUN echo "<configuration>  <solution>    <add key="disableSourceControlIntegration" value="true" />    0.5s
 => [10/19] RUN echo "<Project Sdk="Microsoft.NET.Sdk.Web">  <PropertyGroup>    <TargetFramework>net5.0</TargetFr  0.6s
 => [11/19] RUN chown -R 1000 /home/jovyan                                                                         1.0s
 => [12/19] RUN pip install nteract_on_jupyter                                                                    14.6s
 => [13/19] RUN dotnet tool install -g Microsoft.dotnet-interactive                                               12.8s
 => [14/19] RUN dotnet tool install -g x                                                                           6.5s
 => [15/19] RUN dotnet restore /home/jovyan/preload.csproj                                                        16.4s
 => [16/19] RUN echo "/opt/conda/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/home/jovyan/.d  0.3s
 => [17/19] RUN dotnet interactive jupyter install                                                                 2.7s
 => [18/19] RUN pip install nbconvert                                                                              1.1s
 => [19/19] WORKDIR /home/jovyan/Notebooks/                                                                        0.0s
 => exporting to image                                                                                             6.2s
 => => exporting layers                                                                                            6.2s
 => => writing image sha256:ab54b9fd600007d3badbd7e99927e4c2bfa2dcc2334586c1e76619d1a0e56cbd                       0.0s
```

To run your newly built Docker image, use the following command where `<absolute-path-of-git-repo>` is the location of your local git repository. This can't be a relative.

```shell
docker run -it --rm -p 8888:8888 -v <absolute-path-of-git-repo>:/home/jovyan/Notebooks -e CHOWN_HOME=yes jupyter-reports
```

::: info
Jupyter will generate working directory called `.ipynb_checkpoints` which you can add to your .gitignore
:::

Running this will output a local `127.0.0.1` address to use in your browser with an authentication toke you will need to copy and paste to your preferred browser.

![](/img/pages/jupyter/reports-and-testing/docker-run.png)

## Example notebook report

Now that we have our environment built and running, we want to create a report that is sharable in multiple ways. That is a nice `PDF` output we can attach and share as well as a working notebook so others can see and run the full version of our report to review or make changes themselves.

### Creating a new notebook using the `x` tool

To jump start the process of getting the data you need to create your report in a notebook, we can use the ServiceStack `x` tool to generate the plumbing code we need to fetch data from a specific ServiceStack host and service.

For example, working with the [Chinook sample application](https://chinook.locode.dev) which has details of orders from all over the world, we can produce a report based on invoice data.

![Metadata page of the Chinook sample application hosted at chinook.locode.dev](/img/pages/jupyter/reports-and-testing/chinook-metadata.png)

Running the following command from a new `notebooks` directory in our local git repository, we can generate a working notebook that already integrates with the Chinook sample web services, specifically the `QueryInvoices` service.
```shell
x jupyter-python https://chinook.locode.dev QueryInvoices
```

Once generated, we can navigate to this notebook in the jupyter environment using our browser.

![](/img/pages/jupyter/reports-and-testing/jupyter-notebook.png)

The first cell contains all the typed code for our integration with the Chinook service and initializes the `JsonServiceClient` with the ServiceStack host.

The second cell performs the query, we can provide more details here based on the specific service. If you are unsure of how you can use a specific service you can use [Instant Client Apps](https://apps.servicestack.net) to explore the service or use `x inspect <host> <api name>`.

```python
response = client.send(QueryInvoices())
```

In our example, we are going to query all invoices and filter locally to generate some different visuals.

The last two cells display the data is the response in different ways. Since we will want to visualize the data ourselves to produce a report, we can delete these cells and install some dependencies we will need to generate some more useful plots.

```python
%pip install pandas
%pip install matplotlib
import pandas as pd
import matplotlib.pyplot as plt
```

The above code will use the `pip` [magic](https://ipython.readthedocs.io/en/stable/interactive/magics.html#magic-pip) to install `pandas` and `matplotlib` libraries and import them for use.

We know the structure of the data returning from the service based on the response Data Transfer Objects (DTOs) declared in the first cell. 

```python
@dataclass_json(letter_case=LetterCase.CAMEL, undefined=Undefined.EXCLUDE)
@dataclass
class Invoices:
    invoice_id: int = 0
    customer_id: int = 0
    invoice_date: datetime.datetime = datetime.datetime(1, 1, 1)
    billing_address: Optional[str] = None
    billing_city: Optional[str] = None
    billing_state: Optional[str] = None
    billing_country: Optional[str] = None
    billing_postal_code: Optional[str] = None
    total: Decimal = decimal.Decimal(0)
```
Next, we want to load our response data into a pandas DataFrame for ease of plotting.

```python
df = pd.DataFrame(response.results)
```

And since we will be looking at sales over time, we will create an index column to our data for `year` based on the existing `invoice_date` column.

```python
df['year'] = pd.DatetimeIndex(df['invoice_date']).year
```

Jupyter Notebooks have different types of cells that change the way they behave when they are run. Markdown cells can be used for presentation of code results, making the notebook ideal for generating output that has a clean layout and is well described.

```markdown
# Sales by year
Looking at the sales across 5 years of data we have small dips in 2009 and 2013.
```

Now we have given the context for a visual, lets generate the visual itself by using the following code.

```python
df.groupby('year')['total'].sum().astype(float).plot.bar();
```

::: info
For statements generating plots, remember to end the statement with a semicolon as to avoid unwanted metadata about the statement return type
:::

![Sales by year example](/img/pages/jupyter/reports-and-testing/sales-by-year.png)

Working through the breakdown of data by generating additional plots with headings we end up with a basic report we can present to someone not familiar with python development. To export to PDF we can use the web UI of Jupyter by going to `File`->`Download as`->`PDF via LaTeX (.pdf)`.

![Download PDF menu](/img/pages/jupyter/reports-and-testing/download-pdf-menu.png)

[Looking at the resultant PDF](https://raw.githubusercontent.com/ServiceStack/docs/master/docs/public/jupyter-samples/jupyter-reports-standard.pdf), we can see we can still see the code related input and output. 

![Output PDF](/img/pages/jupyter/reports-and-testing/pdf-standard.png)

If this was something we would present to people not familiar with software development or python, this is unnecessary noise that we can filter out while still leaving the notebook in a state that is runnable for those working on it.

First, clear the cell output you don't want to include in your final result PDF. This will include from cells that install dependencies using `%pip install` and anything else which you think doesn't add value to the final report. This can be done by selecting the cell in the web UI, going to the `Cell` menu and clicking `Current Outputs`->`Clear`.

Once this is done, we will need to run a command from a Terminal in the context of our running Docker container. The easiest way to do this is to use the Jupyter web UI itself. From the file explorer view, at the top right a menu button called `New` can be dropped down and a `Terminal` option can be selected.

![New terminal](/img/pages/jupyter/reports-and-testing/new-terminal.png)

Navigating to the folder of your notebook report, you can use a utility called `nbconvert` to run a similar command to what is happening when using the `Download as` menu, but this time with additional arguments to further refine the output. Specifically, the `--TemplateExporter.exclude_input=True` option.

```shell
jupyter nbconvert --to pdf chinook.locode.dev-QueryInvoices.ipynb --TemplateExporter.exclude_input=True
```

The generated PDF will be visible in the Jupyter file explorer web UI so you can open and [download the result](https://raw.githubusercontent.com/ServiceStack/docs/master/docs/public/jupyter-samples/jupyter-reports-clean.pdf).

![Clean output PDF](/img/pages/jupyter/reports-and-testing/pdf-clean.png)

### HTML Output
The same process can be done for outputing straight HTML for easy sharing on a static site. Using the `Export Notebook As` menu, selecting HTML we get what we can see in our Jupyter environment with all the context and code.

![](/img/pages/jupyter/reports-and-testing/html-standard.png)

Using the terminal again to produce HTML, we can strip the code away to produce a clean report.

```shell
jupyter nbconvert --to html chinook.locode.dev-QueryInvoices.ipynb --TemplateExporter.exclude_input=True
```

![](/img/pages/jupyter/reports-and-testing/html-clean.png)

### Using MyBinder.org

Now that we have finished the report we wanted to write, we might want a colleague review the work in a managed environment they can access straight from a browser. MyBinder.org is limited to only public GitHub repositories but the same workflow work be applicable to your own managed BinderHub environment.

![](/img/pages/jupyter/reports-and-testing/my-binder-ui.png)

Reviewing notebooks is convenient using services like MyBinder, but changes are ephemeral, so while *reviews* can be done using this workflow, changes need to be made in an environment where files can be committed back to the remote GitHub repository.


# GitHub Action Templates for Faster CI Setup
Source: https://docs.servicestack.net/github-action-templates

If your project is on GitHub, GitHub Actions are a great built in way to have an automated Continuous Integration (CI) setup where the configuration is committed to the same repository where your project lives.

GitHub Actions are also very cost effective thanks to the generous free minutes allowance and additional **3000 /month** minutes with every paid team member. 

To make taking advantage of GitHub Actions with your ServiceStack applications, we've created multiple [mix](/mix-tool) templates to setup your CI process quickly. Most [Project Templates](/templates/) provide a build + test step on every commit as well as combinations of Docker image hosting and application deployments focusing on portability.

Since hosting architectures vary so much, these templates are designed to get you *started* with a simple setup where you can iterate quickly as you develop application. As hosting requirements change, the deployment GitHub Action workflow `yml` files can be customized to suit.

The simple build and test step is available using the [build](https://gist.github.com/gistlyn/856bd13c38ad388ef6d48d06c32ab395), mix template, whilst the [mix](/mix-tool) deployment templates uses the naming convention `release-{docker image repository}-{hosting configuration}`. 

For example, `release-ghr-vanilla` where **ghr** uses GitHub for the Docker Repository and `vanilla` for our minimalist deployment that uses SSH and **docker compose**.

## GitHub Action Templates

Templates currently available are:

| Name                    | Docker Repository                | Deployment and Hosting        | 
|-------------------------|----------------------------------|-------------------------------|
| **release-ghr-vanilla**	| GitHub Container Repository	     | SSH + docker compose          |
| **release-ecr-vanilla**	| AWS Elastic Container Repository | SSH + docker compose          | 
| **release-hub-vanilla**	| Docker Hub                       | SSH + docker compose          | 
| **release-ecr-aws**   	| AWS Elastic Container Repository | AWS ECS without Load Balancer | 

### release-ghr-vanilla
Using GitHub Container Repository (ghcr.io) and deploying to a Linux host with `docker compose` via SSH, this provides a GitHub centric option for prototyping your application. A [full tutorial using Digital Ocean as our Linux host provider is available](/do-github-action-mix-deployment) as well as an accompanying video.

<lite-youtube class="w-full mx-4 my-4" width="560" height="315" videoid="0PvzcnxlBvc" style="background-image: url('https://img.youtube.com/vi/0PvzcnxlBvc/maxresdefault.jpg')"></lite-youtube>

Also, a [shorter reference documentation](https://github.com/ServiceStack/mix/blob/master/actions/release-ghr-vanilla/.github/workflows/README.md) that comes with the template when using `mix` available that lists the setup as well as the required [GitHub Repository](https://github.com/ServiceStack/mix/blob/master/actions/release-ghr-vanilla/.github/workflows/README.md#github-repository-setup) Secrets for configuration.

### release-ecr-vanilla
Using AWS ECR (Elastic Container Repository) and deploying to a Linux host with `docker compose` via SSH, this provides a portable simple hosting with AWS ECR for those already in the AWS cloud provider environment.

Reference for this GitHub Action configuration is provided with the template itself, also [available here](https://github.com/ServiceStack/mix/blob/master/actions/release-ecr-vanilla/.github/workflows/README.md) along with the [required Repository Secrets](https://github.com/ServiceStack/mix/blob/master/actions/release-ecr-vanilla/.github/workflows/README.md#github-repository-setup).

### release-hub-vanilla
Using the original Docker Hub as a Docker image repository and deploying to a Linux host with `docker compose` via SSH, this might be more suited to those with existing use of Docker Hub or public application images.

Reference for this GitHub Action configuration is provided with the template itself, [also available on GitHub](https://github.com/ServiceStack/mix/blob/master/actions/release-hub-vanilla/.github/workflows/README.md) here along with the [required Repository Secrets](https://github.com/ServiceStack/mix/blob/master/actions/release-hub-vanilla/.github/workflows/README.md#github-repository-setup).

### release-ecr-aws
Using AWS ECR (Elastic Container Repository) and deploying via AWS ECS to a dedicated ECS cluster with a single EC2 instance, this template enables a gateway into using AWS ECS without the regular cost of an Application Load Balancer (ALB). Like the other templates, this uses NGINX proxy with Lets Encrypt companion in place of AWS specific managed services to do the same. This will give you a starting point for your prototype until you have the need for scalability and high availability for your application.

We have a full tutorial along with a video walk through available, showing from start to finish getting your ServiceStack application created and deploying via GitHub Actions and ECS. 

<lite-youtube class="w-full mx-4 my-4" width="560" height="315" videoid="Eh4tvLN8i8g" style="background-image: url('https://img.youtube.com/vi/Eh4tvLN8i8g/maxresdefault.jpg')"></lite-youtube>

Reference for this GitHub Action configuration is provided with the template itself, [also available on GitHub](https://github.com/ServiceStack/mix/blob/master/actions/release-ecr-aws/.github/workflows/README.md) here along with the [required Repository Secrets](https://github.com/ServiceStack/mix/blob/master/actions/release-ecr-aws/.github/workflows/README.md#github-repository-setup).

### Blazor Litestream

For a detailed overview for creating and setting up deployment for a new [Blazor Litestream App](/blazor-litestream) from scratch checkout:

<lite-youtube class="w-full mx-4 my-4" width="560" height="315" videoid="fY50dWszpw4" style="background-image: url('https://img.youtube.com/vi/fY50dWszpw4/maxresdefault.jpg')"></lite-youtube>

::: info
If you are using the template GitHub Actions and deploying to an Ubuntu 22.04 server, ensure you ssh key is generated using non RSA SHA1 algorithm.
Eg `ssh-keygen -t ecdsa` or swap out the use of `appleboy/scp-action@v0.1.3` for your own step using the latest version of the `scp` command line tool in your CI environment.
For a step by step and other options, see [this Ask Ubuntu Answer](https://askubuntu.com/a/1409528/366659)
:::


# GitHub Action Docker Compose deployments via SSH
Source: https://docs.servicestack.net/ssh-docker-compose-deploment

This guide demonstrates a pattern for deploying to a single Linux server via SSH using GitHub Actions and Docker Compose. 
This pattern of deployment works for any dockerized web application, and can be used with cost-effective hosting providers like Hetzner, Digital Ocean, etc since it only requires a single Linux server with Docker installed.

## Understanding the Core Components

Before we get our hands dirty with deployment, let's take a moment to understand the essential components involved in this process. We'll also explain why we've chosen each one and how they contribute to our this cost-effective deployment pipeline.

### GitHub and Its Functions

The backbone of our deployment pipeline is GitHub, a platform that provides a host of features to support our goals. Here are the key GitHub features we'll leverage:

- **GitHub Actions**: These are automated workflows that will handle the process of Continuous Integration (CI) for our application. It checks out code, sets up .NET Core, builds, tests, and creates releases. We'll go into detail about this in the practical section.
- **GitHub Action Secrets**: Sensitive information like login credentials, tokens, or keys shouldn't be exposed in your codebase. GitHub Action Secrets are encrypted and allow us to store such information securely, which is essential for building and pushing Docker images.
- **GitHub Container Registry (GHCR)**: This is where our Docker images will be stored and versioned. GitHub Actions will build and push Docker images to GHCR, from where our Linux server will pull them during deployment.
- **GitHub Repository**: The central location where our application's codebase is stored. This is also where we'll configure GitHub Actions and store our Docker Compose files.

### Docker Compose

Docker Compose is a tool that helps with the management of multi-container Docker applications. It allows us to define our application's environment in a YAML file (`docker-compose.yml`), enabling consistent setups across different environments. This will be installed on your target Linux server, where it will be used to pull Docker images and run our application.

### Secure Shell (SSH)

SSH is a protocol used for securely connecting to a remote server. In our deployment process, we'll use SSH for copying Docker Compose files and executing commands on the Linux server, such as pulling Docker images and running Docker Compose.
This is done via GitHub Actions where we will use the `ssh-action` to securely transfer the Docker Compose file to the Linux server, and execute commands remotely.

### Linux Server, NGINX, and LetsEncrypt

Our Linux server is where everything comes together. It's where our application will be hosted, and where the Docker Compose file will be executed. But that's not all; we'll set up NGINX reverse proxy on this server to manage HTTP requests and responses between clients and our application.

We're also adding LetsEncrypt into the mix. LetsEncrypt will work in conjunction with NGINX to automate routing, provide Transport Layer Security (TLS), and manage SSL certificates. This combination will ensure our application is secure and readily accessible.

By understanding these core components, we can now piece together our deployment pipeline. But before we proceed, it's essential to ensure you have access to the required tools. Make sure you have a GitHub account, Docker installed on your local machine, access to a Linux server, and the necessary knowledge to work with these tools. Don't worry if you're unsure about any steps; we'll guide you through each stage as we move forward.

## Setting Up Your Linux Server

The heart of your web application deployment, the Linux server, requires proper setup and configuration to ensure the deployment and operation of your applications. Here, we'll be using Ubuntu 22.04 as our target server, although you can adapt these instructions for other distributions as well.

Firstly, you need to ensure you have a Linux server at your disposal. This could be a virtual private server (VPS) from any cloud provider, a dedicated server, or even a Linux machine in your local network (provided it can be accessed via GitHub Actions).

Once you have access to your server, follow these steps:

### Installing Docker and Docker Compose

Docker is a crucial component that enables us to build, ship, and run applications inside containers. Docker Compose, on the other hand, streamlines the process of managing multi-container Docker applications. Here's how to install them:

1. **Update your server:** Before we start, let's make sure our server has the latest updates. Run the following commands:
    ```
    sudo apt update
    sudo apt upgrade -y
    ```
2. **Install Docker:** Docker provides an official guide to install Docker Engine on Ubuntu, which you can follow [here](https://docs.docker.com/engine/install/ubuntu/).

By default, this should come with the latest version of Docker Compose. However, if you need to install Docker Compose separately, you can follow the official guide [here](https://docs.docker.com/compose/install/).

After the installation, confirm that Docker and Docker Compose have been correctly installed by running `docker --version` and `docker compose`. The terminal should print the version of Docker and show command options for Docker Compose, respectively.

### Setting up NGINX and LetsEncrypt

Next, we will set up NGINX and LetsEncrypt in Docker containers. These are responsible for handling client requests, routing, SSL encryption, and certificate management.

- **Create the following YAML file** on your Linux server:

```yaml
version: "3.9"

services:
  nginx-proxy:
    image: nginxproxy/nginx-proxy
    container_name: nginx-proxy
    restart: always
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - conf:/etc/nginx/conf.d
      - vhost:/etc/nginx/vhost.d
      - html:/usr/share/nginx/html
      - dhparam:/etc/nginx/dhparam
      - certs:/etc/nginx/certs:ro
      - /var/run/docker.sock:/tmp/docker.sock:ro
    labels:
      - "com.github.jrcs.letsencrypt_nginx_proxy_companion.nginx_proxy"

  letsencrypt:
    image: nginxproxy/acme-companion:2.2
    container_name: nginx-proxy-le
    restart: always
    depends_on:
      - "nginx-proxy"
    environment:
      - DEFAULT_EMAIL=you@example.com
    volumes:
      - certs:/etc/nginx/certs:rw
      - acme:/etc/acme.sh
      - vhost:/etc/nginx/vhost.d
      - html:/usr/share/nginx/html
      - /var/run/docker.sock:/var/run/docker.sock:ro

networks:
  default:
    name: nginx

volumes:
  conf:
  vhost:
  html:
  dhparam:
  certs:
  acme:
```

- **Start the containers:** Use the command `docker compose up -d` in the directory containing your `docker-compose.yml` file to start the NGINX reverse proxy and LetsEncrypt containers.

With Docker, Docker Compose, NGINX, and LetsEncrypt setup, your Linux server is ready for deployments. Note that these are one-off tasks. Once set up, you won't need to repeat them for deploying additional applications.

For subsequent deployments, GitHub Actions will take care of creating necessary directories and SCP copying the `docker-compose.yml` file from the repository to the target Linux server. This allows your deployment pipeline to be flexible, repeatable, and reliable.

![](./img/posts/docker-compose/linux-server.png)

## GitHub: The Backbone of Your Deployment Pipeline

In this section, we'll explore how to set up a GitHub-based deployment pipeline, using GitHub Actions for automation, GitHub Secrets for security, and the GitHub Container Registry for Docker image storage. You'll see how these tools can provide a powerful, end-to-end solution for building and deploying your applications.

### Understanding GitHub Actions

GitHub Actions allow you to create custom software development life cycle (SDLC) workflows directly in your GitHub repository. These workflows are described in YAML files and can be triggered by GitHub events (such as pushing code, creating releases, etc.), on a schedule, or manually.

In the provided YAML, the deployment workflow is triggered on three events:

1. A new GitHub release is published.
2. The build workflow has completed on `main` or `master` branches.
3. Manual trigger for rolling back to a specific release or redeploying the latest version.

The jobs are divided into two parts: `push_to_registry` and `deploy_via_ssh`. The first job builds a Docker image from the repository's code and pushes it to GitHub's container registry. The second job deploys the image to a remote server via SSH.

### Configuring GitHub Action Secrets

GitHub Secrets are encrypted environment variables created in your repository settings. They're a secure way to store and use sensitive information in GitHub Actions, like credentials, SSH keys, tokens, etc. Without them, this sensitive information would be exposed in your public repository.

The YAML script uses the following secrets:

- `DEPLOY_HOST`: The IP address or domain name of the server where the application is deployed.
- `DEPLOY_USERNAME`: The username used for SSHing into the deployment server.
- `DEPLOY_KEY`: The private SSH key for the deployment server.
- `LETSENCRYPT_EMAIL`: The email used for Let's Encrypt certificate registration.

These secrets can be set up in your repository settings under the `Secrets` section.

![](./img/posts/docker-compose/secrets-separation.PNG)

```markdown
Go to `Settings` -> `Secrets` -> `New repository secret`
```

### Leveraging GitHub Container Registry

The GitHub Container Registry is a place to store Docker images within GitHub, which can then be used in your GitHub Actions workflows or pulled directly to any server with Docker installed.

The following `release.yml` can be used with any dockerized application with a `docker-compose.yml`,`docker-compose.prod.yml` with an `app` and `app-migration` services, and the secrets above.

```yaml
name: Release
permissions:
  packages: write
  contents: write
on:
  # Triggered on new GitHub Release
  release:
    types: [published]
  # Triggered on every successful Build action
  workflow_run:
    workflows: ["Build"]
    branches: [main,master]
    types:
      - completed
  # Manual trigger for rollback to specific release or redeploy latest
  workflow_dispatch:
    inputs:
      version:
        default: latest
        description: Tag you want to release.
        required: true

jobs:
  push_to_registry:
    runs-on: ubuntu-22.04
    if: ${{ github.event.workflow_run.conclusion != 'failure' }}
    steps:
      # Checkout latest or specific tag
      - name: checkout
        if: ${{ github.event.inputs.version == '' || github.event.inputs.version == 'latest' }}
        uses: actions/checkout@v3
      - name: checkout tag
        if: ${{ github.event.inputs.version != '' && github.event.inputs.version != 'latest' }}
        uses: actions/checkout@v3
        with:
          ref: refs/tags/${{ github.event.inputs.version }}
          
      # Assign environment variables used in subsequent steps
      - name: Env variable assignment
        run: echo "image_repository_name=$(echo ${{ github.repository }} | tr '[:upper:]' '[:lower:]')" >> $GITHUB_ENV
      # TAG_NAME defaults to 'latest' if not a release or manual deployment
      - name: Assign version
        run: |
          echo "TAG_NAME=latest" >> $GITHUB_ENV
          if [ "${{ github.event.release.tag_name }}" != "" ]; then
            echo "TAG_NAME=${{ github.event.release.tag_name }}" >> $GITHUB_ENV
          fi;
          if [ "${{ github.event.inputs.version }}" != "" ]; then
            echo "TAG_NAME=${{ github.event.inputs.version }}" >> $GITHUB_ENV
          fi;
      
      - name: Login to GitHub Container Registry
        uses: docker/login-action@v2
        with:
          registry: ghcr.io
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}
      
      # Build and push new docker image, skip for manual redeploy other than 'latest'
      - name: Build and push Docker images
        uses: docker/build-push-action@v3
        if: ${{ github.event.inputs.version == '' || github.event.inputs.version == 'latest' }}
        with:
          file: Dockerfile
          context: .
          push: true
          tags: ghcr.io/${{ env.image_repository_name }}:${{ env.TAG_NAME }}
  
  deploy_via_ssh:
    needs: push_to_registry
    runs-on: ubuntu-22.04
    if: ${{ github.event.workflow_run.conclusion != 'failure' }}
    steps:
      # Checkout latest or specific tag
      - name: checkout
        if: ${{ github.event.inputs.version == '' || github.event.inputs.version == 'latest' }}
        uses: actions/checkout@v3
      - name: checkout tag
        if: ${{ github.event.inputs.version != '' && github.event.inputs.version != 'latest' }}
        uses: actions/checkout@v3
        with:
          ref: refs/tags/${{ github.event.inputs.version }}

      - name: repository name fix and env
        run: |
          echo "image_repository_name=$(echo ${{ github.repository }} | tr '[:upper:]' '[:lower:]')" >> $GITHUB_ENV
          echo "domain=${{ secrets.DEPLOY_HOST }}" >> $GITHUB_ENV
          echo "letsencrypt_email=${{ secrets.LETSENCRYPT_EMAIL }}" >> $GITHUB_ENV
          echo "TAG_NAME=latest" >> $GITHUB_ENV
          if [ "${{ github.event.release.tag_name }}" != "" ]; then
            echo "TAG_NAME=${{ github.event.release.tag_name }}" >> $GITHUB_ENV
          fi;
          if [ "${{ github.event.inputs.version }}" != "" ]; then
            echo "TAG_NAME=${{ github.event.inputs.version }}" >> $GITHUB_ENV
          fi;

      - name: Create .env file
        run: |
          echo "Generating .env file"

          echo "# Autogenerated .env file" > .env
          echo "HOST_DOMAIN=${{ secrets.DEPLOY_HOST }}" >> .env
          echo "LETSENCRYPT_EMAIL=${{ secrets.LETSENCRYPT_EMAIL }}" >> .env

          echo "IMAGE_REPO=${{ env.image_repository_name }}" >> .env
          echo "RELEASE_VERSION=${{ env.TAG_NAME }}" >> .env
      
      # Copy docker-compose and .env files to target server
      - name: copy files to target server via scp
        uses: appleboy/scp-action@v0.1.3
        with:
          host: ${{ secrets.DEPLOY_HOST }}
          username: ${{ secrets.DEPLOY_USERNAME }}
          port: 22
          key: ${{ secrets.DEPLOY_KEY }}
          source: "./docker-compose.yml,./docker-compose.prod.yml,./.env"
          target: "~/.deploy/${{ github.event.repository.name }}/"
      
      - name: Run remote db migrations
        uses: appleboy/ssh-action@v0.1.5
        env:
          APPTOKEN: ${{ secrets.GITHUB_TOKEN }}
          USERNAME: ${{ secrets.DEPLOY_USERNAME }}
        with:
          host: ${{ secrets.DEPLOY_HOST }}
          username: ${{ secrets.DEPLOY_USERNAME }}
          key: ${{ secrets.DEPLOY_KEY }}
          port: 22
          envs: APPTOKEN,USERNAME
          script: |
            echo $APPTOKEN | docker login ghcr.io -u $USERNAME --password-stdin
            cd ~/.deploy/${{ github.event.repository.name }}
            docker compose -f ./docker-compose.yml -f ./docker-compose.prod.yml pull
            docker compose -f ./docker-compose.yml -f ./docker-compose.prod.yml up app-migration

      # Deploy Docker image with your application using `docker compose up app` remotely
      - name: remote docker-compose up via ssh
        uses: appleboy/ssh-action@v0.1.5
        env:
          APPTOKEN: ${{ secrets.GITHUB_TOKEN }}
          USERNAME: ${{ secrets.DEPLOY_USERNAME }}
        with:
          host: ${{ secrets.DEPLOY_HOST }}
          username: ${{ secrets.DEPLOY_USERNAME }}
          key: ${{ secrets.DEPLOY_KEY }}
          port: 22
          envs: APPTOKEN,USERNAME
          script: |
            echo $APPTOKEN | docker login ghcr.io -u $USERNAME --password-stdin
            cd ~/.deploy/${{ github.event.repository.name }}
            docker compose -f ./docker-compose.yml -f ./docker-compose.prod.yml pull
            docker compose -f ./docker-compose.yml -f ./docker-compose.prod.yml up app -d
```

In the provided YAML, the image is built and pushed to the registry in the `push_to_registry` job with the `docker/build-push-action@v3` action.

```yml
- name: Build and push Docker images
  uses: docker/build-push-action@v3
  if: ${{ github.event.inputs.version == '' || github.event.inputs.version == 'latest' }}
  with:
    file: Dockerfile
    context: .
    push: true
    tags: ghcr.io/${{ env.image_repository_name }}:${{ env.TAG_NAME }}
```

After building the Docker image, it is tagged and pushed to the GitHub Container Registry.

## Using GitHub Action Secrets for Multiple Applications

In the YAML provided, the secrets are used in multiple places:

- `GITHUB_TOKEN`: This is a system-generated token used by GitHub Actions to authorize interactions with the GitHub API and other services. Within the context of this workflow, `GITHUB_TOKEN` is used to authenticate Docker, allowing it to push images to and pull images from the GitHub Container Registry. This is generated for you based on the permissions you give the GitHub Actions workflow.
- `DEPLOY_HOST`: This secret represents the hostname to which SSH connections will be made during the deployment phase. This could be an IP address or a subdomain, as long as it's correctly set with an A record pointing to your server.
- `DEPLOY_USERNAME`: This secret corresponds to the username required for logging into the deployment server via SSH. The value for this secret can vary depending on your server setup. For example, it could be 'ubuntu', 'ec2-user', 'root', etc., depending on the operating system and configuration of the deployment server.
- `DEPLOY_KEY`: This is the private SSH key used for remote access to your deployment server or application host. This secret is crucial for securing your SSH connections. It's important to generate this key securely and to store it safely within your GitHub secrets to ensure your server remains secure.
- `LETSENCRYPT_EMAIL`: This secret represents the email address used for Let's Encrypt certificate registration. Let's Encrypt provides free automated TLS (Transport Layer Security) certificates, which help secure the communication between your server and its clients. The email is used to receive important notices.

These secrets are utilized in both jobs, and they provide a secure way to use sensitive data across multiple steps.

```yml
# Copy only the docker-compose.yml to remote server home folder
- name: copy files to target server via scp
  uses: appleboy/scp-action@v0.1.3
  with:
     host: ${{ secrets.DEPLOY_HOST }}
     username: ${{ secrets.DEPLOY_USERNAME }}
     port: 22
     key: ${{ secrets.DEPLOY_KEY }}
     source: "./docker-compose.yml,./docker-compose.prod.yml,./.env"
     target: "~/.deploy/${{ github.event.repository.name }}/"
```

In the example above, secrets are used to provide the `scp-action` with necessary information to copy our `docker-compose.yml`,`docker-compose.prod.yml`, and generated `.env` file to the remote server.

## How They All Work Together

Having a clear grasp of the components involved in our deployment pipeline, it's now time to delve into how they work together end to end to deploy your dockerized application. This section will help you visualize the bigger picture, breaking down the deployment process into a series of understandable steps.

### Setting the Stage: The Deployment Process

The deployment process is a series of operations that involve our main actors: GitHub, Docker, and your Linux server. Here is how each step unfolds:

1. The process begins when the user triggers an event such as a push to the `main` or `master` branch, creates a release, or manually triggers a dispatch.
2. The GitHub repository responds to this by initiating the workflow defined in our GitHub Action.
3. The GitHub Action then retrieves the necessary secrets stored in GitHub Action Secrets. These are essential for secure operations such as logging into the GitHub Container Registry (GHCR).
4. After logging in, the GitHub Action builds the Docker image from your application's source code and pushes the image to GHCR.
5. Once the Docker image is securely stored in GHCR, the GitHub Action uses Secure Copy Protocol (SCP) to transfer the `docker-compose.yml`,`docker-compose.prod.yml`, and `.env` files to your remote Linux server.
6. Using SSH, the GitHub Action then logs into the remote server and runs the database migrations service defined in your `docker-compose.yml` file called the `app-migrate` service.
7. Finally, the GitHub Action instructs your server to pull the new Docker image from GHCR and start your application using Docker Compose.

![](./img/posts/docker-compose/sequence-diagram.PNG)

Remember, this series of steps repeats each time a change triggers the GitHub Action, ensuring that your application is continuously integrated and deployed.

### Flexibility

It's important to note that this process is not exclusive to a specific kind of application. The versatility of Docker allows us to adapt this process to deploy any web application that can be containerized using Docker, giving you a reliable and repeatable deployment process for a broad range of web applications.

## Monitoring with LazyDocker

LazyDocker is a terminal UI for both Docker and Docker Compose. It allows you to monitor your Docker containers and services in real-time, giving you a visual representation of your application's health.

Part of what makes LazyDocker such an awesome tool is that you can use it anywhere from a terminal.

![](./img/posts/docker-compose/lazydocker.png)

To run it as a docker container itself, you can use the following command.

::: sh
docker run --name lazydocker --rm -it -v /var/run/docker.sock:/var/run/docker.sock -v ~/.lazydocker:/.config/jessedufffield/lazydocker lazyteam/lazydocker
:::

Or better yet, use it as an alias in your `.bashrc` or `.zshrc` file.

::: sh
alias lazydocker="docker run --name lazydocker --rm -it -v /var/run/docker.sock:/var/run/docker.sock -v ~/.lazydocker:/.config/jessedufffield/lazydocker lazyteam/lazydocker"
:::

So you can run `lazydocker` easily from your terminal.

## Concrete Example: Deploying a .NET Application

Let's see how you can use it to deploy a specific application. In this section, we will look at how to deploy a .NET application using the `release.yml` workflow.
It needs 3 files to run, as well as some GitHub Actions secrets like `DEPLOY_HOST`, `DEPLOY_USERNAME`, `DEPLOY_KEY`, and `LETSENCRYPT_EMAIL`.

### docker-compose.yml

This file is used by Docker Compose to define the services that make up your application, so they can be run together in an isolated environment.
The `release.yml` expects a web application service called `app` and a database migration service called `app-migration` to be declared.

```yaml
version: "3.9"
services:
    app:
        build: .
        restart: always
        ports:
            - "5000:80"
        environment:
            VIRTUAL_HOST: ${HOST_DOMAIN}
            LETSENCRYPT_HOST: ${HOST_DOMAIN}
            LETSENCRYPT_EMAIL: ${LETSENCRYPT_EMAIL}
        volumes:
            - app-mydb:/app/App_Data
    # Dotnet migrations using ServiceStack AppTasks
    app-migration:
        build: .
        restart: "no"
        profiles:
            - migration
        command: --AppTasks=migrate
        volumes:
            - app-mydb:/app/App_Data

volumes:
    app-mydb:
```

This file is also designed to be used in a local development environment. It uses the `build` keyword to build the Docker image from the Dockerfile in the current directory.

### docker-compose.prod.yml

This file is similar to `docker-compose.yml`, but it is specifically tailored for your production environment. Instead of building from the Dockerfile like in the development version, it pulls a specific image from a repository (`ghcr.io/${IMAGE_REPO}:${RELEASE_VERSION}`) which come from a `.env` file.
It also connects to an external network (`nginx`) which is our reverse proxy on our target Linux server.

```yaml
version: "3.9"
services:
    app:
        image: ghcr.io/${IMAGE_REPO}:${RELEASE_VERSION}
        restart: always
        ports: !reset ["80"]
        container_name: ${IMAGE_REPO}-app
        environment:
            VIRTUAL_HOST: ${HOST_DOMAIN}
            LETSENCRYPT_HOST: ${HOST_DOMAIN}
            LETSENCRYPT_EMAIL: ${LETSENCRYPT_EMAIL}
        volumes:
            - app-mydb:/app/App_Data
    app-migration:
        image: ghcr.io/${IMAGE_REPO}:${RELEASE_VERSION}
        restart: "no"
        container_name: ${IMAGE_REPO}-app-migration
        profiles:
            - migration
        command: --AppTasks=migrate
        volumes:
            - app-mydb:/app/App_Data

networks:
  default:
    external: true
    name: nginx

volumes:
    app-mydb:
```

### Dockerfile

The Dockerfile is a text document that contains all the commands a user could call on the command line to assemble an image. In this example, it first creates a build environment based on `dotnet/sdk:6.0-focal`, copies your application code into the container, and restores any necessary .NET dependencies. It then switches to your application's directory and publishes your application in release mode. Finally, it creates the runtime environment based on `dotnet/aspnet:6.0-focal`, copies the built application from the previous stage, and sets the Docker entrypoint to run your application.

```dockerfile
# Example dotnet app built from Dockerfile
FROM mcr.microsoft.com/dotnet/sdk:6.0-focal AS build
WORKDIR /app

COPY . .
RUN dotnet restore

WORKDIR /app/MyApp
RUN dotnet publish -c release -o /out --no-restore

FROM mcr.microsoft.com/dotnet/aspnet:6.0-focal AS runtime
WORKDIR /app
COPY --from=build /out .
ENTRYPOINT ["dotnet", "MyApp.dll"]
```

### .env (generated)

This file, `.env`, is a plain text file that stores environment variables for your Docker containers. Docker Compose automatically looks for this file in the same deployment directory as your `docker-compose.yml` and `docker-compose.prod.yml` files, and variables defined in `.env` can be read into the Compose file. The variables in this file could be secrets, URLs, or other configuration values. The `.env` file itself is typically not included in source control and instead, you might include a `.env.example` file to highlight the required environment variables.
This means when using `docker-compose.yml` locally, you can have a `.env` file with your local database credentials, and when using `docker-compose.prod.yml` on your server, you can have a `.env` file with your production database credentials, for example.

## Applying the Deployment Pattern: A Practical Guide

The following step-by-step guide will show you how to create, prepare, and deploy your .NET application using best practices.

### 1. Building Blocks: Creating Your .NET Application

Kick-off your development process by creating your .NET application. In this example, we use the ServiceStack's `x` tool to create our web app from a template with the command `x new web MyApp`.

Your application will have a structure that may look something like this:

```
MyApp/
|-- MyApp/
|   |-- wwwroot/
|   |-- Configure.AppHost.cs
|   |-- Program.cs
|-- MyApp.ServiceModel/
|-- MyApp.ServiceInterface/
|-- MyApp.Tests/
|-- MyApp.sln
|-- Dockerfile
|-- docker-compose.yml
|-- docker-compose.prod.yml
|-- .gitignore
```

### 2. Join the Hub: Pushing Your Application to GitHub

Once your application is set up, you can push it to GitHub. JetBrains Rider IDE has a handy "Share On GitHub" functionality that streamlines this process. Here's how you use it:

- Right-click on your solution.
- Select `Git -> GitHub -> Share Project on GitHub`.
- Enter your repository name and description.
- Click `Share`.

Your .NET application is now on GitHub, ready for collaboration and continuous integration.

### 3. Implementing GitHub Actions for CI

To automate the build and test process every time you push to your GitHub repository, you can use GitHub Actions. A minimal .NET workflow file, `build.yml`, can be created and placed in the `.github/workflows` directory. Here's a minimal example:

```yaml
name: Build
on: [push]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v2

    - name: Setup .NET
      uses: actions/setup-dotnet@v1
      with:
        dotnet-version: '6.0.x'

    - name: Restore dependencies
      run: dotnet restore

    - name: Build
      run: dotnet build --no-restore
```

You can also add a `test` step to run your tests here.

This will run alongside any other workflows, like the `release.yml` outlined above, to ensure your application is always in a deployable state.
When the `Build` step completes, it will trigger the `release.yml` workflow.

### 4. Setting Up and Using GitHub Action Secrets

Next, you'll need to create secrets for sensitive data. In GitHub, you can store them as "Secrets". Follow these steps:

- Go to your GitHub repository and click on `Settings`.
- Click on `Actions`->`Secrets` in the left sidebar.
- Click on `New repository secret`.
- Enter the `Name` and `Value` of the secret.
- Click on `Add secret`.

Create the following secrets:

- `DEPLOY_HOST`: This secret represents the hostname to which SSH connections will be made during the deployment phase. This could be an IP address or a subdomain, as long as it's correctly set with an A record pointing to your server.
- `DEPLOY_USERNAME`: This secret corresponds to the username required for logging into the deployment server via SSH.
- `DEPLOY_KEY`: This is the private SSH key used for remote access to your deployment server or application host.
- `LETSENCRYPT_EMAIL`: This secret represents the email address used for Let's Encrypt certificate registration.

### 5. Finding Your Home: Create an A Record DNS Entry

To link your domain to your server, you need to create an A Record DNS entry. Here's a generalized step-by-step:

- Go to your DNS provider's website and sign in.
- Find the domain you want to update and go to its DNS records.
- Create a new record. For the type, select `A`.
- Enter your server's IP address in the `Value` or `Points to` field.
- Save the changes.

Now, you can populate the `DEPLOY_HOST` secret in GitHub with your DNS.
This will be used by the `release.yml` workflow to deploy your application to your server via SSH.

### 6. Configuring Linux Server with Docker

By now, you should have a Linux server with Docker installed, and the NGINX reverse proxy with LetsEncrypt running, as we did in the previous section.

Your server will also need to be accessible via SSH on port 22 so that GitHub Actions can deploy your application.

### 7. Commit Change and Deploy Application

Now, commit any changes and push to your GitHub repository. If you've set up your GitHub Actions correctly, the CI will kick off. After a successful build, your application will be deployed and accessible from your specified domain.

## Deploying Multiple Applications on the Same Server

### Same Pattern, Multiple Applications

One of the core strengths of Docker is the ability to isolate and manage applications in their individual containers. This means you can deploy numerous applications, each from its separate GitHub repository, onto the same Linux server. All these applications can coexist and operate independently, provided each one is correctly dockerized. The release pattern remains unchanged and consistent to apply.

```markdown
1. MyApp1/ -> GitHub Repo 1 -> Docker Image 1 -> Server (Container 1)
2. MyApp2/ -> GitHub Repo 2 -> Docker Image 2 -> Server (Container 2)
3. MyApp3/ -> GitHub Repo 3 -> Docker Image 3 -> Server (Container 3)
```

![](./img/posts/docker-compose/graph-diagram.PNG)

### Organization Secrets

To maintain a streamlined deployment process when dealing with multiple applications, you can utilize the GitHub Actions' Organization Secrets. This feature allows secrets to be shared across multiple repositories in an organization, which saves time and reduces redundancy. The only secret that needs to be set up individually for each repository would be the `DEPLOY_HOST` and corresponding DNS for each application.

To set up organization secrets:

- Go to your GitHub organization's settings.
- Click on `Secrets` in the left sidebar.
- Click on `New organization secret`.
- Enter the `Name` and `Value` of the secret.
- Click on `Add secret`.

Each deployed application now shares the organization-level secrets, streamline the setup process for new applications to a new DNS entry and `DEPLOY_HOST` environment variable.

And since every GitHub Repository in the organization is unique, there is no conflicting files deployed to the same server.

### Cost Optimization: Using a Single Server

In our previous post,[In pursuit of the best value US cloud provider](https://servicestack.net/posts/hetzner-cloud), we looked for the most cost-effective cloud provider. We found that Hetzner Cloud offers the best value for money, with a powerful server costing around $10 USD per month. This means you can deploy multiple applications on a single server, saving you money and resources.

To host lots of our demo applications, we are doing exactly this, meaning we have a per container of less than $0.50 USD per month.

<div class="mx-auto mt-4 mb-4">
    <div class="inline-flex justify-center w-full">
      <img src="/img/posts/docker-compose/cloud-cost-comparison.PNG" alt="">
    </div>
</div>

## Conclusion

By avoiding Kubernetes, you can have less complex control your deployment process, and have more control over your applications. You can also save money by using a single server to host multiple applications. The release pattern is a flexible, yet effective way to deploy your applications, and it can be applied to any programming language or framework.

## Feedback

If you have any feedback on this article, please let us know by commenting below, joining our [Discord](https://servicestack.net/discord), [GitHub Discussions](https://servicestack.net/ask), or [Customer Forums](https://forums.servicestack.net).


# Deploying with Kamal
Source: https://docs.servicestack.net/kamal-deploy

ServiceStack templates now support deployment using Kamal, a CLI tool from the BaseCamp team that simplifies containerized application deployments. Kamal wraps SSH and Docker to streamline self-hosting while maintaining GitHub Actions as the CI runner.

<lite-youtube class="w-full mx-4 my-4" width="560" height="315" videoid="-mDJfRG8mLQ" style="background-image: url('https://img.youtube.com/vi/-mDJfRG8mLQ/maxresdefault.jpg')"></lite-youtube>

## Overview

Kamal enables simple commands to deploy containerized applications to Linux hosts, handling:
- Bootstrap configuration
- Reverse proxy setup
- SSL certificate provisioning
- Zero-downtime deployments
- Health checks on deploy
- Rolling back changes

::: info
Kamal is built by the BaseCamp team, developers of Hey email service and BaseCamp project management tool. For comprehensive documentation on all Kamal features, visit [https://kamal-deploy.org/](https://kamal-deploy.org/)
:::

## Getting Started

### Prerequisites
- A domain name
- A Linux host (e.g., VPS from providers like Hetzner)
- GitHub account for CI/CD

### Initial Setup

1. Create a new ServiceStack application:
```bash
x new blazor-vue MyApp
```

2. Generate deployment SSH key:
```bash
ssh-keygen -t ed25519 -C "deploy@myapp" -f ./deploy-key
```

3. Copy public key to enable server access:
```bash
cat ~/deploy-key.pub | ssh <user>@<your-ip> "cat >> ~/.ssh/authorized_keys"
```

### GitHub Actions

The template includes a GitHub Actions workflow that is broken up into 3 steps that trigger on push to the `main` branch, and then on successful build and test, it will deploy the application to your server.

Once you create your GitHub repository, add the `SSH_PRIVATE_KEY` secret to your repository settings with the contents of your private key file.

```bash
gh secret set PRIVATE_SSH_KEY < ~/deploy-key
```

### Configuration

Update `config/deploy.yml` with your deployment settings:

```yaml
service: myapp
image: your-github-username/myapp

servers:
  web:
    - <your-server-ip-address>

proxy:
  ssl: true
  host: myapp.example.com
```

::: info
The `image` value should match your GitHub repository path on ghcr.io. For example: `ghcr.io/username/repository`
:::

Once you make these changes, commit and push to your repository to trigger the GitHub Actions workflow.

Kamal will deploy the required services including Docker and Kamal Proxy if you server doesn't already have them installed.

:::info
When using ASP.NET Core applications with Kamal-Proxy, ensure your application is running with the environment variable `ASPNETCORE_FORWARDEDHEADERS_ENABLED` set to `true`. 
The template has this by default, but if you are getting errors with 302 redirects, ensure this is set.
:::

The authentication between GitHub Container Registry (ghcr.io) and your server is handled by the GitHub Actions workflow, the `deploy.yml` and [Kamal Secrets](https://kamal-deploy.org/docs/configuration/environment-variables/#secrets).

:::info
You can still use the Kamal CLI locally, but if you want to directly push deployments with `kamal deploy`, you will need to locally populate `KAMAL_REGISTRY_USER` and `KAMAL_REGISTRY_PASSWORD` with your GitHub username and a GitHub Personal Access Token with `read:packages` scope.
:::

## Common Kamal Commands

Kamal provides several useful commands for managing your deployment:

```bash
# View deployment details
kamal details

# Check application logs
kamal app logs

# Deploy new version
kamal deploy

# Restart application
kamal app boot
```

::: info
Kamal commands are context-aware and will use the configuration from your current application directory. This makes managing multiple applications across different servers a lot easier as more applications are added.
:::

## Additional Containers

Kamal supports extensive configuration options including "accessories" for additional features like databases, caches, and more. See the [Kamal documentation](https://kamal-deploy.org/docs/configuration/accessories/) for more information.

## Troubleshooting

### Initial deployment fails

If you are having issues with the initial deployment, an earlier bootstrap of the server via GitHub Actions may have failed.
Delete the `.<app-name>` file in your deployment user's home directory and re-run the GitHub Actions workflow to re-bootstrap the server.

### Missing the service label

If you are getting:

  Image ghcr.io/netcoreapps/northwindauto:latest is missing the 'service' label

Ensure that your AppHost csproj file has `ContainerLabel` with the value matching the `service` in your `deploy.yml` file.


# Deploying to Digital Ocean via GitHub Actions and SSH
Source: https://docs.servicestack.net/do-github-action-mix-deployment

![](/img/pages/mix/github-action-do-tutorial-header.png)

GitHub Actions are a great tool for automating builds, tests and deployments in a composable and flexible way. The ServiceStack `x` tool provides mix templates to incorporate into your existing applications and repositories that can speed up different types of workflows.

We've created a mix template for building and deploying your ServiceStack app with GitHub Actions, GitHub Container Repository and Docker Compose all via SSH for a minimalist server hosting setup.

<lite-youtube class="w-full mx-4 my-4" width="560" height="315" videoid="0PvzcnxlBvc" style="background-image: url('https://img.youtube.com/vi/0PvzcnxlBvc/maxresdefault.jpg')"></lite-youtube>

Specifically, we'll be using `x mix build release-ghr-vanilla` which has GitHub actions configured ready to deploy your ServiceStack application when a new GitHub release is created. This can be run at the root of your local repository folder, for example if you wanted to create an empty web application you would run:

```
git clone git@github.com:<your user or org>/DropletApp.git
cd DropletApp
x new web
x mix build release-ghr-vanilla
# 'y' to process with writing files from x mix.
git add -A
git commit -m "New ServiceStack project"
git push
```

Pushing your new application to GitHub, the `build.yml` will run a `dotnet build` and `dotnet test` within the CI environment. For deployments, we want to get a server setup for hosting the new application.

::: info
`x mix release-*` are designed to be used with ServiceStack applications that were created with most `x new` project templates that follow the ServiceStack recommended project structure. They are designed to be a starting point that you can edit once created to suit your needs.
:::

## Digital Ocean Droplets Host
In this tutorial, we'll be using a Digital Ocean Droplet as the target server and walk through the steps required to setup this automated deployment process for your ServiceStack application.

### Droplet Setup
Since we are deploying a simple ServiceStack application, we are going to use the cheapest `Basic Droplet` at $5USD/month. This is plenty to host even multiple low traffic ServiceStack applications but your use case might have different hardware requirements.

### Create your new droplet
The basic droplet we are going to create will have the following configuration.

- Distribution - Ubuntu 20.04 LTS
- Plan - Basic
- $5/month
- Datacenter region - Which ever suits your use case
- VPC - default
- Authentication - SSH keys, create a new one just for this server, follow the instructions on the right hand panel.

The rest of the options, leave as default.

### Create your new SSH key
If you ended up using an existing SSH key, now would be the time to create one specifically for deploying applications to this server, and **only that function**.

The reason this is important because we will be using the private key within our GitHub Actions, which means the private key generated will be leaving your local computer and stored within GitHub Secrets. In the event that this key is compromised, we want to limit its use.

Digital Ocean has some excellent documentation for [this process here](https://www.digitalocean.com/community/tutorials/how-to-set-up-ssh-keys-on-ubuntu-20-04).


### Enable floating IP
Once your Droplet has started, you'll want to `Enable Floating IP` so that we have a static public IP address to route to for a domain/subdomain.

This can be done via 
- `Manage` 
- `Droplets`
- `Select your droplet`
- click `Enable Floating IP` at the top right.

![Enable Floating IP option](/img/pages/mix/digital-ocean-enable-floating-ip.png)

## Docker setup
Now that our Droplet is running and has a public IP address, we'll want to install Docker and docker compose.

SSH into your Droplet using the appropriate SSH key and your preferred SSH client (straight `ssh`, Putty for Windows, etc).

Eg, with a Linux `ssh` client, the command would be `ssh root@<your_IP_or_domain>` as `root` is the default user setup when creating an Ubuntu droplet.

::: info
the user may change depending on how your server is setup. See `man ssh` for more details/options.
:::

### Install docker and docker compose
Installing Docker for Ubuntu 20.04 can be done via the repository with some setup or via Docker provided convenience scripts. For a more detailed walk through, [DigitalOcean have a good write up here](https://www.digitalocean.com/community/tutorials/how-to-install-and-use-docker-compose-on-ubuntu-20-04). Scripted included below for ease of use.

#### Docker via convenience script

```bash
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh
```

::: info
These scripts required sudo privileges, see [Docker notes regarding security](https://docs.docker.com/engine/install/ubuntu/#install-using-the-convenience-script).
Full repository based [script available here](https://docs.docker.com/engine/install/ubuntu/#install-using-the-repository).
Docker is installed remoting under root in this example for simplification. Information of Docker security can be found in the [Docker docs](https://docs.docker.com/engine/security/#docker-daemon-attack-surface)
:::

### [Docker compose install](https://docs.docker.com/compose/install/linux/#install-using-the-repository)

Run `docker compose version` to confirm.

::: info
Ensure you have v2+ of Docker Compose
A compatibility script can be used for `docker-compose` via the following script.
`echo 'docker compose --compatibility "$@"' > /usr/local/bin/docker-compose`
`sudo chmod +x /bin/docker-compose`
:::

### Get nginx reverse proxy and letsencrypt companion running
Now we have Docker and Docker Compose installed on our new Droplet, we want to setup an nginx reverse proxy running in Docker. This will handle mapping requests to specific domain/subdomain requests to specific docker applications that have matching configuration as well as TLS registration via LetEncrypt. When a new docker container starts up and joins the bridge network, the nginx and letsencrypt companion detect the new application and look to see if routing and TLS certificate is needed.

In the `x mix release-ghr-vanilla` template, we include `deploy/nginx-proxy-compose.yml` file which can be copied to the droplet and run.

Here is the nginx Docker Compose file in full.

```yml
version: '2'

services:
  nginx-proxy:
    image: jwilder/nginx-proxy
    container_name: nginx-proxy
    restart: always
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - conf:/etc/nginx/conf.d
      - vhost:/etc/nginx/vhost.d
      - html:/usr/share/nginx/html
      - dhparam:/etc/nginx/dhparam
      - certs:/etc/nginx/certs:ro
      - /var/run/docker.sock:/tmp/docker.sock:ro
    network_mode: bridge

  letsencrypt:
    image: jrcs/letsencrypt-nginx-proxy-companion:2.0
    container_name: nginx-proxy-le
    restart: always
    environment:
      - DEFAULT_EMAIL=you@example.com
    volumes_from:
      - nginx-proxy
    volumes:
      - certs:/etc/nginx/certs:rw
      - acme:/etc/acme.sh
      - /var/run/docker.sock:/var/run/docker.sock:ro
    network_mode: bridge

volumes:
  conf:
  vhost:
  html:
  dhparam:
  certs:
  acme:
```

You can use `scp` or shared clipboard to copy the short YML file over. For this example, we are going to copy it straight to the `~/` (home) directory.

```
scp -i <path to private ssh key> ./nginx-proxy-compose.yml root@<server_floating_ip>:~/nginx-proxy-compose.yml
```

Once copied, we can use `docker compose` to bring up the nginx reverse proxy.

:::sh
docker compose -f ~/nginx-proxy-compose.yml up -d
:::

To confirm these are running, you can run `docker ps` so have a look at what containers are running on your server.

## Domain setup
Now our droplet server is all setup to host our docker applications, we want to make referring to our server easier by setting up a DNS record.

Specifically, we want to create an `A` record pointing to our Floating IP of our Droplet server.

::: info
You will need to use your DNS provider service to manage the DNS records of your domains.
:::

## GitHub Repository Setup
With the Droplet server all setup, first we'll need an application to deploy!

Create a new repository on GitHub. This setup will work with public or private repositories, select your options and clone it to your local machine.

```bash
git clone <GitHub URL>
cd <project name>
```

We are going to use `x new web` as a command to create a blank ServiceStack application. Run this in your newly cloned repository folder, the project name will be derived from the repository directory name.

::: info
If you create the project in a new directory beforehand and want to name it, use `x new web <project name>`.
:::

The `x new` command gives us a working ServiceStack project from a template, `x mix` allows us to add additional templated files that work with templated ServiceStack projects.

Now our project is created, you can mix in our GitHub Action templates in the local repository folder by running:

```
x mix build release-ghr-vanilla
```

The `build` mix template provides a GitHub Action that builds and tests our dotnet project. The `release-ghr-vanilla` provides a GitHub Action that uses Docker to package the application, pushes the Docker image to GitHub Container Registry (ghcr.io) and deploys the application via SSH + `docker compose` to our new Droplet.

Just like other `x mix` templates ServiceStack provides, these are a *starting* point to help get things running quickly with known patterns. Unlike external dependencies, they just copy the templated code that is editable and not tied to any code generation service that will update these files.

Files provided by the `release-ghr-vanilla` are:

- **.github/workflows/release.yml** - Release GitHub Action Workflow
- **deploy/docker-compose-template.yml** - Templated docker compose file used by the application
- **deploy/nginx-proxy-compose.yml** - File provided to get nginx reserve proxy setup as used by steps above.
- **Dockerfile** - Self contained Docker that builds, publishes and hosts your application.


### Make sure GitHub `Enable improved container support` is turned on
The account or organization of your repository at the time of writing needs to "Enable improved container support". 

::: info
This step may no longer be required once Improved Container Support is generally available.
:::

Goto: 

- `Account`
- `Settings`
- `Packages`
- `Improved container support`
- select `Enable improved container support`
- Save.

::: info
See [GitHub Docs](https://docs.github.com/en/packages/guides/enabling-improved-container-support) for details.
:::

Once these steps are done, our GitHub Actions will be able to push Docker images to GitHub Container Registry.

#### Full Steps

**Create new repository in GitHub first.**

```bash
git clone git@github.com:<your user or org>/WebApp.git # Where "WebApp" is the name of your repository
cd WebApp
x new web
x mix build release-ghr-vanilla
git add -A
git commit -m "Add new ServiceStack project with GitHub Action files"
git push
```

##### Steps overview

- Create a new GitHub repository
- Clone new repository locally
- Change directory to new repository
- Locally create ServiceStack project using `x new`.
- Mix in GitHub Actions using `x mix`
- Commit and push changes to GitHub

### Create secrets
The `x mix` templates needs **the following information** to perform the deployment, this information is added to the GitHub repository as the following *secrets*.

- DEPLOY_HOST - hostname used to SSH to, this should be a domain or subdomain with A record pointing to the server's IP adddress.
- DEPLOY_USERNAME - the username being logged into via SSH. Eg, `ubuntu`, `ec2-user`, `root` etc.
- DEPLOY_KEY - SSH private key used to remotely access deploy server/app host.
- LETSENCRYPT_EMAIL - Email address for your TLS certificate generation

These secrets can use the [GitHub CLI](https://cli.github.com/manual/gh_secret_set) for ease of creation. Eg, using the GitHub CLI the following can be set.

```bash
gh secret set DEPLOY_HOST -b"<DEPLOY_HOST, domain or subdomain for your application and server host.>"
gh secret set DEPLOY_USERNAME -b"<DEPLOY_USERNAME, the username being logged into via SSH. Eg, `ubuntu`, `ec2-user`, `root` etc.>"
gh secret set DEPLOY_KEY < [path to ssh key]
gh secret set LETSENCRYPT_EMAIL -b"<LETSENCRYPT_EMAIL, Email address for your TLS certificate generation, eg me@example.com>"
```

Repository secrets can be created under Settings->Actions->Secrets.

### Tag release
To kick off any new deployment, we use GitHub Releases.

Provide a version number and name, the version will be used to tag the Docker image in GHCR.io. If you are using the GitHub CLI, you can also do this via the command line. For example,

:::sh
gh release create v1 -t "v1" --notes ""
:::

Go to the Actions tab in your repository to see the progress of your deployment.

::: info
The initial deployment might take upto a minute for LetsEncrypt to generate and use the certificate with your domain. Make sure your DNS is all setup **before publishing the Release**, otherwise further delays related to DNS TTL will likely occur.
If you are having problems with your app hosting, be sure to configure the logs in the nginx and your app docker containers for any startup issues. You can also run in attached mode to watch the output of these containers via `docker compose -f ~/nginx-proxy-compose.yml up`.
:::

### GitHub Container Registry Pricing
If you're already have a Pro or Team plan, you get free allowances to using the GitHub Container Registry. It has the [same pricing as the GitHub Packages](https://docs.github.com/en/github/setting-up-and-managing-billing-and-payments-on-github/about-billing-for-github-packages#about-billing-for-github-packages) product which is summarized as the following for Pro or Team.

- 2GB storage free
- 10GB data transfer free
- Additional storage $0.25 per GB
- Additional transfer out $0.50 per GB (GitHub Actions are free)

With Docker images though, they can get large pretty quickly. While GitHub Container Registry is still in beta, it is free to use but additional storage and transfer costs are something to keep in mind. Hopefully use of retention policies and other features can help manage to keep these prices down.

### Wrapping up
Having a CI process from the very start of a project/prototype is something that pays off quickly, even as a solo developer. The `release-ghr-vanilla` template is designed to help get that process started by providing a "no fuss" pattern for prototyping ideas and keeping costs down while giving a dockerized path forward as your hosting requirements change. GitHub Actions provide a great way to build and maintain your CI process right where your code lives, and even though GitHub Container Repository is in the early stage, we think it provides a simplified workflow that works well for the indie/solo developer as well as teams. We intend to put together more of these templates and patterns for different use cases, feel free to give us feedback and let us know what you'd like to see!


# GitHub Actions mix template - Deploy to AWS ECS
Source: https://docs.servicestack.net/mix-github-actions-aws-ecs

AWS EC2 Container Service (ECS) is a managed container orchestration environment that while not as flexible as Kubernetes, it provides some great integration if you are already in an AWS environment, especially for hosting HTTP APIs. However, when just getting started on a project, setting up Application Load Balancers, CloudFront CDN, AutoScaling Groups etc can be a high entry point from a monthly cost and complexity standpoint. It also provides an alternative to 'serverless' solutions that avoid issues like cold starts as well as polluting any of your code with cloud provider specific implementation.

We've created a new `x mix release-ecr-aws` template to try and help solo developers and small teams that think they might use a more mature AWS ECS setup in the future, but don't have the budget or just want a cheap host for a prototype/demo. Once your product grows, integrating all the other AWS infrastructure is a smaller and clearer path than trying to do it from the very beginning, not knowing if you'll ever need it.

We're also going to leverage the powerful GitHub Actions platform so that the distance between your CI environment and code is as small as possible. The `x mix release-ecr-aws` template provides a starting point for your ServiceStack application to have a CI setup and deploy to a **single** server in ECS to keep costs down. This is good for prototyping an idea or any low request rate applications where you think you'll move into a more standard ECS infrastructure pattern as your application usage increases.

### Hosting setup

Since we are trying to keep costs at a minimal, just like our Digital Ocean hosting, we are using just 1 EC2 instance to (potentially) host multiple low traffic applications with minimal infrastructure. In this pattern we are using

- Route53 (DNS)
- 1 EC2 instance
- ECS (to manage our deployments)
- ECR (to stored our docker images)

The lion share of the costs will come from the single EC2 instance which you can match for size depending on how many applications you want to host on the 1 instance, a t3.micro is ~$8/month. ECR (docker repository) does cost money for storage at ~$0.10 per GB/month. $0.50 a month for a Route53 hosted zone. So while this is not quite as cheap as Digital Ocean setup we've shown, it is a stepping stone into using AWS ECS for a much larger horizontally scaling hosting setup without much change.

Keeping parts to our setup to a minimum, Route 53 points each subomain to the IP address of our EC2 instance, nginx-proxy routes traffic to each application running in docker.

![](/img/pages/mix/cloudcraft-host-digram-release-ecr-aws.png)

### Deployment setup

In the `release-ecr-aws` template we are using `ecr` for the storage of our Docker images and ECS for the deployment. Everything runes on GitHub Actions as provided by the template and your specific details are provided by GitHub Secrets (stored at the repository or organization level).

The GitHub Actions require an ECS cluster to be created with a single EC2 instance as member of that cluster. The rest of the AWS resources are created by the GitHub Action the first time it runs.

![](/img/pages/mix/release-ecr-aws-diagram.png)

AWS ECS Agent that runs on the EC2 instance manages with ECS when to create/destroy containers. Since there is only 1 EC2 instance in the cluster, everything runs on the same instance.


### Getting started

Now that we have the high level overview out of the way, lets get your apps running! For this tutorial, we'll start with a new ServiceStack application using `x new` and incorporate the GitHub Action templates to get our CI environment started.

First, create your new  git repository on GitHub.

![](/img/pages/mix/github-create-new-repo.png)

Once created, follow the GitHub wizard and clone it to your local machine.

Then you can use the following commands to get your new ServiceStack application setup in GitHub with GitHub Actions.
> Choose the appropriate web template from `x new` for your needs as most templates are compatible GitHub Actions `x mix` templates.
> `x new web` will create a project in an existing directory, `x new web WebApp` will create the project in a new `WebApp` folder.

```
git clone <Git URL>
cd WebApp
x new web
git add -A
git commit -m "Initial commit"
git branch -M main
git remote add origin <copy git URL from GitHub page>
git push -u origin main
x mix build release-ecr-aws
git add -A
git commit -m "Add GitHub Action files"
git push
```

## AWS Setup

If you're use to setting up larger AWS infrastructure, you'll likely have experienced how costs can rise easily or seen complex infrastructure architected small for a web application doing 5 requests/sec with minimal users. These types of setups can be unnecessarily costly and complex and if you are a solo developer or small team (for which is pattern is more suited), is likely not suitable starting point. As your application infrastructure needs evolve, so can your cloud provider environment, this template provides a starting point with AWS ECS while keeping costs to a minimum.

As previously stated above, this template needs the following in AWS:

- A **dedicated** ECS cluster (not shared)
- Single EC2 server registered to that ECS cluster
- IAM User Credentials with `AmazonEC2ContainerRegistryFullAccess` and `AmazonECS_FullAccess` for use (exclusively) by GitHub Actions.
- Route53 (or other DNS manager) with an A record pointing to the EC2 instance public IP

### ECS Cluster

An empty ECS Cluster is needed as the GitHub Action process won't create this for you. You can choose to use the ECS Cluster wizard to create you an Auto-scaling Group, security groups, etc but the idea to start with is to just start with an empty ECS Cluster that an EC2 instance will join when we create it. This pattern doesn't scale horizontally with additional EC2 instances, but since it does use ECS, changing to use a load balancer and target groups can be introduced once they are needed.
> If you know you need horizontal scaling, it would be suggested to jump straight to using Application Load Balancer with Target Groups to manage your cluster services routing with the additional costs that come with that. The base cost of an ALB is ~$20/month, costs also scales up with requests. [See pricing details](https://aws.amazon.com/elasticloadbalancing/pricing/), the use of "LCU"s makes it highly dependent on your use case.

![](/img/pages/mix/create-cluster-ecs-1.png) ![](/img/pages/mix/create-cluster-ecs-2.png)


### EC2 Instance Setup

Now we can create the EC2 instance, the goal being is that our EC2 instance will join our cluster and run docker + ECS agent to work with this setup.

### Choose AMI

You need to use the AWS `Optimized for ECS` images, the easiest way to find the latest Amazon Linux 2 image for this is to go to the [AWS documentation for ECS-optimized AMIs and look up your region here](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/ecs-optimized_AMI.html#ecs-optimized-ami-linux).

Using the AMI ID (starts with `ami-`) at the bottom, search in the 'Community AMIs' tab on the first step of the `Launch EC2 Instance` wizard.

### Choose Instance Type

A t3.micro or larger will work fine, this pattern can be used to host multiple applications on the 1 server so if the number of applications gets larger, you might need a larger instance type.

::: info
this pattern is suitable for testing prototypes or low traffic applications as it is cost effective and makes it easy to bundle multiple apps onto 1 EC2 instance.
:::

### Configure Instance

Under `IAM role`, use the `ecsInstanceRole`, if this is not available, see [AWS documentation for the process of checking if it exists and creating it if needed](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/instance_IAM_role.html).

If you are *not* using your own generated Elastic IP, select `Enabled` for `Auto-assign Public IP`.

You will also want to add the following Userdata script (in the `Configure` step of the launch wizard) with your own `ECS_CLUSTER` value. This tells the ecs-agent running on the instance which ECS cluster the instance should join.

```bash
#!/bin/bash
cat <<EOS >/etc/ecs/ecs.config
ECS_CLUSTER=my-cluster
ECS_AVAILABLE_LOGGING_DRIVERS=["awslogs", "syslog"]
ECS_ENABLE_CONTAINER_METADATA=true
EOS
```

Note down your cluster name as it will need to be used to create the cluster in ECS before it is visible.
See [`ECS Container Agent Configuration`](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/ecs-agent-config.html) for more information.

### Add Storage

The default of 30gb is fine but take into account how large/how many applications you'll have running.

### Configure Security Groups

You'll want to expose at least ports 80, 443 and 22 for remote SSH access. We'll need SSH access for the next step, once setup it can be closed off or restricted.

### Setup Docker Compose and nginx-proxy

To route traffic to your ServiceStack applications and automate the generation and management of TLS certificates, an additional docker compose file is provided via the `x mix` template, `nginx-proxy-compose.yml` under the `deploy` directory of your repository. This docker-compose file is ready to run and can be copied to the deployment server.

::: info
This is done via docker compose rather than via ECS itself for simplicity as ECS is really not designed to make it easy to handle routing on the EC2 instance itself
:::

First you'll need to [install `docker compose`](https://docs.docker.com/compose/install/linux/#install-using-the-repository).

Run `docker compose version` to confirm.

::: info
Ensure you have v2+ of Docker Compose
A compatibility script can be used for `docker-compose` via the following script.
`echo 'docker compose --compatibility "$@"' > /usr/local/bin/docker-compose`
`sudo chmod +x /bin/docker-compose`
:::

To copy you can use scp or create a new file via server text editor to copy the short YML file over. For this example, we are going to copy it straight to the ~/ (home) directory.

```bash
scp -i <path to private ssh key> ./nginx-proxy-compose.yml ec2-user@<server_floating_ip>:~/nginx-proxy.compose.yml
```

For example, once copied to remote `~/nginx-proxy-compose.yml`, the following command can be run on the remote server.

```
docker compose -f ~/nginx-proxy-compose.yml up -d
```

This will run an nginx reverse proxy along with a companion container that will watch for additional containers in the same docker bridge network and attempt to initialize them with valid TLS certificates. This includes containers created and managed by the ECS agent.

::: info
If the container doesn't have the environment variable `VIRTUAL_HOST` set, it will be ignored. See the `task-definition-template.json` environment for more details
:::

### IAM Deploy User
For GitHub Actions to authenticate with AWS, you'll need a user with programmatic access and sufficient permissions to initialize the ECS + ECR resources. Once the initial deployment is complete, reduced access can be used for just uploading to ECR and promoting new releases to ECS. See the README in the Mix template for example of reduced access IAM policy for deployments.

![](/img/pages/mix/release-ecr-aws-iam-create.png)

### Route 53

To enough the nginx-proxy-lets-ecrypt-companion to work, a domain or subdomain DNS entry is needed to point to our EC2 host. You can use any DNS management tool, but in this example we will be using Route53.

![](/img/pages/mix/route-53-create-A-record.png)

### Validate AWS Setup
Once completed the above steps, we can validate some of the setup by performing the following tests.

 - Check our ECS cluster has 1 EC2 instance registered.
 - Get a response from nginx for the application's subdomain.

If both these are showing up, our AWS environment should be ready to deploy the application. 

### Setup Repository Secrets

The GitHub Action templates added using `x mix release-ecr-aws` get their input from GitHub Secrets. These can be added to the repository or to your organization if there are common ones you are using in multiple repositories. 

- AWS_ACCESS_KEY_ID - AWS access key for programmatic access to AWS APIs.
- AWS_SECRET_ACCESS_KEY - AWS access secrets for programmatic access to AWS APIs.
- AWS_REGION - default region for AWS API calls.
- AWS_ECS_CLUSTER - Cluster name in ECS, this should match the value in your Userdata.
- HOST_DOMAIN - Domain/sub-domain of your application, eg `my-app.example.com` .
- LETSENCRYPT_EMAIL - Email address, required for Let's Encrypt automated TLS certificates.

These secrets can use the [GitHub CLI](https://cli.github.com/manual/gh_secret_set) for ease of creation. Eg, using the GitHub CLI the following can be set.

```bash
gh secret set AWS_ACCESS_KEY_ID -b"<AWS_ACCESS_KEY_ID>"
gh secret set AWS_SECRET_ACCESS_KEY -b"<AWS_SECRET_ACCESS_KEY>"
gh secret set AWS_REGION -b"<AWS_REGION, eg us-east-1>"
gh secret set AWS_ECS_CLUSTER -b"<AWS_ECS_CLUSTER, eg my-apps>"
gh secret set HOST_DOMAIN -b"<HOST_DOMAIN, eg my-app.example.com>"
gh secret set LETSENCRYPT_EMAIL -b"<LETSENCRYPT_EMAIL, eg me@example.com>"
```

These secrets are used to populate variables within GitHub Actions and other configuration files.

For the AWS access, a separate user specifically for deploying via GitHub Actions should be used.

The GitHub Action template in `.github/workflows/release.yml` is there as a starting point and should be edited as required. The idea is that you can evolve and change these to your needs as your application grows.

### Deploying your application

To start any new deployment, we use GitHub Releases.

![](/img/pages/mix/github-create-new-release.png)

Provide a version number and name, the version will be used to tag the Docker image in ECR. If you are using the GitHub CLI, you can also do this via the command line. For example,

```
gh release create v1.0 -t "CI Deploy" --notes ""
```

Go to the Actions tab in your repository to see the progress of your deployment.

![](/img/pages/mix/github-actions-workflows-release.png)

The initial deployment might take up to a minute for Lets-Encrypt to generate and use the certificate with your domain. Make sure your DNS is all setup before doing this, otherwise further delays related to DNS TTL will likely occur. If you are having problems with your app hosting, be sure to configure the logs in the nginx and your app docker containers for any startup issues. You can also run in attached mode to watch the output of these containers via docker compose -f ~/nginx-proxy-compose.yml up. Logs for your application are automatically setup to use CloudWatch under the name `{your-ecs-cluster-name}-{your-app-name}`.


### Wrapping up

Like our other GitHub Action templates, making it easier to have an automated CI environment setup and running from the beginning pays off very quickly. If you're confident you are going to be using ECS in the future or already have AWS as your cloud provider, using this template will help you get started cheaply whilst enabling you to expand and adjust your automated CI strategies as your needs evolve. 

Using ECS with a single EC2 instance is not a common pattern you'll see on AWS sales pitches or 'How to scale' guides. However, it does allow you to test your ideas, share your prototypes cheaply with friends and colleagues. Not everything has to be 'web scale' and starting from that point can be distracting and intimidating, not to mention expensive. Hopefully this pattern helps you build something small, test out your theories quickly while giving you a good base to build on as your application grows.

We intend to put together more of these templates and patterns for different use cases utilizing GitHub Actions, feel free to give us feedback and let us know what you'd like to see!


# An implementation-free logging API for .NET
Source: https://docs.servicestack.net/logging

**ServiceStack.Logging** is an implementation and dependency-free logging API with adapters for all of .NET's popular logging providers. It allows your business logic to bind to an easily-mockable and testable dependency-free interface whilst providing the flexibility to switch logging providers at runtime.

## Download on NuGet

Currently there are 5 different .NET logging providers available on NuGet:

**[NLog](https://nuget.org/packages/ServiceStack.Logging.NLog)**

:::copy
`<PackageReference Include="ServiceStack.Logging.NLog" Version="8.*" />`
:::

**[Elmah](https://nuget.org/packages/ServiceStack.Logging.Elmah)**

:::copy
`<PackageReference Include="ServiceStack.Logging.Elmah" Version="8.*" />`
:::

**[Log4Net](https://nuget.org/packages/ServiceStack.Logging.Log4Net)**

:::copy
`<PackageReference Include="ServiceStack.Logging.Log4Net" Version="8.*" />`
:::

**[EventLog](https://nuget.org/packages/ServiceStack.Logging.EventLog)**

:::copy
`<PackageReference Include="ServiceStack.Logging.EventLog" Version="8.*" />`
:::

**[SlackLog](https://www.nuget.org/packages/ServiceStack.Logging.Slack/)**

:::copy
`<PackageReference Include="ServiceStack.Logging.Slack" Version="8.*" />`
:::

**[SerilogLogger](https://www.nuget.org/packages/ServiceStack.Logging.Serilog/)**

:::copy
`<PackageReference Include="ServiceStack.Logging.Serilog" Version="8.*" />`
:::

::: info
The `ConsoleLogFactory` and `DebugLogFactory` and are already built-in and bind to .NET Framework's Console and Debug loggers.
:::

### Why a Logging Interface?

Even in the spirit of **Bind to interfaces, not implementations**, many .NET projects still have
a hard dependency to [log4net](http://logging.apache.org/log4net/index.html). 

Although log4net is the standard for logging in .NET, potential problems can arise from your libraries having a hard dependency on it:

* Your library needs to be shipped with a third-party dependency
* Potential conflicts can occur when different libraries have dependency on different versions of log4net (e.g. the 1.2.9 / 1.2.10 dependency problem).
* You may want to use a different logging provider (i.e. network distributed logging)
* You want your logging for Unit and Integration tests to redirect to the Console or Debug logger without any configuraiton.
* Something better like [elmah](http://code.google.com/p/elmah/) can come along requiring a major rewrite to take advantage of it

ServiceStack.Logging solves these problems by providing an implementation-free `ILog` interface that your application logic can bind to where your Application Host project can bind to the concrete logging implementation at deploy or runtime.

ServiceStack.Logging also includes adapters for the following logging providers:

* Elmah
* NLog
* Log4Net 1.2.10+
* Log4Net 1.2.9
* EventLog
* SlackLog
* Serilog
* Console Log
* Debug Log
* Null / Empty Log

### Logging with Context

Support for contextual logging is available with the `ILogWithContext` interface and `PushProperty` extension method which lets you attach additional data to log messages, e.g:

```csharp
using (log.PushProperty("Hello", "World"))
{
    log.InfoFormat("Message");
}
```

Support for the additional context was added to `Log4net`, `NLog` and `Serilog` logging providers.

#### Serilog notes

Serilog `PushProperty` support requires [Serilog.Enrichers.Thread](https://www.nuget.org/packages/Serilog.Enrichers.Thread) NuGet package and its enricher enabled, e.g:

```csharp
var serilog = new LoggerConfiguration()
  .Enrich.FromLogContext()
  // additional config
  .CreateLogger();

LogManager.LogFactory = new SerilogFactory(serilog);
```

# Registration Examples

Once on your App Startup, either In your `AppHost.cs` or `Global.asax` file inject the concrete logging implementation that your app should use, e.g.

## Built-in Loggers

```csharp
//Console.WriteLine
LogManager.LogFactory = new ConsoleLogFactory(debugEnabled:true); 
//Debug.WriteLine
LogManager.LogFactory = new DebugLogFactory(debugEnabled:true);   
//Capture logs in StringBuilder
LogManager.LogFactory = new StringBuilderLogFactory(); 
//No Logging (default)
LogManager.LogFactory = new NullLogFactory();   
```

## NLog

```csharp
LogManager.LogFactory = new NLogFactory(); 
```

## Log4Net

```csharp
//Also runs log4net.Config.XmlConfigurator.Configure()
LogManager.LogFactory = new Log4NetFactory(configureLog4Net:true); 
```

## Event Log

```csharp
LogManager.LogFactory = new EventLogFactory("Logging.Tests", "Application");
```

Then your application logic can bind to and use a lightweight implementation-free ILog which at runtime will be an instance of the concrete implementation configured in your host:

```csharp
ILog log = LogManager.GetLogger(GetType());

log.Debug("Debug Event Log Entry.");
log.Warn("Warning Event Log Entry.");
```

## Elmah

To configure Elmah register it before initializing ServiceStack's AppHost, passing in the Global HttpApplication Instance and an alternate logger you'd like to use to for your Debug and Info messages, e.g:

```csharp
public class Global : System.Web.HttpApplication
{
    protected void Application_Start(object sender, EventArgs e)
    {
        var debugMessagesLog = new ConsoleLogFactory();
        LogManager.LogFactory = new ElmahLogFactory(debugMessagesLog, this);
        new AppHost().Init();
    }
}
```

Elmah also requires its handlers and modules to be registered in the **Web.config** which lets you view your Elmah Error Log at: `/elmah.xsd`:

```xml
<configuration>
  <system.web>
    ...
    <httpHandlers>
      <add verb="POST,GET,HEAD" path="elmah.axd" type="Elmah.ErrorLogPageFactory, Elmah" />
    </httpHandlers>
    <httpModules>
      <add name="ErrorLog" type="Elmah.ErrorLogModule, Elmah"/>
    </httpModules>
  </system.web>

  <system.webServer>
    <handlers>
      ...
      <add name="Elmah" path="elmah.axd" verb="POST,GET,HEAD" 
           type="Elmah.ErrorLogPageFactory, Elmah" preCondition="integratedMode" />
    </handlers>
    <modules>
      <add name="Elmah.ErrorLog" type="Elmah.ErrorLogModule, Elmah" preCondition="managedHandler" />
    </modules>
  </system.webServer>

</configuration>
```

For a working example see the [Logging.Elmah UseCase](https://github.com/ServiceStack/ServiceStack.UseCases/tree/master/Logging.Elmah) which has ServiceStack and Elmah configured together.

## Slack

Configure Slack Logger with the channels you want to log it to, e.g:

```csharp
LogManager.LogFactory = new SlackLogFactory("{GeneratedSlackUrlFromCreatingIncomingWebhook}", 
    debugEnabled:true)
{
    //Alternate default channel than one specified when creating Incoming Webhook.
    DefaultChannel = "other-default-channel",
    //Custom channel for Fatal logs. Warn, Info etc will fallback to DefaultChannel or 
    //channel specified when Incoming Webhook was created.
    FatalChannel = "more-grog-logs",
    //Custom bot username other than default
    BotUsername = "Guybrush Threepwood",
    //Custom channel prefix can be provided to help filter logs from different users or environments. 
    ChannelPrefix = System.Security.Principal.WindowsIdentity.GetCurrent().Name
};

LogManager.LogFactory = new SlackLogFactory(appSettings);
```

More usage examples are available in [SlackLogFactoryTests](https://github.com/ServiceStack/ServiceStack/blob/master/tests/ServiceStack.Logging.Tests/UnitTests/SlackLogFactoryTests.cs).

## Serilog

To Configure Serilog Logging, first download [ServiceStack.Logging.Serilog](https://www.nuget.org/packages/ServiceStack.Logging.Serilog) from NuGet:

:::copy
`<PackageReference Include="ServiceStack.Logging.Serilog" Version="8.*" />`
:::

Then configure ServiceStack to use `SerilogFactory`:

```csharp
LogManager.LogFactory =  new SerilogFactory();
```

The Serilog adapter includes enhanced Serilog-specific APIs:

```csharp
ILog.Debug(Exception ex, string messageTemplate, params object[] propertyValues)
ILog.Info(Exception ex, string messageTemplate, params object[] propertyValues)
ILog.Warn(Exception ex, string messageTemplate, params object[] propertyValues)
ILog.Error(Exception ex, string messageTemplate, params object[] propertyValues)
ILog.Fatal(Exception ex, string messageTemplate, params object[] propertyValues)
ILog.ForContext(Type type)
ILog.ForContext<T>()
ILog.ForContext(ILogEventEnricher enricher)
ILog.ForContext(IEnumerable<ILogEventEnricher> enrichers)
ILog.ForContext(string propertyName, object value, bool destructureObjects = false)
```

## Usage Example

Using a logger in your Service is similar to other .NET Logging providers, e.g. you can initialize a static property for the class and use it in your services, e.g:

```csharp
public class MyService : Service
{
    public static ILog Log = LogManager.GetLogger(typeof(MyService));

    public object Any(Request request)
    {
        if (Log.IsDebugEnabled)
            Log.Debug("In Request Service");
    }
}
```

## Community Logging Providers

### [ServiceStack.Seq.RequestLogsFeature](https://github.com/wwwlicious/servicestack-seq-requestlogsfeature)

Servicestack plugin that logs requests to [Seq](https://getseq.net/).

# Community Resources

  - [Using Slack for Logging (with ServiceStack)](http://buildclassifieds.com/2016/02/01/using-slack-for-logging-with-servicestack/) by [@markholdt](https://twitter.com/markholdt)
  - [Elmah, Emails, and ServiceStack](http://rossipedia.com/blog/2013/03/elmah-emails-and-servicestack/) by [@rossipedia](https://twitter.com/rossipedia)


# Request &amp; Response filters
Source: https://docs.servicestack.net/request-and-response-filters

ServiceStack's Global Request and Response filter lets you apply your own generic custom behavior to ServiceStack Requests.
These should be registered in your `AppHost.Configure()` Startup: 

## Global Request Filters

The Request Filters are applied before the service gets called and accepts:
([IRequest](https://github.com/ServiceStack/ServiceStack/blob/master/src/ServiceStack.Interfaces/Web/IRequest.cs), [IResponse](https://github.com/ServiceStack/ServiceStack/blob/master/src/ServiceStack.Interfaces/Web/IResponse.cs), RequestDto) e.g:
    
```csharp
//Global Request Filter to check if the user has a session initialized
this.GlobalRequestFilters.Add((req, res, requestDto) => 
{
    var sessionId = req.GetCookieValue("user-session");
    if (sessionId == null)
    {
        res.ReturnAuthRequired();
    }
});
```

### Async 

Use `GlobalRequestFiltersAsync` when you need to make async requests in your Global Request Filters, e.g:

Simplified example of ServiceStack's [Validation Feature](/validation):

```csharp
//Global Async Request Filter to automatically validate a Request DTO
this.GlobalRequestFiltersAsync.Add(async (req, res, requestDto) => 
{    
    var validator = ValidatorCache.GetValidator(req, requestDto.GetType());
    if (validator == null)
        return;

    var validationResult = await Validate(validator, req, requestDto);
    if (validationResult.IsValid)
        return;

    var errorResponse = DtoUtils.CreateErrorResponse(requestDto, validationResult.ToErrorResult());
    
    await res.WriteToResponse(req, errorResponse);
});
```

::: info Tip
If you're writing your own response to the response stream inside the response filter, add `res.EndRequest();` to signal to ServiceStack not to do anymore processing for this request
:::

Simple Rate-limiting example:

```csharp
GlobalRequestFiltersAsync.Add(async (req,res,dto) => {
    var response = await client.Send(new CheckRateLimit { 
        Service = dto.GetType().Name,
        IpAddress = req.UserHostAddress,
     });
     if (response.RateLimitExceeded) 
     {
         res.StatusCode = 403;
         res.StatusDescription = "RateLimitExceeded";
         res.EndRequest();
     }
})
```

## Global Response Filters

The Response Filters are applied after your service is called and accepts:
([IRequest](https://github.com/ServiceStack/ServiceStack/blob/master/src/ServiceStack.Interfaces/Web/IRequest.cs), [IResponse](https://github.com/ServiceStack/ServiceStack/blob/master/src/ServiceStack.Interfaces/Web/IResponse.cs), ResponseDto) e.g:

```csharp
//Add a response filter to add a 'Content-Disposition' header so browsers treat it as a native .csv file
this.GlobalResponseFilters.Add((req, res, responseDto) => 
{
    if (req.ResponseContentType == ContentType.Csv)
    {
        res.AddHeader(HttpHeaders.ContentDisposition,
        string.Format("attachment;filename={0}.csv", req.OperationName));
    }
});
```

## Global Request and Response Filters

  - `PreRequestFilters` - Global Filter executed at the start of all ServiceStack Requests
  - `GlobalRequestFilters` - Global Request Filter for ServiceStack Service Requests
  - `GlobalResponseFilters` - Global Response Filter for ServiceStack Service Requests
  - `GatewayRequestFilters` - Request Filter for [Service Gateway](/service-gateway) Requests
  - `GatewayResponseFilters` - Response Filter for [Service Gateway](/service-gateway) Requests
  - `GlobalMessageRequestFilters` - Request Filter for [Service MQ](/messaging) Requests
  - `GlobalMessageResponseFilters` - Response Filter for [Service MQ](/messaging) Requests

Async versions are also available:

  - `GlobalRequestFiltersAsync` - Global Request Filter for ServiceStack Service Requests
  - `GlobalResponseFiltersAsync` - Global Response Filter for ServiceStack Service Requests
  - `GatewayRequestFiltersAsync` - Request Filter for [Service Gateway](/service-gateway) Requests
  - `GatewayResponseFiltersAsync` - Response Filter for [Service Gateway](/service-gateway) Requests
  - `GlobalMessageRequestFiltersAsync` - Request Filter for [Service MQ](/messaging) Requests
  - `GlobalMessageResponseFiltersAsync` - Response Filter for [Service MQ](/messaging) Requests

### Typed Request Filters

A more typed API to register Global Request and Response filters per Request DTO Type are available under the `RegisterTyped*` API's in AppHost where you can register both typed Request and Response Filters for HTTP and MQ Services independently:

```csharp
void RegisterTypedRequestFilter<T>(Action<IRequest, IResponse, T> filterFn);
void RegisterTypedResponseFilter<T>(Action<IRequest, IResponse, T> filterFn);
void RegisterTypedMessageRequestFilter<T>(Action<IRequest, IResponse, T> filterFn);
void RegisterTypedMessageResponseFilter<T>(Action<IRequest, IResponse, T> filterFn);
```

Here's an example usage that enables more flexibility in multi-tenant solutions by attaching custom data on incoming requests, e.g:

```csharp
public override void Configure(Container container)
{
    RegisterTypedRequestFilter<Resource>((req, res, dto) =>
    {
        var route = req.GetRoute();
        if (route != null && route.Path == "/tenant/{TenantName}/resource")
        {
            dto.SubResourceName = "CustomResource";
        }
    });
}
```

### Autowired Typed Request Filters
 
You can also register Autowired Typed Request and Response Filters which lets you handle Request DTOs in a Typed Filter similar to how Autowired Services handles Typed Request DTOs with access to IOC injected dependencies.
 
Autowired Typed Filters just needs to implement `ITypedFilter<TRequest>` and can be registered in the IOC like a regular dependency, e.g:
 
```csharp
container.RegisterAutoWiredAs<Dependency, IDependency>();
container.RegisterAutoWired<TypedRequestFilter>();
```
 
Then can be registered using the new `RegisterTypedRequestFilter` overload:
 
```csharp
this.RegisterTypedRequestFilter(c => c.Resolve<TypedRequestFilter>());
```
 
Which invokes the Typed Request Filter on each `MyRequest` where it's able to access any IOC injected dependencies, e.g:
 
```csharp
class TypedRequestFilter : ITypedFilter<MyRequest>
{
    public IDependency Dependency { get; set; } // injected by IOC
 
    public void Invoke(IRequest req, IResponse res, MyRequest dto) 
    {
        // Handle MyRequest using a Request Filter
        if (!Dependency.GrantAccess(dto, req))
        {
            res.StatusCode = (int)HttpStatusCode.Forbidden;
            res.StatusDescription = "Thou shall not pass";
            res.EndRequest();
        }
    }
}
```

### Apply custom behavior to multiple DTO's with Interfaces

Typed Filters can also be used to apply custom behavior on Request DTO's sharing a common interface, e.g:

```csharp
public override void Configure(Container container)
{
    RegisterTypedRequestFilter<IHasSharedProperty>((req, res, dtoInterface) => {
        dtoInterface.SharedProperty = "Is Shared";    
    });
}
```

## Message Queue Endpoints

Non-HTTP requests like [Redis MQ](/redis-mq) are treated as _Internal Requests_ which only execute the alternate `GlobalMessageRequestFilters` and `GlobalMessageResponseFilters` and Action [Filter attributes](/filter-attributes).


# Filter Attributes
Source: https://docs.servicestack.net/filter-attributes

ServiceStack also contains interfaces for attributes which can be executed before and after a request like request/response filters. The filter attributes are great for composing re-usable functionality as you can wrap common functionality in a Filter Attribute and selectively annotate which Services they should apply to. 

For example, ServiceStack uses `[Authenticate]` and `[RequiredPermission]` filter attributes to decorate which Services should be protected with authentication or specific permissions (see [Authentication and authorization](/auth/authentication-and-authorization)).

### Request Filter Attributes

Request Filters are executed before Services are called. You can create a Filter Attribute by inheriting from the built-in RequestFilterAttribute's:

```csharp
//Async:
public class CustomAsyncRequestFilterAttribute : RequestFilterAsyncAttribute 
{
    public override async Task ExecuteAsync(IRequest req, IResponse res, object requestDto) 
    {
        string userAgent = req.UserAgent;
        StatisticManager.SaveUserAgent(userAgent);
    }
}

//Sync:
public class CustomRequestFilterAttribute : RequestFilterAttribute 
{
    public override void Execute(IRequest req, IResponse res, object requestDto) { ... }
}
```

Or if you prefer you can instead implement one of the Request or Response Filter interfaces below:

```csharp
public interface IRequestFilterBase
{
    int Priority { get; }      // Prioity of <0 are run before Global Request Filters. >=0 Run after
    IRequestFilterBase Copy(); // A new shallow copy of this filter is used on every request.
}

public interface IHasRequestFilter : IRequestFilterBase
{
    void RequestFilter(IRequest req, IResponse res, object requestDto);
}

public interface IHasRequestFilterAsync : IRequestFilterBase
{
    Task RequestFilterAsync(IRequest req, IResponse res, object requestDto);
}
```

### Response Filter Attributes

Response Filters are called after Services are executed. 

```csharp
//Async:
public class CustomAsyncResponseFilterAttribute : ResponseFilterAsyncAttribute
{
    public override async Task ExecuteAsync(IRequest req, IResponse res, object responseDto) 
    {
        //This code is executed after the service
        res.AddHeader("Cache-Control", "max-age=3600");
    }
}

//Sync:
public class CustomResponseFilterAttribute : ResponseFilterAttribute
{
    public override void Execute(IRequest req, IResponse res, object responseDto) { ... }
}
```

Alternatively you can implement the `IHasResponseFilter` or `IHasResponseFilterAsync` interfaces instead.

### Action Filter Attributes

All Sync and Async Filter Attributes follow the same [Order of Operations](/order-of-operations) with Async Attributes  executed immediately after any registered sync filters with the same priority.

Filter attributes annotated on methods are always executed immediately before or after the Service, i.e. the Priority is only scoped and sorted between other method-level attributes.

```csharp
public class MyServices : Service
{
    [CustomRequestFilter]
    public object Any(Request request) => ...;
}
```

## Filter Attributes Example

The method signatures for Filter Attributes are the same as Global Request/Response Filters with the `IRequest`, `IResponse` and Request or Response DTO. Filter attributes can change the DTO, the http response (e.g status code) or look for a specific header in the http request. You can also attach any data to this request via the `IHttpRequest.Items` dictionary which all subsequent filters and services can access.

## Example Usage

These two attributes have to be added to a request/response DTO or to the service implementation to enable them.

```csharp

//Request DTO
[Route("/aspect")]
[CustomRequestFilter]
public class User
{
    public string Name { get; set; }
    public string Company { get; set; }
    public int Age { get; set; }
    public int Count { get; set; }
}

//Response DTO
[CustomResponseFilter]
public class UserResponse : IHasResponseStatus
{
    public string Car { get; set; }
    public ResponseStatus ResponseStatus { get; set; }
}
```

...or if you don't want the code-first DTOs messed with attributes:

```csharp
[CustomRequestFilter]
[CustomResponseFilter]
public class AspectService : Service
{
    public object Get(Aspect request)
    {
        ...
    }
}
```

That's all, now ServiceStack recognizes the attributes and executes them on every call!

### Dependencies are auto-wired

Just like in Services and Validators, the filter attributes are also auto-wired, e.g:

```csharp
public class CustomRequestFilterAttribute : RequestFilterAttribute
{
    //This property will be resolved by the IoC container
    public ICacheClient Cache { get; set; }
    
    public void RequestFilter(IRequest req, IResponse res, object requestDto)
    {
        //Access the property 'Cache' here
        
        //This code is executed before the service
        string userAgent = req.UserAgent;
        StatisticManager.SaveUserAgent(userAgent);
    }
}
```

In this case the property `Cache` will be tried to be resolved by the IoC container.

### RequestFilterAttribute base class

ServiceStack also has two base classes, which implement the above interfaces, which make it easier to create contextual filters. Contextual filters are only executed on specific HTTP verbs (GET, POST...).

```csharp
public class StatisticFilterAttribute : RequestFilterAttribute
{
    //This property will be resolved by the IoC container
    public ICacheClient Cache { get; set; }
    
    public StatisticFilterAttribute() {}

    public StatisticFilterAttribute(ApplyTo applyTo)
        : base(applyTo) {}

    public override void Execute(IRequest req, IResponse res, object requestDto)
    {
        //This code is executed before the service
        string userAgent = req.UserAgent;
        StatisticManager.SaveUserAgent(userAgent);
    }
}
```

::: info
The `ResponseFilterAttribute` base class can be used for Response Filter Attributes which works the same as `RequestFilterAttribute` above
:::

### Conditionally Apply Filter Attributes

The base class `RequestFilterAttribute` has an empty constructor and a constructor which takes the `ApplyTo` flag. If the empty constructor is called, the method `Execute` will be called on every HTTP verb (`ApplyTo.All`), with the other constructor it will be called only on the configured HTTP verbs (eg `ApplyTo.Get | ApplyTo.Post`).

So you can use the attribute on your Request DTO/service like that:

```csharp
//Filter will be executed on every request
[StatisticFilter]

//Filter will be executed only on GET and POST requests
[StatisticFilter(ApplyTo.Get | ApplyTo.Post)]
```


# Access HTTP-specific Features in Services
Source: https://docs.servicestack.net/access-http-specific-features-in-services

ServiceStack is based on [http handlers](http://msdn.microsoft.com/en-us/library/system.web.ihttphandler.aspx), but ServiceStack provides a clean, dependency-free [IService](https://github.com/ServiceStack/ServiceStack/blob/master/src/ServiceStack.Interfaces/IService.cs) to implement your Web Services logic in. The philosophy behind this approach is that the less dependencies you have on your environment and its request context, the more testable and re-usable your services become. 

::: info
The core [IRequest](https://github.com/ServiceStack/ServiceStack/blob/master/src/ServiceStack.Interfaces/Web/IRequest.cs) and [IResponse](https://github.com/ServiceStack/ServiceStack/blob/master/src/ServiceStack.Interfaces/Web/IResponse.cs) interfaces used in filters and Services
:::

### Request Filters

The Request Filters are applied before the service gets called and accepts: (IRequest, IResponse, RequestDto) e.g:

```csharp
//Add a request filter to check if the user has a session initialized
this.RequestFilters.Add((httpReq, httpResponse, requestDto) =>
{
    httpReq.Headers["HttpHeader"];
    httpReq.QueryString["queryParam"];
    httpReq.Form["htmlFormParam"];
    httpReq.GetParam("aParamInAnyOfTheAbove");

    httpReq.Cookies["requestCookie"];
    httpReq.AbsoluteUri;
    httpReq.Items["requestData"] = "Share data between Filters and Services";

     //Access underlying Request in ASP.NET hosts
    var aspNetRequest = httpResponse.OriginalRequest as HttpRequestBase;
     //Access underlying Request in HttpListener hosts
    var listenerRequest = httpResponse.OriginalRequest as HttpListenerRequest;
});
```

#### Services

When inheriting from Service you can access them via `base.Request` and `base.Response`:

```csharp
public class MyService : Service
{
    public object Any(Request request)
    {
        var value = base.Request.GetParam("aParamInAnyHeadersFormOrQueryString");
        base.Response.AddHeader("X-CustomHeader", "Modify HTTP Response in Service");
    }
}
```

#### Response Filters

The Response Filters are applied after your service is called and accepts: (IRequest, IResponse, ResponseDto) e.g Add a response filter to add a 'Content-Disposition' header so browsers treat it as a native .csv file:

```csharp
this.ResponseFilters.Add((req, res, responseDto) => 
{
    if (req.ResponseContentType == ContentType.Csv)
    {
        res.AddHeader(HttpHeaders.ContentDisposition,
            $"attachment;filename={req.OperationName}.csv");
    }

    //Access underlying Response in ASP.NET hosts
    var aspNetResponse = httpResponse.OriginalResponse as HttpResponseBase;
    //Access underlying Response in HttpListener hosts
    var listenerResponse = httpResponse.OriginalResponse as HttpListenerResponse;
});
```

### Communicating throughout the Request Pipeline

The recommended way to pass additional metadata about the request is to use the `IRequest.Items` collection. E.g. you can change what Razor View template the response DTO gets rendered in with: 

```csharp
httpReq.Items["Template"] = "_CustomLayout";

...

var preferredLayout = httpReq.Items["Template"];
```

## Advantages for having dependency-free services

If you don't need to access the HTTP specific features your services can be called by any non-HTTP endpoint,  like from a [message queue](/messaging).

### Injecting the IRequest into your Service

Although working in a clean-room can be ideal from re-usability and testability point of view, you stand the chance of missing out a lot of the features present in HTTP.

Just like using built-in Funq IOC container, the way to tell ServiceStack to inject the request context is by implementing the [IRequiresRequest](https://github.com/ServiceStack/ServiceStack/blob/master/src/ServiceStack.Interfaces/Web/IRequiresRequest.cs) interface which will get the [IRequest](https://github.com/ServiceStack/ServiceStack/blob/master/src/ServiceStack.Interfaces/Web/IRequest.cs) injected before each request.

::: info
ServiceStack's Convenient `Service` base class already implements `IRequiresRequest` which allows you to access the `IRequest` with `base.Request` and the HTTP Response with `base.Response`
:::

::: info
To return a customized HTTP Response, e.g. set Response Cookies or Headers, return the [HttpResult](https://github.com/ServiceStack/ServiceStack/blob/master/src/ServiceStack/HttpResult.cs) object
:::


# Serialization and Deserialization
Source: https://docs.servicestack.net/serialization-deserialization

### Passing complex objects in the Query String

ServiceStack uses the [JSV-Format](/jsv-format) (JSON without quotes) to parse QueryStrings.

JSV lets you embed deep object graphs in QueryString as seen [this example url](https://test.servicestack.net/json/reply/StoreLogs?Loggers=%5B%7BId:786,Devices:%5B%7BId:5955,Type:Panel,TimeStamp:1199303309,Channels:%5B%7BName:Temperature,Value:58%7D,%7BName:Status,Value:On%7D%5D%7D,%7BId:5956,Type:Tank,TimeStamp:1199303309,Channels:%5B%7BName:Volume,Value:10035%7D,%7BName:Status,Value:Full%7D%5D%7D%5D%7D%5D):

```
https://test.servicestack.net/json/reply/StoreLogs?Loggers=[{Id:786,Devices:[{Id:5955,Type:Panel,
Channels:[{Name:Temperature,Value:58},{Name:Status,Value:On}]},
{Id:5956,Type:Tank,TimeStamp:1199303309,
Channels:[{Name:Volume,Value:10035},{Name:Status,Value:Full}]}]}]
```

If you want to change the default binding ServiceStack uses, you can register your own **Custom Request Binder**.

## Custom Media Types

ServiceStack serializes and deserializes your DTOs automatically. If you want to override the default serializers or you want to add a new format, you have to register your own `Content-Type`:

### Register a custom format

```csharp
string contentType = "application/yourformat"; //To override JSON eg, write "application/json"
var serialize = (IRequest req, object response, Stream stream) => ...;
var deserialize = (Type type, Stream stream) => ...;

//In AppHost Configure method
//Pass two delegates for serialization and deserialization
this.ContentTypes.Register(contentType, serialize, deserialize);	
```

### Encapsulate inside a plugin

If you're looking to standardize on a custom implementation, it's recommended to wrap the registration inside a plugin.

E.g. here's how you can change ServiceStack to use .NET's `XmlSerializer` instead of its `DataContractSerializer` default:

```csharp
public class XmlSerializerFormat : IPlugin
{
    public static void Serialize(IRequest req, object response, Stream stream)
    {
        var serializer = new XmlSerializer(response.GetType());
        serializer.Serialize(stream, response);
    }

    public static object Deserialize(Type type, Stream stream)
    {
        var serializer = new XmlSerializer(type.GetType());
        var obj = (Type) serializer.Deserialize(stream);
        return obj;
    }

    public void Register(IAppHost appHost)
    {
        appHost.ContentTypes.Register(MimeTypes.Xml, Serialize, Deserialize);
    }
}
```

Where it can then be easily registered as a regular [plugin](/plugins):

```csharp
Plugins.Add(new XmlSerializerFormat());
```

### Other ContentType Examples

The [Protobuf-format](/protobuf-format) shows an example of registering a new format whilst the [Northwind VCard Format](https://northwind.netcore.io/vcard-format.htm) shows an example of creating a custom media type in ServiceStack.

For reference see registration examples of ServiceStack's different Formats:

 - [CSV](https://github.com/ServiceStack/ServiceStack/blob/master/src/ServiceStack/Formats/CsvFormat.cs)
 - [MsgPack](https://github.com/ServiceStack/ServiceStack/blob/6e584877125fa0750db10700a6f1a271a7ef918a/src/ServiceStack.MsgPack/MsgPackFormat.cs#L67)
 - [Protobuf](https://github.com/ServiceStack/ServiceStack/blob/6e584877125fa0750db10700a6f1a271a7ef918a/src/ServiceStack.ProtoBuf/ProtoBufFormat.cs#L12)
 - [Wire](https://github.com/ServiceStack/ServiceStack/blob/6e584877125fa0750db10700a6f1a271a7ef918a/src/ServiceStack.Wire/WireServiceClient.cs#L64)
 - [SOAP](https://github.com/ServiceStack/ServiceStack/blob/6e584877125fa0750db10700a6f1a271a7ef918a/src/ServiceStack/Formats/SoapFormat.cs#L29)

#### Async ContentTypes Formats

The async registration APIs are for Content-Type Formats which perform Async I/O, most serialization formats don't except for HTML View Engines which can perform Async I/O when rendering views, which are all registered using the `RegisterAsync` APIs:

```csharp
appHost.ContentTypes.RegisterAsync(MimeTypes.Html, SerializeToStreamAsync, null);
appHost.ContentTypes.RegisterAsync(MimeTypes.JsonReport, SerializeToStreamAsync, null);
appHost.ContentTypes.RegisterAsync(MimeTypes.MarkdownText, SerializeToStreamAsync, null);
```

## Reading in and De-Serializing ad-hoc custom requests

There are 2 ways to deserialize your own custom format, via attaching a custom request binder for a particular service or marking your service with `IRequiresRequestStream` which will skip auto-deserialization and inject the ASP.NET Request stream instead.

### Create a custom request dto binder

You can register custom binders in your AppHost by using the example below:

```cs
appHost.RegisterRequestBinder<MyRequest>(httpReq => ... requestDto);      // or:
appHost.RequestBinders.Add(typeof(MyRequest), httpReq => ... requestDto);
```

This gives you access to the IHttpRequest object letting you parse it manually so you can construct and return the strong-typed Request DTO manually which will be passed to the service instead.

### Uploading Files

You can access uploaded files independently of the Request DTO using `Request.Files`. e.g:

```csharp
public object Post(MyFileUpload request)
{
    if (this.Request.Files.Length > 0)
    {
        var uploadedFile = base.Request.Files[0];
        uploadedFile.SaveTo(MyUploadsDirPath.CombineWith(file.FileName));
    }
    return HttpResult.Redirect("/");
}
```

ServiceStack's [imgur.netcore.io](https://imgur.netcore.io) example shows how to access the [byte stream of multiple uploaded files](https://github.com/ServiceStackApps/Imgur/blob/master/src/Imgur/Global.asax.cs#L62), e.g:

```csharp
public object Post(Upload request)
{
    foreach (var uploadedFile in base.Request.Files
       .Where(uploadedFile => uploadedFile.ContentLength > 0))
    {
        using (var ms = new MemoryStream())
        {
            uploadedFile.WriteTo(ms);
            WriteImage(ms);
        }
    }
    return HttpResult.Redirect("/");
}
```

### Reading directly from the Request Stream

Instead of registering a custom binder you can skip the serialization of the Request DTO, you can add the [IRequiresRequestStream](https://github.com/ServiceStack/ServiceStack/blob/master/src/ServiceStack.Interfaces/Web/IRequiresRequestStream.cs) interface to directly retrieve the stream without populating the Request DTO.

```csharp
//Request DTO
public class RawBytes : IRequiresRequestStream
{
    /// <summary>
    /// The raw Http Request Input Stream
    /// </summary>
    Stream RequestStream { get; set; }
}
```

Which tells ServiceStack to skip trying to deserialize the request so you can read in the raw HTTP Request body yourself, e.g:

```csharp
public async Task<object> PostAsync(RawBytes request)
{
    byte[] bytes = await request.RequestStream.ReadFullyAsync();
    string text = bytes.FromUtf8Bytes(); //if text was sent
}
```

### Buffering the Request and Response Streams

ServiceStack's Request and Response stream are non-buffered (i.e. forward-only) by default. This can be changed at runtime using a `PreRequestFilters` to allow the Request Body and Response Output stream to be re-read multiple times should your Services need it:

```csharp
appHost.PreRequestFilters.Add((httpReq, httpRes) => {
    httpReq.UseBufferedStream = true;  // Buffer Request Input
    httpRes.UseBufferedStream = true;  // Buffer Response Output
});
```

Which you'll then be able to re-read the Request Input Stream with:

```csharp
string textBody = await httpReq.GetRawBodyAsync(); //read as string

ReadOnlySpan<byte> bytes = ((MemoryStream)httpReq.InputStream).GetBufferAsSpan(); //read as bytes
```

### Raw SOAP Message

You can access raw WCF Message when accessed with the SOAP endpoints in your Service with `IHttpRequest.GetSoapMessage()` extension method, e.g:

```csharp
Message requestMsg = base.Request.GetSoapMessage();
```

To tell ServiceStack to skip Deserializing the SOAP request entirely, add the `IRequiresSoapMessage` interface to your Request DTO, e.g:

```csharp
public class RawWcfMessage : IRequiresSoapMessage {
    public Message Message { get; set; }
}

public object Post(RawWcfMessage request) { 
    request.Message... //Raw WCF SOAP Message
}
```


# Auto Mapping
Source: https://docs.servicestack.net/auto-mapping

## Using ServiceStack's Built-in Auto-mapping

Although [we encourage keeping separate DTO models](http://stackoverflow.com/a/15369736/85785), you don't need to maintain your own manual mapping as you can use ServiceStack's built-in Auto Mapping support. It's quite comprehensive and resilient and does a good job in being able to co-erce one type into another, e.g. you can convert between different Enum types with the same name, between Enums and any value type and Strings, between properties and fields, POCOs and strings and many things in between - some of which can be seen in these [Auto Mapping tests](https://github.com/ServiceStack/ServiceStack/blob/main/ServiceStack.Text/tests/ServiceStack.Text.Tests/AutoMappingTests.cs).

Here are some typical common use-cases you're likely to hit in your web service development travels:

Create a new DTO instance, populated with matching properties on viewModel:

```csharp
var dto = viewModel.ConvertTo<MyDto>();

var dto = new { Anon = "Object" }.ConvertTo<MyDto>();
```

Initialize DTO and populate it with matching properties on a view model:

```csharp
var dto = new MyDto { A = 1, B = 2 }.PopulateWith(viewModel);
```

Initialize DTO and populate it with **non-default** matching properties on a view model:

```csharp
var dto = new MyDto { A = 1, B = 2 }.PopulateWithNonDefaultValues(viewModel);
```

Initialize DTO and populate it with matching properties that are annotated with the **Attr** Attribute on a view model:

```csharp
var dto = new MyDto { A=1 }
    .PopulateFromPropertiesWithAttribute(viewModel, typeof(CopyAttribute));
```

There is also the inverse for mapping all properties that don't include a specific attribute:

```csharp
var safeUpdate = db.SingleById<MyTable>(id)
    .PopulateFromPropertiesWithoutAttribute(dto, typeof(ReadOnlyAttribute));
```

### Advanced mapping using Converters

You can register a custom Converter mapping using the `AutoMapping.RegisterConverter()` APIs, e.g:

```csharp
// Data.User -> DTO User
AutoMapping.RegisterConverter((Data.User from) => {
    var to = from.ConvertTo<User>(skipConverters:true); // avoid infinite recursion
    to.FirstName = from.GivenName;
    to.LastName = from.Surname;
    return to;
});

// Car -> String
AutoMapping.RegisterConverter((Car from) => $"{from.Model} ({from.Year})");

// WrappedDate -> DateTime
AutoMapping.RegisterConverter((WrappedDate from) => from.ToDateTime());
// DateTime    -> WrappedDate
AutoMapping.RegisterConverter((DateTime from) => new WrappedDate(from));
```

Where it will be called whenever a conversion between `Data.User -> User` or `Car -> String` is needed, inc. nested types and collections.

Converters can also be used when you want to "take over" and override the default conversion behavior.

### Intercept AutoMapping Conversions

The `RegisterPopulator` AutoMapping API can be used to run custom logic after an Auto Mapping Conversion, e.g. after a
`T.ConvertTo<T>()` or `T.PopulateWith(obj)` is performed. 

This is useful when you need to intercept Auto Mapping conversions in external libraries, e.g. you can use this to populate
the UserSession's `UserAuthId` with a different field from your Custom UserAuth:

```csharp
AutoMapping.RegisterPopulator((IAuthSession session, IUserAuth userAuth) => 
{
    if (userAuth is RavenUserAuth ravenUserAuth)
    {
        session.UserAuthId = ravenUserAuth.Key;
    }
});
```

### Advanced mapping using custom extension methods

When mapping logic becomes more complicated we like to use extension methods to keep code DRY and maintain the mapping in one place 
that's easily consumable from within your application, e.g:

```csharp
public static class ConvertExtensions
{
    public static MyDto ToDto(this MyViewModel from)
    {
        var to = from.ConvertTo<MyDto>();
        to.Items = from.Items.ConvertAll(x => x.ToDto());
        to.CalculatedProperty = Calculate(from.Seed);
        return to;
    }
}
```

Which is now easily consumable with just:

```csharp
var dto = viewModel.ToDto();
```

Using C# methods ensures conversion is explicit, discoverable, debuggable, fast and flexible with access to the full C# language at your disposal
whose conversion logic can be further DRY'ed behind reusable extension methods.

If you find you need to call this extension method manually in many places you may want to consider registering a Custom Converter instead.

### Ignore Mapping

Use the `AutoMapping.IgnoreMapping()` API to specify mappings you want to skip entirely, e.g:

```csharp
// Ignore Data.User -> User
AutoMapping.IgnoreMapping<Data.User, User>();
// Ignore List<Data.User> -> List<User>
AutoMapping.IgnoreMapping<List<Data.User>, List<User>>();
```

### Support for Implicit / Explicit Type Casts

The built-in Auto Mapping also supports using any `implicit` or `explicit` Value Type Casts when they exists, e.g:

```csharp
struct A
{
    public int Id { get; }
    public A(int id) => Id = id;
    public static implicit operator B(A from) => new B(from.Id);
}

struct B
{
    public int Id { get; }
    public B(int id) => Id = id;
    public static implicit operator A(B from) => new A(from.Id);
}

var b = new A(1).ConvertTo<B>();
```

### Powerful and Capable

Due to its heavy reliance in [#Script](https://sharpscript.net) and other parts in ServiceStack, the built-in Auto Mapping is a 
sophisticated implementation that covers a large number of use-cases and corner cases when they can be intuitively mapped.

To see a glimpse of its available capabilities check out some of the examples in the docs where it's able to 
[call any method or construct any type dynamically](/reflection-utils#call-any-method-dynamically) using different Types.

Or how it's able to [convert any Reference Type into and out of an Object Dictionary](/reflection-utils#converting-instances-from-an-object-dictionary), 
providing a simple approach to dynamically manipulating Types.

### Populating Types from an Object Dictionary

The `ToObjectDictionary` and `FromObjectDictionary` extension methods are also useful in trying to convert loosely-typed data structures into a Typed POCO's, e.g:

```csharp
var dto = new User
{
    FirstName = "First",
    LastName = "Last",
    Car = new Car { Age = 10, Name = "ZCar" },
};

Dictionary<string,object> map = dtoUser.ToObjectDictionary();

map["LastName"] = "Updated";

User user = (User)map.FromObjectDictionary(typeof(User));
```


  [1]: http://martinfowler.com/eaaCatalog/dataTransferObject.html
  [2]: http://msdn.microsoft.com/en-us/library/ff649585.aspx
  [3]: http://www.palmmedia.de/Blog/2011/8/30/ioc-container-benchmark-performance-comparison
  [4]: /clients-overview
  [5]: http://ayende.com/blog/4769/code-review-guidelines-avoid-inheritance-for-properties
  [6]: https://github.com/AutoMapper/AutoMapper


# Auto Batched Requests
Source: https://docs.servicestack.net/auto-batched-requests

One of the best ways to improve performance, efficiency and reduce latency is to minimize the number of network requests required, which is one of the reasons we've always encouraged [Coarse-grained API designs](/why-servicestack#servicestack-encourages-development-of-message-style-re-usable-and-batch-full-web-services) - which also lend themselves to better encapsulation and re-use. 

A common use-case that can be improved are clients making multiple requests to the same API, but due to the lack of a better alternative batched API or control over the server implementation, will default to making multiple N+1 web service requests. 

## All Services support Batching

Thanks to it's [message-based design](/advantages-of-message-based-web-services), ServiceStack is able to enable high-level generic functionality like Request Batching which is now implicitly available for all Services, without any additional effort - where multiple requests of the same type can be sent together in a single HTTP Request.

This is enabled in all [.NET Service Clients](/csharp-client) via the new `SendAll()` and `SendAllOneWay()` API's, e.g:

```csharp
var client = new JsonApiClient(BaseUrl);
var requests = new[]
{
    new Request { Id = 1, Name = "Foo" },
    new Request { Id = 2, Name = "Bar" },
    new Request { Id = 3, Name = "Baz" },
};

List<Response> responses = client.SendAll(requests);
```

The API works as you would expect where multiple requests can be sent together and the Service Client will return a list of all responses in the same order as the requests were sent. ServiceStack also adds the `X-AutoBatch-Completed` HTTP Response Header containing the **number** of Requests that were executed. E.g. if 
one of the Requests threw an Exception it will contain the number of requests that were processed before the Exception was thrown, which short-circuits processing the remaining Auto Batched requests and returns a populated [structured Error Response](/error-handling) of the Exception.

And on the back-end, your Services are none the wiser, remaining focused on handling a single Request DTO. In the case below the Service does some work then stores the response in Redis before returning it:

```csharp
public class MyServices : Service
{
    public object Any(Request request)
    {
        var response = DoWork(request);
        Redis.Store(response);
        return response;
    }
}
```

## Request Execution Flow

From the Service's point of view nothing changes. Request DTO's still get executed one at a time, through all existing filters just as if they we're sent on their own. They're just delivered together within a single HTTP Request, in this case POST'ed as JSON to the `/json/reply/Request[]` [pre-defined route](/routing#pre-defined-routes):

![Auto Batched Requests](https://raw.githubusercontent.com/ServiceStack/Assets/master/img/release-notes/auto-batched-requests.png)

## Custom Batched Requests Implementations

If a client was previously calling the same API 100 times, the existing overhead of 100 HTTP Requests would be reduced to just **1 HTTP Request** when batched. Although the above Service would still be calling Redis 100 times to store each Response.

If later this API has become really hot and you want to improve it even further, you can later add a custom implementation that accepts a `Request[]` and it will only get called once, with access to all the Request DTO's together. In this case we can use a custom implementation and take advantage of Redis's own batched API's and reduce this further to 1 Redis operation:

```csharp
public class MyServices : Service
{
    public object Any(Request request)
    {
        var response = DoWork(request);
        Redis.Store(response);
        return response;
    }
    
    public object Any(Request[] requests)
    {
        var responses = requests.Map(DoWork);
        Redis.StoreAll(responses);
        return responses;
    }
}
```

So with this custom implementation we've gone from **100 HTTP Requests + 100 Redis Operations** to **1 HTTP Request + 1 Redis Operation**.

Another scenario where you may consider using a **Custom Batched Implementation** is if you wanted to execute all requests within a single RDBMS transaction, which with [OrmLite](https://github.com/ServiceStack/ServiceStack.OrmLite) would look something like:

```csharp
public class MyServices : Service
{
    public object Any(Request request)
    {
        var response = DoWork(request);
        Db.Insert(request);
        return response;
    }

    public object Any(Request[] requests)
    {
        using (var trans = Db.OpenTransaction())
        {
            var responses = requests.Map(x => Any(x));	

            trans.Commit();
            return responses;
        }
    }
}
```

Just like with normal Batched Requests, Custom Batched implementations are still executed one at a time through all request/response filters, taking advantage of any existing logic/validation. 

## Defining a Request DTO to accept a collection of Types

If you instead only wanted multiple Requests to be treated as a single Request through the entire pipeline you can create a new Request DTO that inherits from `List<TRequest>` which then gets treated as a normal Request DTO e, g:

```csharp
public class Requests : List<Request> {}

public class MyServices : Service
{
	...
    public object Any(Requests requests)
    {
        var responses = requests.Map(DoWork);
        Redis.StoreAll(responses);
        return responses;
    }
}
```

More examples of Auto Batched Requests and its behavior can be found in the [ReplyAllTests suite](https://github.com/ServiceStack/ServiceStack/blob/master/tests/ServiceStack.WebHost.Endpoints.Tests/ReplyAllTests.cs).

## Auto Batch Index

The current index of the Auto Batched Request being processed is now being maintained in `IRequest.Items[Keywords.AutoBatchIndex]`.

In Error Responses the index of the request that failed is now being populated in your Response DTO's `ResponseStatus.Meta["AutoBatchIndex"]`.

To also maintain the active `AutoBatchIndex` in [Custom Batched Requests Implementations](#custom-batched-requests-implementations) 
you can use the `IRequest.EachRequest()` extension method, e.g:

```csharp
public object Any(GetCustomAutoBatchIndex[] requests)
{
    var responses = new List<GetAutoBatchIndexResponse>();

    Request.EachRequest<GetCustomAutoBatchIndex>(dto =>
    {
        responses.Add(Any(dto));
    });

    return responses;
}
```


# Virtual File System
Source: https://docs.servicestack.net/virtual-file-system

In order to access physical files in view engines from multiple sources, ServiceStack includes its own pluggable virtual file system API that lets it support multiple filesystem backends. 

The virtual file system (VFS) is what allows ServiceStack to support view engines in a standard ASP.NET websites (e.g. serving directories from the root directory) as well in self-hosting stand-alone HttpListener websites and Windows Services serving from the output `/bin` directory as well as embedded resources inside .dlls, [in memory filesystems](/html-css-and-javascript-minification#minify-static-js-css-and-html-files) populated at runtime, [remote datastores like AWS S3](/aws#s3virtualfiles), or in a [remote Azure Blob Storage](https://github.com/ServiceStack/ServiceStack.Azure) or any combination of either.

## Virtual File Systems Available

ServiceStack has the following Virtual Files Sources available:

 - `FileSystemVirtualFiles` - Hard-disk or Network Files and Directories from a specified root directory
 - `MemoryVirtualFiles` - Virtual Files and Folders that can be programmatically populated In Memory
 - `FileSystemMapping` - Hard-disk or Network files made available under an custom file mapping alias
 - `S3VirtualFiles` - Files stored on Amazon's S3 Managed File Storage in [ServiceStack.Aws](https://github.com/ServiceStack/ServiceStack/tree/main/ServiceStack.Aws/src/ServiceStack.Aws)
 - `AzureBlobVirtualFiles` - Files stored on Azure's Managed Blob Storage in [ServiceStack.Azure](https://github.com/ServiceStack/ServiceStack/tree/main/ServiceStack.Azure/src/ServiceStack.Azure)
 - `GoogleCloudVirtualFiles` - Files stored on GoogleCloud Storage in [ServiceStack.GoogleCloud](https://github.com/ServiceStack/ServiceStack/tree/main/ServiceStack/src/ServiceStack.GoogleCloud)
 - `R2VirtualFiles` - Files stored on CloudFlare's R2 Managed File Storage in [ServiceStack.Aws](https://github.com/ServiceStack/ServiceStack/tree/main/ServiceStack.Aws/src/ServiceStack.Aws)
 - `ResourceVirtualFiles` - Embedded Resource Files in .dlls
 - `GistVirtualFiles` - Files stored in a GitHub Gist
 - `MultiVirtualFiles` - Any combination of any of the above Virtual File Sources under a cascading configuration

## Embedded Resources

To enable ServiceStack to serve embedded resources in your Website's compiled `.dll` Assembly you'll need to register either an `Assembly` or a `Type` in an Assembly that contains embedded resources, e.g:

```csharp
SetConfig(new HostConfig {
   EmbeddedResourceSources = { typeof(TypeInDllWithEmbeddedResources).Assembly },
   EmbeddedResourceBaseTypes = { typeof(TypeInDllWithEmbeddedResources) } 
});
```

By default ServiceStack automatically includes the Assembly where your `AppHost` is defined which since it's typically the same top-level assembly where all your Website assets are maintained, no configuration is required to serve any embedded resources which are accessible from the same path as it's defined in your VS.NET project. E.g. if you have an embedded resource in your project at `/dir/file.js` it would be available from the same path where ServiceStack is mounted, e.g `http://localhost:1337/dir/file.js`.

### FileSystem Mappings

Custom FileSystem mappings can be easily registered under a specific alias by overriding your AppHost's `AddVirtualFileSources` and registering a custom `FileSystemMapping`, e.g:

```csharp
AddVirtualFileSources.Add(new FileSystemMapping("img", "i:\\images"));
AddVirtualFileSources.Add(new FileSystemMapping("docs", "d:\\documents"));
```

This will let you access File System Resources under the custom `/img` and `/doc` routes, e.g:

 - http://host/img/the-image.jpg
 - http://host/docs/word.doc

### Register additional Virtual File Sources in Plugins

As Virtual File Sources are initialized before plugins are registered your plugin will need to implement `IPreInitPlugin` so any VFS sources are registered in its `Configure()` method, e.g:

```csharp
public class Disk1Plugin : IPlugin, IPreInitPlugin
{
    public void BeforePluginsLoaded(IAppHost appHost)
    {
        // Insert higher priority Virtual Files and the start of VirtualFileSources
        var s3Client = new AmazonS3Client(AwsAccessKey, AwsSecretKey, RegionEndpoint.USEast1);
        appHost.InsertVirtualFileSources.Add(new S3VirtualFiles(s3Client, AwsConfig.S3BucketName));

        // Add additional low priority Virtual Files and the end of VirtualFileSources
        var mountPath = appHost.MapProjectPath("~/App_Data/mount/hdd");
        appHost.AddVirtualFileSources.Add(new FileSystemMapping("disk1", mountPath));
        appHost.AddVirtualFileSources.Add(new FileSystemMapping("disk2", "d:\\hdd"));
    }

    public void Register(IAppHost appHost) {}
}
```

If needed you can use the `MapProjectPath()` API to resolve a physical file path from your projects ContentPath folder. 

Then you can register the plugin with your AppHost as normal, e.g:

```csharp
public override void Configure(Container container)
{
    Plugins.Add(new Disk1Plugin());
}
```

Where your AppHost will serve static files from your plugin's registered path mappings, e.g:

```
/disk1/file.html -> /path/to/project/App_Data/mount/hdd/file.html
/disk2/file.html -> d:\hdd\file.html
```

### Empty MemoryVirtualFiles registered in VirtualFileSources

To enable **shadowing** of the `WebRoot` cascading Virtual File Sources, an empty `MemoryVirtualFiles` has been added to 
`InsertVirtualFileSources` by default where it gets inserted at the start of `VirtualFileSources`, i.e:

```csharp
new AppHost {
    InsertVirtualFileSources = { new MemoryVirtualFiles() } 
}
```

If needed, the individual Memory and FileSystem VFS providers in the WebRoot VFS Sources can be accessed with:

```csharp
var memFs = appHost.VirtualFileSources.GetMemoryVirtualFiles();
var diskFs = appHost.VirtualFileSources.GetFileSystemVirtualFiles();
```

Which are also available from the `HostContext` singleton:

 - `HostContext.MemoryVirtualFiles` - **WebRoot** MemoryVirtualFiles
 - `HostContext.FileSystemVirtualFiles` - **WebRoot** FileSystem

The **WebRoot** Directory and **ContentRoot** Directories are also available from:

 - `HostContext.RootDirectory` - **WebRoot** `wwwroot/` 
 - `HostContext.ContentRootDirectory` - **ContentRoot** `/`

### Populate Virtual Files

We can leverage this to provide an elegant solution for minifying static `.html`, `.css` and `.js` resources by simply pre-loading a new 
**Memory Virtual FileSystem** with minified versions of existing files and giving the Memory FS a higher precedence so any matching requests 
serve up the minified version first with:

```csharp
public class MyPlugin : IPlugin, IPostInitPlugin
{
    public void Register(IAppHost appHost) { }

    public void AfterPluginsLoaded(IAppHost appHost)
    {
        var memFs = appHost.VirtualFileSources.GetMemoryVirtualFiles();

        //Get FileSystem Provider
        var fs = appHost.VirtualFileSources.GetFileSystemVirtualFiles();

        //Process all .html files:
        foreach (var file in fs.GetAllMatchingFiles("*.html"))
        {
            var contents = Minifiers.HtmlAdvanced.Compress(file.ReadAllText());
            memFs.WriteFile(file.VirtualPath, contents);
        }

        //Process all .css files:
        foreach (var file in fs.GetAllMatchingFiles("*.css")
            .Where(file => !file.VirtualPath.EndsWith(".min.css")))
        {
            var contents = Minifiers.Css.Compress(file.ReadAllText());
            memFs.WriteFile(file.VirtualPath, contents);
        }

        //Process all .js files
        foreach (var file in fs.GetAllMatchingFiles("*.js")
            .Where(file => !file.VirtualPath.EndsWith(".min.js")))
        {
            try
            {
                var js = file.ReadAllText();
                var contents = Minifiers.JavaScript.Compress(js);
                memFs.WriteFile(file.VirtualPath, contents);
            }
            catch (Exception ex)
            {
                //Report any errors in StartUpErrors collection on ?debug=requestinfo
                base.OnStartupException(new Exception(
                    $"JSMin Error in {file.VirtualPath}: {ex.Message}"));
            }
        }
    }
}
```

### Registering additional Virtual File Sources

The `InsertVirtualFileSources` can be used to **prepend** additional Virtual File Sources at start giving them the highest priority whilst
`AddVirtualFileSources` **appends** at the end giving them the lowest priority, which your AppHost or plugins can use to 
register additional Virtual File Sources:

```csharp
public class MyPlugin : IPlugin, IPostInitPlugin
{
    public void Register(IAppHost appHost) 
    { 
        appHost.InsertVirtualFileSources.Add(new GistVirtualFiles("6de7993333b457445793f51f6f520ea8"));
        appHost.AddVirtualFileSources.Add(new FileSystemMapping("docs", "d:\\documents"));
    }
}
```

### Using a different Virtual Path Provider

You can also globally replace the VFS used by setting it in your AppHost, e.g. If you only want to use an InMemory File System:

```csharp
base.VirtualFileSources = new MemoryVirtualFiles();
```

Fine-grained control on which VFS to use can also be specified on any [Plugins](/plugins) requiring access to the FileSystem like ServiceStack's built-in HTML ViewEngines, here's how you could override the VFS used in ServiceStack's Razors support:

```csharp
Plugins.Add(new RazorFormat { 
    VirtualFileSources = new MemoryVirtualFiles() 
});
```

### Changing Physical File Path

You can change the physical root path from where ServiceStack serves your files from by changing `Config.WebHostPhysicalPath`, e.g. the current directory for self-hosts is where the **.exe** is run from, during development this is typically `\bin\Release`. You can change the self-host to serve files from your project folder with:

```csharp
SetConfig(new HostConfig {
    WebHostPhysicalPath = MapProjectPath("~/")
});
```

::: info
Where `~/` is resolved from your App's configured `ContentRootPath`
:::

## Overriding Embedded Resources with Static Files

The VFS supports multiple file source locations where you can override embedded files by including your own custom files in the same location as the embedded files. We can see how this works by overriding the built-in templates used in metadata pages:


## GistVirtualFiles

The `GistVirtualFiles` is a particular exciting addition to the collection of available [Virtual File System providers](/virtual-file-system#virtual-file-systems-available). 
Gist's are the perfect way to capture and share a publicly versionable snapshot of files that's validated against a 
authenticated user account - adding an important layer of trust and verification over an anonymous archive download.

GitHub also provide public HTTP API's to access Gist's and their metadata, that scales nicely to support small fileset snapshots where all
content is returned in the public API resource request, as well as supporting larger fileset snapshots where the contents of the gist are 
truncated and its contents are instead downloaded from its `raw_url` in an alternative HTTP Request.

`GistVirtualFiles` provides a transparent VFS abstraction over GitHub's Gist APIs so they can be used interchangeably with all other VFS providers.

#### Heirachal and Binary file Support

On its surface Gists appear to only support a flat list of text files, but `GistVirtualFiles` is able to overcome these limitations by transparently
encoding Binary files to **Base 64** behind the scenes and utilizing `\` back-slashes in file names to maintain a heirachal file structure
where it's able to implement the full VFS Provider abstraction.

ServiceStack includes good heuristics for determining which files are binary on its extension and Content Type, if your Binary file isn't 
recognized you can register its extension with a known binary content type or override the `IsBinaryFilter` predicate:

```csharp
MimeTypes.ExtensionMimeTypes[ext] = contentType; // e.g. MimeTypes.Binary
//MimeTypes.IsBinaryFilter = contentType => ...;
```

#### Read/Write and ReadOnly Gists

It supports both public read-only and read/write gists with a GitHub `accessToken` being needed in order to perform any writes:

```csharp
var gistFs = new GistVirtualFiles(gistId, accessToken);
var gistFsReadOnly = new GistVirtualFiles(gistId);
```

#### Gist Refresh

Behaviourally they differ from other VFS providers in that they're used more as a snapshot instead of a actively modified file system and
their updates and are noticeably slower to both read and write then the other VFS providers. 

To maximize performance the files are stored in memory after the first access and its internal cache only updated when a **Write** operation is performed.

If you're instead using a Gist that changes frequently you can specify how long before refreshing the cache:

```csharp
var gistFs = new GistVirtualFiles(...) {
    RefreshAfter = TimeSpan.FromHours(1)
};
```

GitHub truncates large Gists which `GistVirtualFiles` transparently fetches behind-the-scenes on-demand, you can also eagerly 
fetch all truncated content with:

```csharp
await gistFs.LoadAllTruncatedFilesAsync();
```

### Batched WriteFiles APIs

As Gist HTTP API's are relatively slow, we recommend using the `WriteFiles` **Batched APIs**  so multiple files can be updated in a single HTTP Request.

### Updating HTML and Metadata Page Templates

The HTML templates for the metadata pages are maintained as [embedded html template resources](https://github.com/ServiceStack/ServiceStack/tree/master/src/ServiceStack/Templates). 

The VFS lets you replace built-in ServiceStack templates with your own by simply copying the metadata or [HtmlFormat Template files](http://bit.ly/164YbrQ) you want to customize and placing them in your Website Directory at:

```
/Templates/HtmlFormat.html        // The auto HtmlFormat template
/Templates/IndexOperations.html   // The /metadata template
/Templates/OperationControl.html  // Individual operation template
```

Which you can customize locally that ServiceStack will pick up and use instead.

## Writable Virtual File System

The Virtual File System extended `IVirtualFiles` interface extends the read-only `IVirtualPathProvider` interface to offer a read/write API:

```csharp
public interface IVirtualFiles : IVirtualPathProvider
{
  void WriteFile(string filePath, string textContents);
  void WriteFile(string filePath, Stream stream);
  void WriteFiles(IEnumerable<IVirtualFile> files,Func<IVirtualFile,string> toPath=null);
  void AppendFile(string filePath, string textContents);
  void AppendFile(string filePath, Stream stream);
  void DeleteFile(string filePath);
  void DeleteFiles(IEnumerable<string> filePaths);
  void DeleteFolder(string dirPath);

  void WriteFile(string filePath, object contents);
  void AppendFile(string filePath, object contents);
  void WriteFiles(Dictionary<string, string> textFiles); //text files only
  void WriteFiles(Dictionary<string, object> files); //binary or text files
}
```

The single and multi-write File APIs support `object` content values of either `string`, `ReadOnlyMemory<char>`, `byte[]`, 
`ReadOnlyMemory<byte>`, `Stream` and `IVirtualFile` Types.

Additional allocation-efficient `ReadOnlyMemory<T>` APIs are also available as extension methods:

```csharp
void WriteFile(string path, ReadOnlyMemory<char> text);
void WriteFile(string path, ReadOnlyMemory<byte> bytes);
void AppendFile(string path, ReadOnlyMemory<char> text);
void AppendFile(string path, ReadOnlyMemory<byte> bytes);
```

::: info
Folders are implicitly created when writing a file to folders that don't exist
:::

The new `IVirtualFiles` API is available in local FileSystem, In Memory, Gists and S3 Virtual path providers:

 - `FileSystemVirtualFiles`
 - `S3VirtualFiles`
 - `AzureBlobVirtualFiles`
 - `GistVirtualFiles`
 - `MemoryVirtualFiles`

All `IVirtualFiles` providers share the same 
[VirtualPathProviderTests](https://github.com/ServiceStack/ServiceStack/blob/main/ServiceStack.Aws/tests/ServiceStack.Aws.Tests/S3/VirtualPathProviderTests.cs)
ensuring a consistent behavior where it's now possible to swap between different file storage backends with simple
configuration as seen in the [Imgur](https://github.com/ServiceStackApps/AwsApps/tree/master/src/AwsApps/imgur) and 
[REST Files](https://github.com/ServiceStackApps/AwsApps/tree/master/src/AwsApps/restfiles) examples.

#### Object APIs

The `object GetContents()` API allow VFS Providers to implement more efficient file access which by default returns `ReadOnlyMemory<char>`
for text files and `ReadOnlyMemory<byte>` for binary files:

```csharp
public interface IVirtualFile
{
    object GetContents();
}
```

The `object` APIs also let you use the same source code to read/write both text and binary files which VFS providers can implement more efficiently:

```csharp
var content = vfs.GetFile(fromVirtualPath).GetContent();
vfs.WriteFile(toVirtualPath, content);
```

In [#Script](https://sharpscript.net) you can access a files text or binary contents with either:

```js
vfs.fileContents(filePath) | to => fileContents
vfs.writeFile(path, fileContents)

vfs.fileTextContents(filePath) | to => textContents
vfs.writeFile(path, textContents)

vfs.fileBytesContent(filePath) | to => binaryContents
vfs.writeFile(path, binaryContents)
```

### VirtualFiles vs VirtualFileSources

As typically when saving uploaded files you'd only want files written to a single explicit File Storage provider,
ServiceStack keeps a distinction between the existing read-only Virtual File Sources it uses internally whenever a 
static file is requested and the new `IVirtualFiles` which is maintained in a separate `VirtualFiles` property on 
`IAppHost` and `Service` base class for easy accessibility:

```csharp
public class IAppHost
{
    // Read/Write Virtual FileSystem. Defaults to Local FileSystem.
    IVirtualFiles VirtualFiles { get; set; }
    
    // Cascading file sources, inc. Embedded Resources, File System, In Memory, S3.
    IVirtualPathProvider VirtualFileSources { get; set; }
}

public class Service : IService //ServiceStack's convenient concrete base class
{
    //...
    public IVirtualFiles VirtualFiles { get; set; }
    public IVirtualPathProvider VirtualFileSources { get; }
}
```

Internally ServiceStack only uses `VirtualFileSources` itself to serve static file requests. 
The new `IVirtualFiles` is a clean abstraction your Services can bind to when saving uploaded files which can be easily
substituted when you want to change file storage backends. If not specified, `VirtualFiles` defaults to your local 
filesystem at your host project's root directory.

### Examples

 - [AWS RazorRockstars](/aws#maintain-website-content-in-s3) - Serving all Razor Views and Markdown Content from a S3 bucket
 - [AWS Imgur and REST Files](/aws#aws-imgur) - 1 line configuration switch between saving files to local files or S3 Bucket

### [ServiceStack.Gap](https://github.com/ServiceStack/ServiceStack.Gap)

See the ServiceStack.Gap project for different examples of how to create single **.exe** ILMerged applications with Embedded Resources and Compiled Razor Views.

## Implementing a new Virtual File System

The VFS is designed to be implementation agnostic so can be changed to use any file repository, e.g. it could easily be made to support a Redis, RDBMS, embedded Sqlite or other NoSQL back-ends.

Like most of ServiceStack's substitutable API's, the interfaces for the VFS lives in the **ServiceStack.Interfaces.dll** under the [ServiceStack.IO](https://github.com/ServiceStack/ServiceStack/tree/master/src/ServiceStack.Interfaces/IO) namespace.

To reduce the amount of effort to implement a VFS provider you can inherit from the 
[`ServiceStack.VirtualPath.Abstract*`](https://github.com/ServiceStack/ServiceStack/tree/master/src/ServiceStack.Common/VirtualPath) 
that all of ServiceStack's VFS providers inherit from.

Otherwise for a clean-room implementation, you'll need to implement these interfaces in order to create a new VFS Provider:

```csharp
public interface IVirtualPathProvider
{
    IVirtualDirectory RootDirectory { get; }
    string VirtualPathSeparator { get; }
    string RealPathSeparator { get; }

    string CombineVirtualPath(string basePath, string relativePath);

    bool FileExists(string virtualPath);
    bool DirectoryExists(string virtualPath);

    IVirtualFile GetFile(string virtualPath);
    string GetFileHash(string virtualPath);
    string GetFileHash(IVirtualFile virtualFile);

    IVirtualDirectory GetDirectory(string virtualPath);

    IEnumerable<IVirtualFile> GetAllMatchingFiles(string globPattern, int maxDepth = Int32.MaxValue);

    IEnumerable<IVirtualFile> GetAllFiles();
    IEnumerable<IVirtualFile> GetRootFiles();
    IEnumerable<IVirtualDirectory> GetRootDirectories();

    bool IsSharedFile(IVirtualFile virtualFile);
    bool IsViewFile(IVirtualFile virtualFile);
}

public interface IVirtualNode
{
    IVirtualDirectory Directory { get; }
    string Name { get; }
    string VirtualPath { get; }
    string RealPath { get; }
    bool IsDirectory { get; }
    DateTime LastModified { get; }
}

public interface IVirtualFile : IVirtualNode
{
    IVirtualPathProvider VirtualPathProvider { get; }

    string Extension { get; }

    string GetFileHash();

    Stream OpenRead();
    StreamReader OpenText();
    string ReadAllText();

    /// <summary>
    /// Returns ReadOnlyMemory&lt;byte&gt; for binary files or
    /// ReadOnlyMemory&lt;char&gt; for text files   
    /// </summary>
    object GetContents();

    long Length { get; }

    /// <summary>
    /// Refresh file stats for this node if supported
    /// </summary>
    void Refresh();
}

public interface IVirtualDirectory : IVirtualNode, IEnumerable<IVirtualNode>
{
    bool IsRoot { get; }
    IVirtualDirectory ParentDirectory { get; }

    IEnumerable<IVirtualFile> Files { get; }
    IEnumerable<IVirtualDirectory> Directories { get; }

    IVirtualFile GetFile(string virtualPath);
    IVirtualFile GetFile(Stack<string> virtualPath);

    IVirtualDirectory GetDirectory(string virtualPath);
    IVirtualDirectory GetDirectory(Stack<string> virtualPath);

    IEnumerable<IVirtualFile> GetAllMatchingFiles(string globPattern, int maxDepth = Int32.MaxValue);
}
```

### Writable Virtual Files Provider

If you want your VFS provider to support writes where it can used in your `IAppHost.VirtualFiles`, 
your `IVirtualPathProvider` should also implement the interface below:

```csharp
public interface IVirtualFiles : IVirtualPathProvider
{
    void WriteFile(string filePath, string textContents);

    void WriteFile(string filePath, Stream stream);

    /// <summary>
    /// Contents can be either:
    /// string, ReadOnlyMemory&lt;char&gt;, byte[], `ReadOnlyMemory&lt;byte&gt;, Stream or IVirtualFile 
    /// </summary>
    void WriteFile(string filePath, object contents);

    void WriteFiles(IEnumerable<IVirtualFile> files, Func<IVirtualFile, string> toPath = null);

    void WriteFiles(Dictionary<string, string> textFiles);
    void WriteFiles(Dictionary<string, object> files);

    void AppendFile(string filePath, string textContents);

    void AppendFile(string filePath, Stream stream);

    /// <summary>
    /// Contents can be either:
    /// string, ReadOnlyMemory&lt;char&gt;, byte[], `ReadOnlyMemory&lt;byte&gt;, Stream or IVirtualFile 
    /// </summary>
    void AppendFile(string filePath, object contents);

    void DeleteFile(string filePath);

    void DeleteFiles(IEnumerable<string> filePaths);

    void DeleteFolder(string dirPath);
}
```

To ensure behavior conformance your VFS provider, it should also be validated against the existing
[VirtualPathProviderTests](https://github.com/ServiceStack/ServiceStack/blob/master/tests/ServiceStack.WebHost.Endpoints.Tests/VirtualPathProviderTests.cs)
test suite.


# Multitenancy
Source: https://docs.servicestack.net/multitenancy

ServiceStack provides a number of ways of changing the database connection used at runtime based on an incoming Request. 
You can use a [Request Filter](/request-and-response-filters#global-request-filters), use the `[ConnectionInfo]` 
[Request Filter Attribute](/filter-attributes#request-filter-attributes), use the `[NamedConnection]` attribute on 
[Auto Query](/autoquery/) Services, access named connections in Custom Service implementations or override 
`GetDbConnection(IRequest)` in your AppHost.

### Change Database Connection at Runtime

The default implementation of `IAppHost.GetDbConnection(IRequest)` includes an easy way to change the DB Connection that can be done by populating the 
[ConnectionInfo](https://github.com/ServiceStack/ServiceStack/blob/master/src/ServiceStack.Common/ConnectionInfo.cs) 
POCO in any
[Request Filter in the Request Pipeline](/order-of-operations):

```csharp
req.Items[Keywords.DbInfo] = new ConnectionInfo {
    NamedConnection  = ... //Use a registered NamedConnection for this Request
    ConnectionString = ... //Use a different DB connection for this Request
    ProviderName     = ... //Use a different Dialect Provider for this Request
};
```

To illustrate how this works we'll go through a simple example showing how to create an AutoQuery Service 
that lets the user change which DB the Query is run on. We'll control which of the Services we want to allow 
the user to change the DB it's run on by having them implement the interface below:

```csharp
public interface IChangeDb
{
    string NamedConnection { get; set; }
    string ConnectionString { get; set; }
    string ProviderName { get; set; }
}
```

We'll create one such AutoQuery Service, implementing the above interface:

```csharp
[Route("/rockstars")]
public class QueryRockstars : QueryBase<Rockstar>, IChangeDb
{
    public string NamedConnection { get; set; }
    public string ConnectionString { get; set; }
    public string ProviderName { get; set; }
}
``` 

For this example we'll configure our Database to use a default **SQL Server 2012** database, 
register an optional named connection looking at a "Reporting" **PostgreSQL** database and 
register an alternative **Sqlite** RDBMS Dialect that we also want the user to be able to use:

#### ChangeDB AppHost Registration

```csharp
container.Register<IDbConnectionFactory>(c => 
    new OrmLiteConnectionFactory(defaultDbConn, SqlServer2012Dialect.Provider));

var dbFactory = container.Resolve<IDbConnectionFactory>() as OrmLiteConnectionFactory;

//Register NamedConnection
dbFactory.RegisterConnection("Reporting", ReportConnString, PostgreSqlDialect.Provider);

//Register DialectProvider
dbFactory.RegisterDialectProvider("Sqlite", SqliteDialect.Provider);
```

#### ChangeDB Request Filter

To enable this feature we just need to add a Request Filter that populates the `ConnectionInfo` with properties
from the Request DTO:

```csharp
GlobalRequestFilters.Add((req, res, dto) => {
   var changeDb = dto as IChangeDb;
   if (changeDb == null) return;

   req.Items[Keywords.DbInfo] = new ConnectionInfo {
       NamedConnection = changeDb.NamedConnection,
       ConnectionString = changeDb.ConnectionString,
       ProviderName = changeDb.ProviderName,
   };
});
```

Since our `IChangeDb` interface shares the same property names as `ConnectionInfo`, the above code can be 
further condensed using a 
[Typed Request Filter](/request-and-response-filters#typed-request-filters)
and ServiceStack's built-in [AutoMapping](/auto-mapping)
down to just:

```csharp
RegisterTypedRequestFilter<IChangeDb>((req, res, dto) =>
    req.Items[Keywords.DbInfo] = dto.ConvertTo<ConnectionInfo>());
```

#### Change Databases via QueryString

With the above configuration the user can now change which database they want to execute the query on, e.g:

```csharp
var response = client.Get(new QueryRockstars()); //SQL Server

var response = client.Get(new QueryRockstars {   //Reporting PostgreSQL DB
    NamedConnection = "Reporting"
}); 

var response = client.Get(new QueryRockstars {   //Alternative SQL Server Database
    ConnectionString = "Server=alt-host;Database=Rockstars;User Id=test;Password=test;"
}); 

var response = client.Get(new QueryRockstars {   //Alternative SQLite Database
    ConnectionString = "C:\backups\2016-01-01.sqlite",
    ProviderName = "Sqlite"
}); 
```

### ConnectionInfo Attribute

To make it even easier to use we've also wrapped this feature in a simple
[ConnectionInfoAttribute.cs](https://github.com/ServiceStack/ServiceStack/blob/master/src/ServiceStack/ConnectionInfoAttribute.cs)
which allows you to declaratively specify which database a Service should be configured to use, e.g we can
configure the `Db` connection in the Service below to use the PostgreSQL **Reporting** database with:

```csharp
[ConnectionInfo(NamedConnection = "Reporting")]
public class ReportingServices : Service
{
    public object Any(Sales request)
    {
        return new SalesResponse { Results = Db.Select<Sales>() };
    }
}
```

### Auto Query Named Connection

[Auto Query](/autoquery/) can also easily be configured to query any number of [different databases registered in your AppHost](/autoquery/rdbms#named-connection). 

In the example below we configure our main RDBMS to use SQL Server and register a **Named Connection** 
to point to a **Reporting** PostgreSQL RDBMS:

```csharp
var dbFactory = new OrmLiteConnectionFactory(connString, SqlServer2012Dialect.Provider);
container.Register<IDbConnectionFactory>(dbFactory);

dbFactory.RegisterConnection("Reporting", pgConnString, PostgreSqlDialect.Provider);
```

Any normal AutoQuery Services like `QueryOrders` will use the default SQL Server connection whilst 
`QuerySales` will execute its query on the PostgreSQL `Reporting` Database instead:

```csharp
public class QueryOrders : QueryDb<Order> {}

[ConnectionInfo(NamedConnection = "Reporting")]
public class QuerySales : QueryDb<Sales> {}
```

An alternative to specifying the `[ConnectionInfo]` Request Filter Attribute on the AutoQuery Request DTO, is to specify the named connection on the **POCO Table** instead, e.g:

```csharp
[NamedConnection("Reporting")]
public class Sales { ... }

public class QuerySales : QueryDb<Sales> {}
```

Which can also be added on the Request DTO itself:

```csharp
[NamedConnection("Reporting")]
public class ViewSales : IReturn<ViewSalesResponse> { }
```

### Resolving Named Connections in Services

Whilst inside a Service you can change which DB connection to use by passing in the NamedConnection when opening a DB Connection. E.g. The example below allows the user to change which database to retrieve all sales records for otherwise fallbacks to "Reporting" database by default:

```csharp
public class SalesServices : Service
{
   public IDbConnectionFactory ConnectionFactory { get; set; } 

   public object Any(GetAllSales request)
   {
       var namedConnection = request.NamedConnection ?? "Reporting";
       using (var db = ConnectionFactory.Open(namedConnection)) 
       {
           return db.Select<Sales>();
       }
   }
}
```

### Override Connection used per request at Runtime

All built-in dependencies available from `Service` base class, AutoQuery, Razor View pages, etc are resolved 
from a central overridable location in your `AppHost`. This lets you control which pre-configured 
dependency gets used based on the incoming Request for each Service by overriding any of the `AppHost` methods below: 

```csharp
public IDbConnection Db => db ??= HostContext.AppHost.GetDbConnection(Request);

public IRedisClient Redis => redis ??= HostContext.AppHost.GetRedisClient(Request);

public ICacheClient Cache => cache ??= HostContext.AppHost.GetCacheClient(Request);

public MemoryCacheClient LocalCache => localCache ??= HostContext.AppHost.GetMemoryCacheClient(Request);

public IMessageProducer MessageProducer => messageProducer ??= 
    HostContext.AppHost.GetMessageProducer(Request);
```

E.g. to change the DB Connection your Service uses you can override `GetDbConnection(IRequest)` in your `AppHost`.

## Multitenancy RDBMS AuthProvider

ServiceStack resolves its `IAuthProvider` from the overridable `GetAuthRepository(IRequest)` AppHost factory method just like the other "Multitenancy-aware" dependencies above letting you dynamically change which AuthProvider should be used 
based on the incoming request.

This can be used with the new `OrmLiteAuthRepositoryMultitenancy` provider to maintain isolated 
User Accounts per tenant in all [major supported RDBMS](/ormlite/installation)

Since each tenant database uses their own isolated UserAuth tables we need to provide the list of db 
connection strings that the OrmLite AuthRepository uses to check and create any missing User Auth tables:

```csharp
var connectionStrings = 100.Times(i => GetConnectionStringForTenant(i));
container.Register<IAuthRepository>(c =>
    new OrmLiteAuthRepositoryMultitenancy(c.TryResolve<IDbConnectionFactory>(),
        connectionStrings));

container.Resolve<IAuthRepository>().InitSchema(); // Create any missing UserAuth tables
```

However if you've already created all UserAuth table schema's for each tenant or are manually creating 
them out-of-band you can register it without the list of connection strings:

```csharp
container.Register<IAuthRepository>(c =>
    new OrmLiteAuthRepositoryMultitenancy(c.TryResolve<IDbConnectionFactory>()));
```

Then to specify which AuthRepository should be used for each request we can override `GetAuthRepository()` 
in your AppHost and return the `OrmLiteAuthRepositoryMultitenancy` configured to use the same Multitenant 
DB connection used in that request, e.g:

```csharp
public override IAuthRepository GetAuthRepository(IRequest req = null)
{
    return req != null
        ? new OrmLiteAuthRepositoryMultitenancy(GetDbConnection(req)) //At Runtime
        : TryResolve<IAuthRepository>();                              //On Startup
}
```


Now when `GetAuthRepository()` is called within the context of a request it uses the same Multitenancy 
DB as your other services, otherwise when called outside (e.g. on Startup) it uses the default IOC 
Registration configured with the connectionStrings for each Multitenant DB that it can use to create any
missing UserAuth table schemas not found in any of the Multitenant databases. 

#### Extending UserAuth tables

In the same way that you can use [Custom UserAuth tables in OrmLiteAuthRepository](/auth/authentication-and-authorization#extending-userauth-tables), you can 
also extend `OrmLiteAuthRepositoryMultitenancy` to utilize your own custom `UserAuth` tables with extended fields by configuring them to use its generic class, e.g:

```csharp
public class MyUserAuth : UserAuth { .... }
public class MyUserAuthDetails : UserAuthDetails { .... }
```

```csharp
container.Register<IAuthRepository>(c =>
    new OrmLiteAuthRepositoryMultitenancy<MyUserAuth, MyUserAuthDetails>(c.Resolve<IDbConnectionFactory>()) {
        UseDistinctRoleTables = true
    });
```

### Multi Tenancy Example

To show how easy it is to implement a Multi Tenancy Service with this feature we've added a stand-alone
[Multi Tenancy AppHost Example](https://github.com/ServiceStack/ServiceStack/blob/master/tests/ServiceStack.WebHost.Endpoints.Tests/MultiTenantAppHostTests.cs) 
showing 2 different ways we can configure a Service to use different databases based on an incoming request.

In this example we've configured our AppHost to use the **master.sqlite** database as default and registered
3 different named connections referencing 3 different databases. Each database is then initialized with a 
different row in the `TenantConfig` table to identify the database that it's in.

```csharp
public class MultiTenantChangeDbAppHost : AppSelfHostBase
{
    public MultiTenantChangeDbAppHost()
        : base("Multi Tenant Test", typeof (MultiTenantChangeDbAppHost).Assembly) {}

    public override void Configure(Container container)
    {
        container.Register<IDbConnectionFactory>(new OrmLiteConnectionFactory(
            "~/App_Data/master.sqlite".MapAbsolutePath(), SqliteDialect.Provider));

        var dbFactory = container.Resolve<IDbConnectionFactory>();

        const int noOfTenants = 3;

        using (var db = dbFactory.OpenDbConnection()) {
            InitDb(db, "MASTER", "Masters inc.");
        }

        noOfTenants.Times(i => {
            var tenantId = "T0" + (i + 1);
            using var db = dbFactory.OpenDbConnectionString(GetTenantConnString(tenantId));
            InitDb(db, tenantId, "ACME {0} inc.".Fmt(tenantId));
        });

        RegisterTypedRequestFilter<IForTenant>((req,res,dto) => 
            req.Items[Keywords.DbInfo] = new ConnectionInfo { 
                ConnectionString = GetTenantConnString(dto.TenantId)
            }
        );
    }

    public void InitDb(IDbConnection db, string tenantId, string company)
    {
        db.DropAndCreateTable<TenantConfig>();
        db.Insert(new TenantConfig { Id = tenantId, Company = company });
    }

    public string GetTenantConnString(string tenantId) => tenantId != null 
        ? "~/App_Data/tenant-{0}.sqlite".Fmt(tenantId).MapAbsolutePath()
        : null;
}
```

This example uses only contains a single Service which returns the first result in the `TenantConfig` table:

```csharp
public interface IForTenant
{
    string TenantId { get; }
}

public class TenantConfig
{
    public string Id { get; set; }
    public string Company { get; set; }
}

public class GetTenant : IForTenant, IReturn<GetTenantResponse>
{
    public string TenantId { get; set; }
}

public class GetTenantResponse
{
    public TenantConfig Config { get; set; }
}

public class MultiTenantService : Service
{
    public object Any(GetTenant request)
    {
        return new GetTenantResponse
        {
            Config = Db.Select<TenantConfig>().FirstOrDefault(),
        };
    }
}
```

Calling this Service with a different `TenantId` value changes which database the Service is configured with:

```csharp
var client = new JsonApiClient(Config.AbsoluteBaseUri);

var response = client.Get(new GetTenant()); //= Company: Masters inc. 

var response = client.Get(new GetTenant { TenantId = "T01" }); //= Company: ACME T01 inc.

var response = client.Get(new GetTenant { TenantId = "T02" }); //= Company: ACME T02 inc.

var response = client.Get(new GetTenant { TenantId = "T03" }); //= Company: ACME T03 inc.

client.Get(new GetTenant { TenantId = "T04" }); // throws WebServiceException
```

An alternative way to support Multitenancy using a Custom DB Factory is available in 
[MultiTenantAppHostTests.cs](https://github.com/ServiceStack/ServiceStack/blob/master/tests/ServiceStack.WebHost.Endpoints.Tests/MultiTennantAppHostTests.cs#L129).

```csharp
public class MultiTenantCustomDbFactoryAppHost : AppSelfHostBase
{
    public MultiTenantCustomDbFactoryAppHost()
        : base("Multi Tenant Test", typeof(MultiTenantCustomDbFactoryAppHost).Assembly) { }

    public override void Configure(Container container)
    {
        var dbFactory = new OrmLiteConnectionFactory(
            "~/App_Data/master.sqlite".MapAbsolutePath(), SqliteDialect.Provider);

        const int noOfTenants = 3;

        container.Register<IDbConnectionFactory>(c =>
            new MultiTenantDbFactory(dbFactory));

        var multiDbFactory = (MultiTenantDbFactory)container.Resolve<IDbConnectionFactory>();

        using (var db = multiDbFactory.OpenTenant()) {
            InitDb(db, "MASTER", "Masters inc.");
        }

        noOfTenants.Times(i => {
            var tenantId = "T0" + (i + 1);
            using var db = multiDbFactory.OpenTenant(tenantId);
            InitDb(db, tenantId, "ACME {0} inc.".Fmt(tenantId));
        });

        GlobalRequestFilters.Add((req, res, dto) => {
            if (dto is IForTenant forTenant)
                RequestContext.Instance.Items.Add("TenantId", forTenant.TenantId);
        });
    }

    public void InitDb(IDbConnection db, string tenantId, string company)
    {
        db.DropAndCreateTable<TenantConfig>();
        db.Insert(new TenantConfig { Id = tenantId, Company = company });
    }

    public class MultiTenantDbFactory : IDbConnectionFactory
    {
        private readonly IDbConnectionFactory dbFactory;

        public MultiTenantDbFactory(IDbConnectionFactory dbFactory)
        {
            this.dbFactory = dbFactory;
        }

        public IDbConnection OpenDbConnection()
        {
            var tenantId = RequestContext.Instance.Items["TenantId"] as string;
            return OpenTenant(tenantId);
        }

        public IDbConnection OpenTenant(string tenantId = null)
        {
            return tenantId != null
                ? dbFactory.OpenDbConnectionString(
                    "~/App_Data/tenant-{0}.sqlite".Fmt(tenantId).MapAbsolutePath())
                : dbFactory.OpenDbConnection();
        }

        public IDbConnection CreateDbConnection() => dbFactory.CreateDbConnection();
    }
}
```


# Physical Project Structure
Source: https://docs.servicestack.net/physical-project-structure

The Recommended structure below is built into all ServiceStackVS VS.NET Templates where creating any new ServiceStack project will create a solution with a minimum of 4 projects:

<img class="ml-4 float-right" src="/img/pages/solution-layout.png" />

### Host Project

The Host project contains your AppHost that references and registers all your App's concrete dependencies in its IOC. It also contains any Web Assets like any Razor Views, JS, CSS, Images, Fonts, etc. that's needed to deploy with your App. The AppHost is the master project which references all dependencies used by your App whose role is to act like a conduit where it decides which concrete implementations should be used. By design it references everything and nothing references it which as a goal should be kept logic-free.

### ServiceInterface Project

The ServiceInterface project is the implementation project where all Business Logic and Services live which typically references every other project except the Host projects. Small and Medium projects can maintain all their implementation here where logic can be grouped under sub feature folders. Large solutions can split this project into more manageable cohesive and modular projects which we also recommend encapsulates any dependencies they might use.

### ServiceModel Project

The ServiceModel Project contains all your Application's DTOs which is what defines your Services contract, keeping them isolated from any Server implementation is how your Service is able to encapsulate its capabilities and make them available behind a remote facade. There should be the only ServiceModel project per solution which should be impl, dependency and logic-free which should only reference the impl/dep-free **ServiceStack.Interfaces.dll** contract assembly to ensure Service contracts are decoupled from its implementation, enforces interoperability ensuring that your Services don't mandate specific client implementations and will ensure this is the only project clients need to be able to call any of your Services using either referencing the **ServiceModel.dll** directly or downloading the DTOs from a remote ServiceStack instance using [Add ServiceStack Reference](/add-servicestack-reference):

![](/img/pages/dtos-role.png)

### Test Project

The Unit Test project contains all your Unit and Integration tests. It's also a Host project that typically references all other non-Host projects in the solution and contains a combination of concrete and mock dependencies depending on what's being tested. See the [Testing Docs](/testing) for more information on testing ServiceStack projects.

## Concrete Example

Ideally the root-level **AppHost** project should be kept lightweight and implementation-free. Although for small/prototype projects with only a few services it's fine for everything to be in a single project and to simply grow your architecture when and as needed. 

For medium-to-large projects we recommend the physical structure below we've modelled after this [concrete Events example](http://stackoverflow.com/a/15235822/85785) to describe how we'd typically layout a ServiceStack project. For the purposes of this illustration we'll assume our Application is called **EventMan**. 

The order of the projects also show its dependencies, e.g. the top-level `EventMan` project references **all** sub projects whilst the last `EventMan.ServiceModel` project references **none**:

```
/EventMan
  AppHost.cs                  // The ServiceStack ASP.NET Web or Console Host Project

/EventMan.ServiceInterface    // All Service implementations (akin to MVC Controllers)
  EventsService.cs
  EventsReviewsService.cs

/EventMan.Logic               // For larger projs: pure C# logic deps, data models, etc
  IGoogleCalendarGateway      // E.g of a external dependency this project could use

/EventMan.ServiceModel        // Service Request/Response DTOs and DTO types in /Types
  Events.cs                   // Events, CreateEvent, GetEvent, UpdateEvent DTOs 
  EventReviews.cs             // EventReviews, GetEventReview, CreateEventReview DTOs
  /Types
    Event.cs                  // Event type
    EventReview.cs            // EventReview type
```

With the `EventMan.ServiceModel` DTO's kept in their own separate implementation and dependency-free dll, you're freely able to share this dll in any .NET client project as-is - which you can use with any of the generic [C# Service Clients](/csharp-client) to provide an end-to-end typed API without any code-gen.

## Documented Example Project

The [EmailContacts solution](https://github.com/ServiceStack/EmailContacts/) details the recommended setup and physical layout structure of typical medium-sized ServiceStack projects. It includes the complete documentation going through how to create the solution from scratch, and explains all the ServiceStack hidden features it makes use of along the way.


# Modularizing Services
Source: https://docs.servicestack.net/modularizing-services

ServiceStack only allows a **single App Host** for each App Domain. As you might be able to infer from the name, the role of the **Host** project is to be the conduit for binding all your services concrete dependencies, plugins, filters and everything else your service needs. The configuration of your service should be immutable after everything is initialized in your `AppHost.Configure()` method. The [Physical project structure wiki page](/physical-project-structure) wiki shows the recommended physical project structure for typical solutions.

## Modularizing services in multiple assemblies

Whilst you can only have 1 AppHost, you can have multiple services spread across multiple assemblies. In that case you have to provide a list of assemblies containing the services to the AppHostBase constructor, e.g:

```csharp
public class AppHost : AppHostBase
{
    //Tell ServiceStack the name of your app and which assemblies to scan for services
    public AppHost() : base("Hello ServiceStack!", 
       typeof(ServicesFromDll1).Assembly,
       typeof(ServicesFromDll2).Assembly
       /*, etc */) {}

    public override void Configure(Container container) {}
}
```

You can also provide your own strategy for discovering and resolving the service types that ServiceStack should auto-wire by overriding `CreateServiceManager`, e.g:

```csharp
public class AppHost : AppHostBase
{
    public AppHost(): base("Hello ServiceStack!", typeof(ServicesFromDll1).Assembly) {}
    public override void Configure(Container container) {}
    
    //Alternative way to inject Service Resolver strategy
    protected override ServiceController CreateServiceController(
        params Assembly[] assembliesWithServices)
    {       
        return new ServiceController(this, () => assembliesWithServices.ToList().SelectMany(x =>x.GetTypes()));
    }
}
```

## Encapsulating Services inside Plugins

One way of modularizing services is to encapsulate them inside [Plugins](/plugins) which allows you to manually register services, custom routes, filters, content types, allow customization and anything else your module needs.

To illustrate this point, we'll show what a Basic [Auth Feature](https://github.com/ServiceStack/ServiceStack/blob/master/src/ServiceStack/AuthFeature.cs) example might look like:

```csharp
public class BasicAuthFeature : IPlugin 
{
    public string HtmlRedirect { get; set; }   //User-defined configuration

    public void Register(IAppHost appHost)
    {
        //Register Services exposed by this module
        appHost.RegisterService<AuthService>("/auth", "/auth/{provider}");
        appHost.RegisterService<AssignRolesService>("/assignroles");
        appHost.RegisterService<UnAssignRolesService>("/unassignroles");

        //Load dependent plugins
        appHost.LoadPlugin(new SessionFeature());
    }
}
```

With everything encapsulated inside a plugin, your users can easily enable them in your AppHost with:

```csharp
Plugins.Add(new BasicAuthFeature { HtmlRedirect = "~/login" });
```

## "No touch" Host Configuration

To improve modularization and reuse the configuration logic for a ServiceStack AppHost can be split over multiple files as 
seen with [World Validation's](/world-validation) AppHost where all it's Auth registration is maintained inside 
[Configure.Auth.cs](https://github.com/NetCoreApps/Validation/blob/master/world/Configure.Auth.cs):

```csharp
public class ConfigureAuth : IConfigureAppHost
{
    public void Configure(IAppHost appHost)
    {
        var AppSettings = appHost.AppSettings;
        appHost.Plugins.Add(new AuthFeature(() => new CustomUserSession(),
            new IAuthProvider[] {
            new CredentialsAuthProvider(), //Enable UserName/Password Credentials Auth
        }));

        appHost.Plugins.Add(new RegistrationFeature()); //Enable /register Service

        //override the default registration validation with your own custom implementation
        appHost.RegisterAs<CustomRegistrationValidator, IValidator<Register>>();

        appHost.Register<ICacheClient>(new MemoryCacheClient()); //Store User Sessions in Memory

        appHost.Register<IAuthRepository>(new InMemoryAuthRepository()); //Store Authenticated Users in Memory
   }
}
```

This modular approach makes it easy to "layer on" functionality with tools like [web +](/web-apply).

### ConfigureAppHost Interfaces

You can use this to refactor out different cohesive parts your Host configuration over multiple files and decouple them from your concrete `AppHost` which
ServiceStack automatically runs all `IPreConfigureAppHost`, `IConfigureAppHost` and `IPostConfigureAppHost` interfaces on Startup it 
can find in either your `AppHost` Assembly or **Service Assemblies** specified in your AppHost constructor.

This opens up a number of re-use benefits where you'll be able to use the same AppHost configuration if your Services are being hosted
in [different Hosting Options](/why-servicestack#multiple-hosting-options), it makes it easy to maintain a standardized configuration 
across many of your ServiceStack projects, e.g. you can easily replace `Configure.Auth.cs` in all your projects to ensure they're running
the same Auth Configuration without impacting any of the projects other bespoke host configuration.

### Bundle Startup Logic in your Services Assembly

It also allows you to maintain any necessary Startup configuration that your Services implementation needs alongside the Services themselves.

E.g. This is used to register the `Data.Contact` to DTO `Contact` [Auto Mapping](/auto-mapping):

```csharp
// Register Custom Auto Mapping for converting Contact Data Model to Contact DTO
public class ContactsHostConfig : IConfigureAppHost 
{
    public void Configure(IAppHost appHost) =>
        AutoMapping.RegisterConverter((Data.Contact from) => from.ConvertTo<Contact>(skipConverters:true));
}
```

There are **3 different Startup interfaces** you can use depending on when you want your configuration to run.

### Register additional Service Assemblies on Startup

Use `IPreConfigureAppHost` for Startup logic you want to run before the AppHost starts initialization, this is
run before `AppHost.Config` is initialized or Services are registered so has limited configurability but is useful
if you want to register additional Service Assemblies with ServiceStack, e.g:

```csharp
public class ConfigureContactsServices : IPreConfigureAppHost
{
    public void PreConfigure(IAppHost host) => host.ServiceAssemblies.AddIfNotExists(typeof(MyServices).Assembly);
}
```

### Register no-touch Startup before and after your AppHost's Configure

Use `IConfigureAppHost` for Startup logic you want to run immediately **before** `AppHost.Configure()`:

```csharp
public interface IConfigureAppHost
{
    void Configure(IAppHost appHost);
}
```

Use `Priority <= -1` for Startup logic you want to run **before** `AppHost.Configure()` and
`Priority >= 1` for logic you want to run immediately **after** `AppHost.Configure()`:

```csharp
[Priority(-1)]
public class MyPreAppHostConfigure : IConfigureAppHost
{
    public void Configure(IAppHost host) => ...;
}

[Priority(1)]
public class MyPostAppHostConfigure : IConfigureAppHost
{
    public void Configure(IAppHost host) => ...;
}
```


# Built-in Mini Profiler
Source: https://docs.servicestack.net/built-in-profiling

## Try the built-in Admin Logging & Profiling UI

For a better integrated alternative to Mini Profiler checkout the built-in Admin [Logging & Profiling UI](/admin-ui-profiling).

---

## MVC Mini Profiler

ServiceStack's [HTML5 JSON Report Format](/html5reportformat) also includes the [Mvc Mini Profiler](https://github.com/MiniProfiler/dotnet) - by [@jarrod_dixon](https://twitter.com/jarrod_dixon) and [@samsaffron](https://twitter.com/samsaffron).
It's the same profiler used to profile and help speed up sites like [Stack Overflow](http://www.stackoverflow.com) and more recently the much faster [NuGet v2.0](http://nuget.org) website.

The MVC Mini Profiler plugin is only available for classic ASP.NET Framework Web Apps, for .NET Core Apps you can use the official [MiniProfiler.AspNetCore.Mvc](https://www.nuget.org/packages/MiniProfiler.AspNetCore.Mvc) NuGet package, please see this community post for details:

### Using the MVC Mini Profiler

The built-in Mini Profiler is available in ServiceStack's .NET Framework features package:

:::copy
`<PackageReference Include="ServiceStack.NetFramework" Version="8.*" />`
:::

Just like the [Normal Mvc Mini Profiler](https://github.com/MiniProfiler/dotnet) you can enable it by registering the `MiniProfilerFeature` Plugin:

```csharp
Plugins.Add(new MiniProfilerFeature());  
```

Then starting it in your Global.asax, here's how to enable it for local requests:

```csharp
protected void Application_BeginRequest(object src, EventArgs e)
{
    if (Request.IsLocal)
        Profiler.Start();
}

protected void Application_EndRequest(object src, EventArgs e)
{
    Profiler.Stop();
}
```

Now if you also have ServiceStack Razor views you can enable the profiler by putting this into your _Layout.cshtml page:

```csharp
@ServiceStack.MiniProfiler.Profiler.RenderIncludes().AsRaw() 
```

That's it! Now every time you view a web service or a razor page in your browser (locally) you'll see a profiler view of your service broken down in different stages:

![Hello MiniProfiler](/img/pages/advanced/miniprofiler-hello.png)

By default you get to see how long it took ServiceStack to de-serialize your request, run any Request / Response Filters and more importantly how long it took to **Execute** your service.

## SQL Profiling

The profiler includes special support for SQL Profiling that can easily be enabled for OrmLite and Dapper by getting it to use a Profiled Connection using a ConnectionFilter:

```csharp
Plugins.Add(new MiniProfilerFeature()); // Register before using ProfiledDbConnection

this.Container.Register<IDbConnectionFactory>(c =>
    new OrmLiteConnectionFactory(
        "~/App_Data/db.sqlite".MapHostAbsolutePath(), SqliteDialect.Provider) {
            ConnectionFilter = x => new ProfiledDbConnection(x, Profiler.Current)
    });
```

Refer to the [Main MVC MiniProfiler home page](https://github.com/MiniProfiler/dotnet) for instructions on how to configure profiling for Linq2Sql and EntityFramework.

It's also trivial to add custom steps enabling even finer-grained profiling for your services. 
Here's a [simple web service DB example](https://github.com/ServiceStack/ServiceStack/blob/master/tests/ServiceStack.WebHost.IntegrationTests/Services/ProfilerService.cs) 
returning a list of Movies using both a simple DB query and a dreaded N+1 query.

```csharp
public class MiniProfiler
{
    public string Type { get; set; }
}

public class MiniProfilerService : Service
{
    public object Any(MiniProfiler request)
    {
        var profiler = Profiler.Current;

        using (profiler.Step("MiniProfiler Service"))
        {
            if (request.Type == "n1")
            {
                using (profiler.Step("N + 1 query"))
                {
                    var results = new List<Movie>();
                    foreach (var movie in Db.Select<Movie>())
                    {
                        results.Add(Db.QueryById<Movie>(movie.Id));
                    }
                    return results;
                }
            }

            using (profiler.Step("Simple Select all"))
            {
                return Db.Select<Movie>();
            }
        }
    }
}
```

## View executed SQL

Calling the above service normally provides the following Profiler output:

![Simple DB Example](/img/pages/advanced/miniprofiler-simpledb.png)

Whilst calling the service with the **n1** param yields the following warning:

![Simple N+1 DB Example](/img/pages/advanced/miniprofiler-simpledb-n1.png)

In both cases you see the actual SQL statements performed by clicking the **SQL** link. The N+1 query provides shows the following:

![N+1 DB Example SQL Statementes](/img/pages/advanced/miniprofiler-simpledb-n1-sql.png)

Notice the special attention the MVC MiniProfiler team put into identifying **Duplicate** queries - Thanks Guys!


# Community Resources

  - [MiniProfiler for AJAX calls with ServiceStack.Net](http://tunurgitr.blogspot.com/2012/04/miniprofiler-for-ajax-calls-with.html) by Jeff Harris


# Hot Reloading
Source: https://docs.servicestack.net/hot-reloading

ServiceStack includes 2 Hot Reloading solutions to automatically detect file changes and reload your page on save.

## Hot Reload Static Files

If you're not developing your Website with `#Script` or are developing a Single Page App where it's mostly contained in static files
you can use the `HotReloadFeature` plugin which has added support for monitoring multiple File Search Patterns and can now be configured
to monitor a different VFS provider (defaults to WebRoot).

The new "lite" projects utilize both these features for its hot reloading support:

```csharp
if (Config.DebugMode)
{
    Plugins.Add(new HotReloadFeature {
        DefaultPattern = "*.html;*.js;*.css",
        VirtualFiles = VirtualFiles // Monitor ContentRoot to detect changes in /src
    });
}
```

Which is enabled during development in `_layout.html` by including `/js/hot-fileloader.js`:

::: v-pre
```html
<i hidden>{{ '/js/hot-fileloader.js' |> ifDebugIncludeScript }}</i>
```
:::

Or if you're not using [#Script Pages](https://sharpscript.net/docs/script-pages) you can add the script tag:

```html
<script src="/js/hot-fileloader.js"></script>
```

#### Hot Reload Sharp Pages

The [Hot Reloading](https://sharpscript.net/docs/hot-reloading) support in Sharp Pages enables the `HotReloadFilesService`
when registering the `SharpPagesFeature`, e.g:

```csharp
Plugins.Add(new SharpPagesFeature {
    EnableHotReload = Config.DebugMode //default
});
```

This is enabled in your pages with this snippet which renders the hot reload client script during development:

::: v-pre
```html
<i hidden>{{ '/js/hot-loader.js' |> ifDebugIncludeScript }}</i>
```
:::

Which starts a long poll that calls the smart `HotReloadFilesService` which recursively inspects the current tokenized 
[Sharp Pages](https://sharpscript.net/docs/script-pages) to find if it or any dependent layouts, partials or file includes have changed.

Sharp Page's Hot Reload feature now also monitors **Paged Based Routing Pages** and **View Pages**.

If enabled and working correctly hot reloading should allow you to view instant UI changes on save:

[![](/img/pages/app/vue-desktop/vuedesktop-livereload.gif)](https://www.vuedesktop.com)


# HTML, CSS and JavaScript Minification
Source: https://docs.servicestack.net/html-css-and-javascript-minification

As part of our quest to provide a complete and productive solution for developing highly responsive Web and Single Page Apps, ServiceStack now includes minifiers for compressing HTML, CSS and JavaScript available from the new `Minifiers` class: 

```csharp
var minifiedJs = Minifiers.JavaScript.Compress(js);
var minifiedCss = Minifiers.Css.Compress(css);
var minifiedHtml = Minifiers.Html.Compress(html);

// Also minify in-line CSS and JavaScript
var advancedMinifiedHtml = Minifiers.HtmlAdvanced.Compress(html);
```

::: info
Each minifier implements the lightweight [ICompressor](https://github.com/ServiceStack/ServiceStack/blob/master/src/ServiceStack.Interfaces/ICompressor.cs) interface making it trivial to substitute with a custom implementation
:::

#### JS Minifier
For the JavaScript minifier we're using [Ext.Net's C# port](https://github.com/extnet/Ext.NET.Utilities/blob/master/Ext.Net.Utilities/JavaScript/JSMin.cs) of Douglas Crockford's venerable [JSMin](http://crockford.com/javascript/jsmin). 

#### CSS Minifier
The CSS Minifier uses Mads Kristensen simple [CSS Minifer](http://madskristensen.net/post/efficient-stylesheet-minification-in-c). 

#### HTML Compressor
For compressing HTML we're using a [C# Port](http://blog.magerquark.de/c-port-of-googles-htmlcompressor-library/) of Google's excellent [HTML Compressor](https://code.google.com/p/htmlcompressor/) which we've further modified to remove the public API's ugly Java-esque idioms and replaced them with C# properties.

The `HtmlCompressor` also includes a number of well-documented options which can be customized by configuring the available properties on its concrete type, e.g:

```csharp
var htmlCompressor = (HtmlCompressor)Minifier.Html;
htmlCompressor.RemoveComments = false;
```

### Easy win for server generated websites

If your project is not based off one of our optimized [Webpack-powered Single Page App templates](/templates/single-page-apps) or configured to use our earlier [node.js-powered Bundler](https://github.com/ServiceStack/Bundler) Web Optimization solution, these built-in minifiers now offers the easiest solution to effortlessly optimize your existing website which is able to work transparently with your existing Razor Views and static `.js`, `.css` and `.html` files without requiring adding any additional external tooling or build steps to your existing development workflow.

### Optimal Library Bundles

To facilitate splitting JS and CSS assets into multiple bundles without needing to create artificial directories for each bundle
you can use the `!` prefix to exclude files from bundles.

Example from `sharp` [_layout.html](https://github.com/NetCoreTemplates/sharp/blob/master/MyApp/wwwroot/_layout.html):

::: v-pre
```hbs
{{ (debug ? '' : '[hash].min') | to => min }}

{{ [ '!/assets/css/default.css', '/assets/css/', '/css/buttons.css', '/css/svg-auth.css', 
     '/css/svg-icons.css', '/css/app.css' ]
   |> bundleCss({ disk:!debug, out:`/css/lib.bundle${min}.css` }) }}

{{ [ '/assets/css/default.css']
   |> bundleCss({ minify:!debug, cache:!debug, disk:!debug, out:`/css/bundle${min}.css` }) }}
```
:::

Here the App specific `default.css` is excluded when bundling all other `.css` files in the `/assets/css/` directory as
it's included on its own in a separate app **bundle.css** below.

::: v-pre
```hbs
{{ [ '!/assets/js/dtos.js', '!/assets/js/default.js', '/assets/js/jquery.min.js', '/assets/js/' ]
   |> bundleJs({ disk:!debug, out:`/js/lib.bundle${min}.js` }) }} 

{{ [ '/assets/js/dtos.js', '/assets/js/default.js' ]
   |> bundleJs({ minify:!debug, cache:!debug, disk:!debug, out:`/js/bundle${min}.js` }) }}
```
:::

Likewise the App specific `dtos.js` and `default.js` files are excluded from the library bundle and included in its own app **bundle.js**.

The equivalent bundle API's are also available in ServiceStack.Razor projects as seen in the `razor` template's 
[_Layout.cshtml](https://github.com/NetCoreTemplates/razor/blob/master/MyApp/Views/Shared/_Layout.cshtml):

```csharp
@{ 
  var debug = DebugMode;
  var min = debug ? "" : "[hash].min";
}

@Html.BundleCss(new BundleOptions {
    Sources = {
        "!/assets/css/default.css",
        "/assets/css/",
        "/css/buttons.css",
        "/css/svg-auth.css",
        "/css/svg-icons.css",
        "/css/app.css",
    },
    SaveToDisk = !debug,
    OutputTo = $"/css/lib.bundle{min}.css"
})

@Html.BundleCss(new BundleOptions {
    Sources = {
        "/assets/css/default.css",
    },
    Minify = !debug,
    Cache = !debug,
    SaveToDisk = !debug,
    OutputTo = $"/css/bundle{min}.css"
})

//...

@Html.BundleJs(new BundleOptions {
    Sources = {
        "!/assets/js/dtos.js",
        "!/assets/js/default.js",
        "/assets/js/jquery.min.js",
        "/assets/js/",
    },
    SaveToDisk = !debug,
    OutputTo = $"/js/lib.bundle{min}.js"
})

@Html.BundleJs(new BundleOptions {
    Sources = {
        "/assets/js/dtos.js",
        "/assets/js/default.js",
    },
    Minify = !debug,
    Cache = !debug,
    SaveToDisk = !debug,
    OutputTo = $"/js/bundle{min}.js"
})
```

### cssIncludes

Single Page App Templates also makes use of `cssIncludes` to embed multiple `*.css` files inline in the initial page request,
avoiding external resource requests as seen in the `vue-lite` template 
[_layout.html](https://github.com/NetCoreTemplates/vue-lite/blob/master/wwwroot/_layout.html):

::: v-pre
```hbs
{{ 'buttons,svg-auth,app,/assets/css/default.css' | cssIncludes }}
{{ 'svg-icons' | cssIncludes | svgFill('#41B883') }}
```
:::

By default `cssIncludes` references files in the format `/css/{name}.css` which can be overridden by specifying
the Virtual Path to the file. It can be useful to use in conjunction with `svgFill` to change the **fill** color 
of all SVG images in the SVG CSS bundle as seen above.

## Configure NUglify

You can configure your ServiceStack App to use Nuglify's Advanced HTML, CSS, JS Minifiers using [mix](/mix-tool) with:

:::sh
x mix nuglify 
:::

Which will write [Configure.Nuglify.cs](https://gist.github.com/gistlyn/4bdb79d21f199c22b8a86f032c186e2d) to your **HOST** project.

## Integrated Bundling Example

For more detailed information on using ServiceStack's built-in bundling checkout the 
[Integrated Bundling in Vue/React lite templates](/templates/lite#integrated-bundling).


### Minify static `.js`, `.css` and `.html` files

With nothing other than the new minifiers, we can leverage the flexibility in ServiceStack's [Virtual File System](/virtual-file-system) to provide an elegant solution for minifying static `.html`, `.css` and `.js` resources by simply pre-loading the pre-configured Memory Virtual FileSystem with minified versions of existing files and giving the Memory FS a higher precedence so any matching requests serve up the minified version first:

```csharp
public class MyPlugin : IPlugin, IPostInitPlugin
{
    public void Register(IAppHost appHost) { }

    public void AfterPluginsLoaded(IAppHost appHost)
    {
        var memFs = appHost.VirtualFileSources.GetMemoryVirtualFiles();

        //Get FileSystem Provider
        var fs = appHost.VirtualFileSources.GetFileSystemVirtualFiles();

        //Process all .html files:
        foreach (var file in fs.GetAllMatchingFiles("*.html"))
        {
            var contents = Minifiers.HtmlAdvanced.Compress(file.ReadAllText());
            memFs.WriteFile(file.VirtualPath, contents);
        }

        //Process all .css files:
        foreach (var file in fs.GetAllMatchingFiles("*.css")
            .Where(file => !file.VirtualPath.EndsWith(".min.css")))
        {
            var contents = Minifiers.Css.Compress(file.ReadAllText());
            memFs.WriteFile(file.VirtualPath, contents);
        }

        //Process all .js files
        foreach (var file in fs.GetAllMatchingFiles("*.js")
            .Where(file => !file.VirtualPath.EndsWith(".min.js")))
        {
            try
            {
                var js = file.ReadAllText();
                var contents = Minifiers.JavaScript.Compress(js);
                memFs.WriteFile(file.VirtualPath, contents);
            }
            catch (Exception ex)
            {
                //Report any errors in StartUpErrors collection on ?debug=requestinfo
                base.OnStartupException(new Exception(
                    $"JSMin Error in {file.VirtualPath}: {ex.Message}"));
            }
        }
    }
}
```

A nice benefit of this approach is that it doesn't pollute your project with minified build artifacts, has excellent runtime performance with the minified contents being served from Memory and as the file names remain the same, the links in HTML don't need to be rewritten to reference the minified versions. i.e. When a request is made it just looks through the registered virtual path providers and returns the first match, which given the Memory FS was inserted at the start of the list, returns the minified version.

### Enabled in [servicestack.net](https://servicestack.net)

As this was an quick and non-invasive feature to add, we've enabled it on all [servicestack.net](https://servicestack.net) Razor views and static files. You can `view-source:https://servicestack.net/` (as url in Chrome, Firefox or Opera) to see an example of the resulting minified output. 

### Minify dynamic Razor Views

Minification of Razor Views is easily enabled by specifying `MinifyHtml=true` when registering the `RazorFormat` plugin:

```csharp
Plugins.Add(new RazorFormat {
    MinifyHtml = true,
    UseAdvancedCompression = true,
});
```

Use the `UseAdvancedCompression=true` option if you also want to minify inline js/css, although as this requires a bit more processing you'll want to benchmark it to see if it's providing an overall performance benefit to end users. It's a recommended option if you're caching Razor Pages. Another solution is to minimize the use of in-line js/css and move them to static files to avoid needing in-line js/css compression.


# Unified Navigation
Source: https://docs.servicestack.net/navigation

With the App composition model in [ModularStartup](/modular-startup) we want to enable features to be able to have deep integration with your App 
for instant utility and to reduce the effort required to integrate it with your App.

A problem with being able to add an integrated feature that combines both UI and functionality is the large variety of different
kind of Apps that can be created with ServiceStack. To give you some idea, the [World Validation](/world-validation) contains 
**10 different client/server rendered** Web App development strategies - which doesn't even cover all the major SPA that ServiceStack 
has first-class support for, not including any native Desktop or Mobile Apps.

To be able to provide higher-level functionality with instant utility we need a standard navigation API that all Apps can use to 
register functionality that all ServiceStack Apps can make use of.

To support this, we use the new `NavItem` below to capture hierarchical Navigation information about a single Navigation Item:

```csharp
/// NavItem in View.NavItems and View.NavItemsMap
public class NavItem : IMeta
{
    /// Link Label
    public string Label { get; set; }
    
    /// Link href
    public string Href { get; set; }
    
    /// Whether NavItem should only be considered active when paths 
    /// are an exact match otherwise checks if ActivePath starts with Path
    public bool? Exact { get; set; }

    /// Emit id="{Id}"
    public string Id { get; set; }

    /// Override class="{Class}"
    public string ClassName { get; set; }

    /// Icon class (if any)
    public string IconClass { get; set; } 
    
    /// Only show if NavOptions.Attributes.Contains(Show) 
    public string Show { get; set; }
    
    /// Do not show if NavOptions.Attributes.Contains(Hide) 
    public string Hide { get; set; }
    
    /// Sub Menu Child NavItems
    public List<NavItem> Children { get; set; }
    
    /// Additional custom Metadata to attach to this Nav Item
    public Dictionary<string, string> Meta { get; set; }
}
```

There's also 2 built-in collections you can add Navigation Items to:

```csharp
public static class View
{
    // The App's main navigation
    public static List<NavItem> NavItems

    // Maintain any other number of custom Navigation lists
    public static Dictionary<string, List<NavItem>> NavItemsMap
}
```

Simply `View.NavItems` can be used to maintain your App's primary navigation whilst `NavItemsMap` lets you maintain any number of additional 
navigation item groups. 

For example ServiceStack uses `NavItemsMap` to maintain Navigation items for each OAuth provider in the `auth` NavItem collection
which is now able to generate an auto dynamic list of Auth Sign In Options from the existing list of Auth Providers registered
in your App's `AuthFeature`, e.g:

```csharp
Plugins.Add(new AuthFeature(() => new AuthUserSession(),
    new IAuthProvider[] {
        new CredentialsAuthProvider(AppSettings),
        new FacebookAuthProvider(AppSettings),
        new GoogleAuthProvider(AppSettings),
        new MicrosoftGraphAuthProvider(AppSettings),
        new TwitterAuthProvider(AppSettings),
        new GithubAuthProvider(AppSettings),
    }));
```

Will render the following list of OAuth Sign In buttons in new ServiceStack Project Templates:

![](/img/pages/nav/auth-navitems.png)

This is enabled by each OAuth Provider defining their own Navigation Item which is used to populate the `auth` NavItems collection, 
here's an example from [FacebookAuthProvider](https://github.com/ServiceStack/ServiceStack/blob/master/src/ServiceStack/Auth/FacebookAuthProvider.cs):

```csharp
NavItem = new NavItem {
    Href = "/auth/" + Name,
    Label = "Sign in with Facebook",
    Id = "btn-" + Name,
    ClassName = "btn-social btn-facebook",
    IconClass = "fab svg-facebook",
};
```

### Load from Configuration

To start with, the NavItems collections can be initialized from `appsettings.json` by populating the `NavItems` and `NavItemsMap` collections, e.g:

```json
{
  "NavItems": [
    { "href":"/",                   "label":"Home", "exact":true },
    { "href":"/about",              "label":"About" },
    { "href":"/services",           "label":"Services" },
    { "href":"/contact",            "label":"Contact",
      "children": [
        { "href": "/contact/me",    "label":"Me" },
        { "href": "/contact/email", "label":"Email" },
        { "label":"-" },
        { "href": "/contact/phone", "label":"Phone" }
      ]
    },
    { "href":"/login",      "label":"Sign In", "hide":"auth" },
    { "href":"/profile",    "label":"Profile", "show":"auth" },
    { "href":"/admin",      "label":"Admin",   "show":"role:Admin" }
  ],
  "NavItemsMap": {
    "aside": [
      { "href":"/faq",     "label":"FAQ" }
    ],
    "footer": [
      { "href":"/terms",   "label":"Terms" },
      { "href":"/privacy", "label":"Privacy" }
    ]
  }
}
```

### Populate from Code

Or if preferred you can create the navigation in code:

```csharp
View.NavItems.AddRange(new List<NavItem>
{
    new NavItem { Href = "/",         Label = "Home",    Exact = true },
    new NavItem { Href = "/about",    Label = "About" },
    new NavItem { Href = "/services", Label = "services" },
    new NavItem
    {
        Href = "/contact", Label = "Contact",
        Children = new List<NavItem>
        {
            new NavItem { Href = "/contact/me", Label = "Me" },
            new NavItem { Href = "/contact/email", Label = "Email" },
            new NavItem { Label = "-" },
            new NavItem { Href = "/contact/phone", Label = "Phone" },
        }
    },
    new NavItem { Href = "/login",    Label = "Sign In", Hide = "auth" },
    new NavItem { Href = "/profile",  Label = "Profile", Show = "auth" },
    new NavItem { Href = "/admin",    Label = "Admin",   Show = "role:Admin" },
});
```

Which when used to render your main menu navigation in a Bootstrap Web App, looks something like:

![](/img/pages/nav/appsettings.png)

### UI Feature Integration

The `NavItems` generic collections can be further extended programmatically which allows UI plugins to register their functionality with the App's UI.

Here are some examples that the new 
[feature-authrepo](https://gist.github.com/gistlyn/9fe61f1967c53d85984402118ee03017) and
[feature-mq](https://gist.github.com/gistlyn/355338cd60a32ee9c9fc4761269f7782) `mix` features 
use to register their pages with the running Web App:

#### Feature.UserAuth.cs 

```csharp
public void AfterPluginsLoaded(IAppHost appHost)
{
    View.NavItems.Add(new NavItem {
        Label = "Users",
        Href = "/admin/users",
        // Show = "role:Admin" // Uncomment to only show menu item to Admin Users
    });
}
```

Which adds the **Users** Menu Item linking to the [/admin/users.html](https://gist.github.com/gistlyn/9fe61f1967c53d85984402118ee03017#file-wwwroot-admin-users-html) page:

![](/img/pages/nav/feature-authrepo.png)

#### Feature.Mq.cs

```csharp
public void AfterPluginsLoaded(IAppHost appHost)
{
    View.NavItems.Add(new NavItem {
        Label = "Messaging",
        Href = "/messaging",
    });
}
```

Which adds the **Messaging** Menu Item linking to its [messaging.html](https://gist.github.com/gistlyn/355338cd60a32ee9c9fc4761269f7782#file-wwwroot-messaging-html) page:

![](/img/pages/nav/feature-mq.png)


### Navigation Renderers

The `NavItem` classes capture the Navigation information which is used together with the `NavOptions` class below:

```csharp
public class NavOptions
{
    /// User Attributes for conditional rendering, e.g:
    ///  - auth - User is Authenticated
    ///  - role:name - User Role
    ///  - perm:name - User Permission 
    public HashSet<string> Attributes { get; set; }
    
    /// Path Info that should set as active 
    public string ActivePath { get; set; }
    
    /// Prefix to include before NavItem.Path (if any)
    public string BaseHref { get; set; }

    // Custom classes applied to different navigation elements (defaults to Bootstrap classes)
    public string NavClass { get; set; }
    public string NavItemClass { get; set; }
    public string NavLinkClass { get; set; }
    
    public string ChildNavItemClass { get; set; }
    public string ChildNavLinkClass { get; set; }
    public string ChildNavMenuClass { get; set; }
    public string ChildNavMenuItemClass { get; set; }
}
```

To customize how navigation items are rendered using the new navigation controls available for each of ServiceStack's most popular Project Types.

All components are customizable in the same way and render the same markup, apart from Angular due to how it renders components where 
it includes additional "wrapper" HTML tags around each component.

### `#Script` Pages

In [#Script Pages](https://sharpscript.net/docs/script-pages) you can use render the `navbar` and `navButtonGroup` methods to render NavItems:

#### Navbar

You can render the **main menu** navigation using the 
[navbar](https://github.com/NetCoreTemplates/sharp/blob/50b77454950ef0590042e08cf327aae602a2ab0a/MyApp/wwwroot/_layout.html#L30) script method:

::: v-pre
```hbs
{{ navbar }}
```
:::

Which by default renders the `View.NavItems` main navigation, using the default `NavOptions` and User Attributes (if authenticated): 

![](/img/pages/nav/appsettings.png)

You can also render a **different Navigation List** with:

::: v-pre
```hbs
{{ navbar(navItems('submenu')) }}
```
:::

Which can be customized using the different `NavOptions` properties above, in camelCase:

::: v-pre
```hbs
{{ navbar(navItems('submenu'), { navClass: 'navbar-nav navbar-light bg-light' }) }}
```
:::

#### Rewritten using #Script Extension methods

Thanks to `#Script` new ability to be able to call any script methods as extension methods, this can also be rewritten as:

::: v-pre
```hbs
{{ 'submenu'.navItems().navbar({ navClass: 'navbar-nav navbar-light bg-light' }) }}
```
:::

#### Button group

The `navButtonGroup` script can render NavItems in a button group, e.g. the
[OAuth buttons](https://github.com/NetCoreTemplates/sharp/blob/50b77454950ef0590042e08cf327aae602a2ab0a/MyApp/wwwroot/login.html#L46)
are rendered with:

::: v-pre
```hbs
{{ 'auth'.navItems().navButtonGroup({ navClass: '', navItemClass: 'btn btn-block btn-lg' }) }}
```
:::

Which renders a vertical, spaced list of buttons which look like:

![](/img/pages/nav/auth-navitems.png)


### Razor Pages

The same server controls are available in ServiceStack.Razor Apps as HTML Helper extension methods: 

#### Navbar

```csharp
@Html.Navbar()

@Html.Navbar(Html.GetNavItems("submenu"))

@Html.Navbar(Html.GetNavItems("submenu"), new NavOptions {
    NavClass = "navbar-nav navbar-light bg-light"
})
```

#### NavButtonGroup

```csharp
@Html.NavButtonGroup(Html.GetNavItems("auth"), new NavOptions {
    NavClass = "",
    NavItemClass = "btn btn-block btn-lg",
})
```

## SPA Component Libraries

To lay the foundation for richer and more tightly integrated UI controls, we've created UI and common component libraries for the 
3 most popular JS frameworks:

### [@servicestack/vue](https://github.com/ServiceStack/servicestack-vue)

### [@servicestack/react](https://github.com/ServiceStack/servicestack-react)

### [@servicestack/angular](https://github.com/ServiceStack/servicestack-angular)

All [Single Page App Project Templates](/templates/single-page-apps) have been pre-configured to use these libraries which will make it 
a lot easier to deliver new UI components and updates to existing SPA Apps with just an npm upgrade.

### Navigation Components

All navigation components are populated the same way for all JavaScript FX's where it embeds the navigation data structure in the page by
serializing the response of the `GetNavItems` Service to JSON that's embedded in the layout page where it's only loaded once 
upon the initial page request (immediately, without an Ajax network request): 

::: v-pre
```hbs
{{#script}}
NAV_ITEMS = {{ 'GetNavItems'  |> execService |> json }};
AUTH      = {{ 'Authenticate' |> execService({ ifErrorReturn: "null" }) |> json }};
{{/script}}
```
:::

The navigation items data structure is used with new Navigation Components for each JavaScript FX to render the menu navigation
which is initially captured in a state object containing the NavItems data structure, the Users Session and the list
of User Attributes generated from the Authenticated Users Session (if any), e.g:

### Vue

In Vue the Nav and User Information is maintained in a global `store` object which uses `UserAttributes.fromSession()` from the 
`@servicestack/client` library to generate the list of User Attributes:

```ts
export const store: State = {
  nav: global.NAV_ITEMS as GetNavItemsResponse,
  userSession: global.AUTH as AuthenticateResponse,
  userAttributes: UserAttributes.fromSession(global.AUTH),
};
```

The built-in list of User Attributes include:

  - `auth` - Authenticated User
  - `role:TheRole` - Authenticated User with `TheRole` role.
  - `perm:ThePermission` - Authenticated User with `ThePermission` permission.

This list can be further extended to include your own custom User Attributes, these are used to control whether to display the navigation item 
based on if the attribute is an exact match for the `Show` and `Hide` properties of the `NavItem`. E.g. Navigation Items populated with:

```json
  "NavItems": [
    { "href":"/login",      "label":"Sign In", "hide":"auth" },
    { "href":"/profile",    "label":"Profile", "show":"auth" },
    { "href":"/admin",      "label":"Admin",   "show":"role:Admin" }
  ],
```

Will hide the **Sign In** and show the **Profile** nav items to Authenticated Users and only show the **Admin** nav item to Admin Users.

The `navbar` component uses these data structures to [render the main menu](https://github.com/NetCoreTemplates/vue-spa/blob/24ce35d67dcec0f4e00f0dd2f40cf2e8f0c58c7c/MyApp/src/App.vue#L9):

```html
<navbar :items="store.nav.results" :attributes="store.userAttributes" />
```

The rendering of the component can be further customized using any of the `NavOptions` properties, in **camelCase**.

Which also applies to the list of [registered OAuth provider buttons](https://github.com/NetCoreTemplates/vue-spa/blob/24ce35d67dcec0f4e00f0dd2f40cf2e8f0c58c7c/MyApp/src/App.vue#L9)
rendered with `<nav-button-group>`:

```html
<nav-button-group :items="store.nav.navItemsMap.auth" :attributes="store.userAttributes" 
                  :baseHref="store.nav.baseUrl" block lg />
```

In addition to `NavOptions` properties, new Bootstrap UI Controls (in each JavaScript FX) can also use these common bootstrap attributes
to stylize their components:

```ts
export declare class BootstrapBase extends Vue {
    primary?: boolean;
    outlinePrimary?: boolean;
    secondary?: boolean;
    outlineSecondary?: boolean;
    success?: boolean;
    outlineSuccess?: boolean;
    info?: boolean;
    outlineInfo?: boolean;
    warning?: boolean;
    outlineWarning?: boolean;
    danger?: boolean;
    outlineDanger?: boolean;
    light?: boolean;
    outlineLight?: boolean;
    dark?: boolean;
    outlineDark?: boolean;
    lg?: boolean;
    md?: boolean;
    sm?: boolean;
    xs?: boolean;
    block?: boolean;
    vertical?: boolean;
    horizontal?: boolean;
}
```

> camelCase properties like `outlinePrimary` are exposed as **kebab-case** in components, e.g. `outline-primary`

### React

These same components are 
[available in React](https://github.com/NetCoreTemplates/react-spa/blob/7bee202a4ceff4b5a191df178633c45f7f736073/MyApp/src/App.tsx#L46) 
from the new `@servicestack/react` library, except the JSX Components use PascalCase, e.g:

```html
<Navbar items={state.nav.results} attributes={state.userAttributes} />
```

Likewise for [NavButtonGroup](https://github.com/NetCoreTemplates/react-spa/blob/7bee202a4ceff4b5a191df178633c45f7f736073/MyApp/src/components/SignIn.tsx#L93):

```html
<NavButtonGroup items={state.nav.navItemsMap.auth} attributes={state.userAttributes} 
                baseHref={state.nav.baseUrl} block lg />
```

### Angular

Likewise for Angular from the new `@servicestack/angular` package where the main menu is rendered using the 
[navbar component](https://github.com/NetCoreTemplates/angular-spa/blob/278a965d3b8d922f6ea55408269308ff90913263/MyApp/src/app/app.component.html#L9):

```html
<navbar [items]="nav.results" [attributes]="userAttributes"></navbar>
```

And the OAuth Button list is rendered using the [nav-button-group component](https://github.com/NetCoreTemplates/angular-spa/blob/278a965d3b8d922f6ea55408269308ff90913263/MyApp/src/app/signin/index.ts#L49) in kebab-case:

```html
 <nav-button-group [items]="nav.navItemsMap.auth" [attributes]="userAttributes" 
                   [baseHref]="nav.baseUrl" block lg></nav-button-group>
```

### Mobile and Desktop Apps

Whilst there are no native components developed for different Mobile and Desktop UI's, the same navigation information can be accessed
by calling the `GetNavItems` Service, e.g:

```csharp
var response = await client.GetAsync(new GetNavItems());
```


# App Tasks
Source: https://docs.servicestack.net/app-tasks

App Tasks let you run one-off tasks with the full context of your App but without the overhead of maintaining a separate **.exe** with duplicated App configuration.
With App Tasks you can run your ASP .NET Core App, run the specified Tasks then exit before launching its HTTP Server.

### Example

The `AppTasks` static class can be used to register user-defined tasks, e.g:

```csharp
var runner = new TaskRunner(app.Services);
AppTasks.Register("task1", args => runner.Task1(args));
AppTasks.Register("task2", args => runner.Task2(args));
AppTasks.Run();

app.Run();
```

Which can then be run from the command-line with:

:::sh
dotnet run --AppTasks=task1:arg1,arg2;task2:arg1,arg2
:::

Which will run the tasks in the specified order, before immediately exiting. If any of the tasks fail the command will return the 1-based index of the task that failed, otherwise it will return a **0** success result.

## DB Migration App Task

For a more complete example we'll look at how [code-first DB Migrations](/ormlite/db-migrations) uses App Tasks to run DB Migrations from the command-line.

### Running migrations from command-line

To be able to run from migrations from the command line, DB Migrations needs access to your App's DB configuration. The best way to do this is to run your App normally then access the configured `IDbConnectionFactory` from the IOC, perform the migrations then exit with either a success or failure error code.

To do this we've added support for **AppTasks** which let you define tasks in your App that you can run from the command-line. This will let you perform migrations in a separate stage to check migrations were successful before running your App.

### Configuring existing Projects

You can add DB Migration support to existing projects by applying the [migrations](https://gist.github.com/gistlyn/50df00df4b3b9faa94a73d32ab4b2484) gist to your project with:

:::sh
x mix migrations
:::

This will register the Migration **AppTasks** with your App via a [Modular Startup](/modular-startup) configuration:

```csharp
public class ConfigureDbMigrations : IHostingStartup
{
    public void Configure(IWebHostBuilder builder) => builder
        .ConfigureAppHost(afterAppHostInit:appHost => {
            var migrator = new Migrator(appHost.Resolve<IDbConnectionFactory>(), typeof(Migration1000).Assembly);
            AppTasks.Register("migrate", _ => migrator.Run());
            AppTasks.Register("migrate.revert", args => migrator.Revert(args[0]));
            AppTasks.Run();
        });
}
```

Here we can see we need to configure our `Migrator` with the `IDbConnectionFactory` we want to run against and the assemblies where all our Migration classes are maintained. It also registers an AppTasks to **migrate** our App by comparing the **Migration** table with the Migrations in the specified Assembly to workout which Migrations are left to run (in order) and the **revert** AppTask to do the opposite and revert to the specified migration.

This will now let us run your app in **"Task Mode"** where it will execute the specified task before promptly exiting with a **0** success exit code if successful or the index of the task that failed, e.g. **1** if the first Task failed. 

### dotnet Migration Tasks

We can then execute our App Task by running our App with the `AppTasks` command-line argument of the Task we want to run, so we can run all pending migrations with:

:::sh
dotnet run --AppTasks=migrate
:::

The format to revert a migration is:

```bash
$ dotnet run --AppTasks=migrate.revert:<name>
```

Where **name** is either the class name of the Migration you want to revert to (inclusive) or you can use **last** to revert the last migration:

:::sh
dotnet run --AppTasks=migrate.revert:last
:::

or **all** to revert all migrations:

:::sh
dotnet run --AppTasks=migrate.revert:all
:::

### npm Migration Scripts

To make this easier to remember and use, these tasks are also added as npm scripts:

```json
{
  "scripts": {
    "migrate": "dotnet run --AppTasks=migrate",
    "revert:last": "dotnet run --AppTasks=migrate.revert:last",
    "revert:all": "dotnet run --AppTasks=migrate.revert:all",
    "rerun:last": "npm run revert:last && npm run migrate"
  }
}
```

Which can be run with:

```bash
$ npm run migrate
$ npm run revert:last
$ npm run revert:all
$ npm run rerun:last
```

Which Rider provides a nice UX for running directly from the IDE where it will print all executed SQL output in a dedicated Console:

![](/img/pages/ormlite/migration-scripts.png)

### ASP .NET Core Projects

General (i.e. non-ServiceStack) ASP.NET Core Apps can instead configure AppTasks before `app.Run()` in their **Program.cs**:

```csharp
var migrator = new Migrator(app.Services.Resolve<IDbConnectionFactory>(), typeof(Migrations.Migration1000).Assembly);
AppTasks.Register("migrate", _ => migrator.Run());
AppTasks.Register("migrate.revert", args => migrator.Revert(args[0]));
AppTasks.Run();

app.Run();
```


# ASP.NET MVC Integration
Source: https://docs.servicestack.net/mvc-integration

:::tip
These docs only apply to ASP .NET Framework MVC projects, for [.NET Core](/netcore) see [MVC Project Templates](/templates/mvc)
:::

### Add ServiceStack to an existing MVC Project

You can easily add ServiceStack to any ASP.NET MVC project by getting it from NuGet with:

:::copy
`<PackageReference Include="ServiceStack.Mvc" Version="8.*" />`
:::

This install ServiceStack with additional (and optional) integration support for MVC letting you use ServiceStack's IOC to initialize MVC controllers or create MVC Controllers with built-in access to ServiceStack's components.

### Enabling ServiceStack in Web.Config

Typically when hosting ServiceStack with MVC you'd want to host it at the `/api` custom route which you can do by adding the IIS7+ configuration below to your **Web.config**:

```xml
<location path="api">
  <system.web>
    <httpHandlers>
      <add path="*" type="ServiceStack.HttpHandlerFactory, ServiceStack" 
           verb="*"/>
    </httpHandlers>
  </system.web>

  <system.webServer>
    <modules runAllManagedModulesForAllRequests="true"/>
    <validation validateIntegratedModeConfiguration="false" />
    <handlers>
      <add path="*" name="ServiceStack.Factory" 
           type="ServiceStack.HttpHandlerFactory, ServiceStack" verb="*" 
           preCondition="integratedMode" 
           resourceType="Unspecified" allowPathInfo="true" />
    </handlers>
  </system.webServer>
</location>
```

::: info
See [Run Side-by-Side with another web framework](/servicestack-side-by-side-with-another-web-framework) for other web.config examples of hosting ServiceStack, e.g with IIS6/Mono
:::

### Add your ServiceStack AppHost

The smallest ServiceStack AppHost for MVC would look something like:

```csharp
public class AppHost : AppHostBase
{
    public AppHost() : base("MVC", typeof(MyServices).Assembly) {}

    public override void Configure(Container container)
    {            
        SetConfig(new HostConfig { 
            HandlerFactoryPath = "api" 
        });

        ControllerBuilder.Current.SetControllerFactory(
            new FunqControllerFactory(container));
    }
}

[Route("/hello/{Name}")]
public class Hello
{
    public string Name { get; set; }
}

public class MyServices : Service
{
    public object Any(Hello request)
    {
        return request;
    }
}
```

### Inferring ServiceStack's HandlerFactoryPath (/api)

Whilst ServiceStack automatically tries to infer the handler path based on the `<location>` tag, if there's an uncommon Web.config setup or there are some other issue inferring it, it' recommended to also explicitly set the `/api` handler path in `Config.HandlerFactoryPath`, e.g:

```csharp
SetConfig(new HostConfig { 
    HandlerFactoryPath = "api",
});
```

### Initializing ServiceStack

Hosting in ASP.NET MVC is very similar to hosting in any ASP.NET framework, i.e. The ServiceStack AppHost still needs to be initialized on start up in your `Global.asax.cs` (or WebActivator), e.g:

```csharp
public class Global : System.Web.HttpApplication
{
    protected void Application_Start(object sender, EventArgs e)
    {
        new AppHost().Init();
    }
}
```

You *MUST* also register ServiceStacks `/api` path by adding the lines below to MvcApplication.RegisterRoutes(RouteCollection) in the **Global.asax**:

```csharp
routes.IgnoreRoute("api/{*pathInfo}"); 
routes.IgnoreRoute("{*favicon}", new { favicon = @"(.*/)?favicon.ico(/.*)?" }); 
```

Place them before the current entries the method.

### Removing Web API

For MVC applications that include WebApi, you would need to unregister it by commenting out this line:

```csharp
//WebApiConfig.Register(GlobalConfiguration.Configuration);
```

## Optional Configuration

### Sharing dependencies with MVC Controllers

To register all your dependencies in your ServiceStack AppHost, register an MVC Controller factory so both your MVC Controllers and ServiceStack services get auto-wired with these dependencies in your `AppHost.Configure()`, e.g:

```csharp
void Configure(Funq.Container container) 
{
    //Set MVC to use the same Funq IOC as ServiceStack
    ControllerBuilder.Current.SetControllerFactory(
        new FunqControllerFactory(container));
}
```

## Calling ServiceStack Services from MVC Controllers


### Using the Service Gateway

The preferred method for calling ServiceStack Services is via the loosely-coupled [Service Gateway](/service-gateway):

```csharp
public HelloController : ServiceStackController 
{
    public void Index(string name) 
    {
        ViewBag.GreetResult = base.Gateway.Send(new Hello { Name = name }).Result;
        return View();
    }        
}
```

### Calling Services Directly

Alternatively just like in ServiceStack, you can retrieve an autowired Service and execute it directly using `base.ResolveService<TService>()`, e.g:

```csharp
public HelloController : ServiceStackController 
{
    public void Index(string name) 
    {
        using (var service = base.ResolveService<HelloService>())
        {
           ViewBag.GreetResult = service.Any(new Hello { Name = name }).Result;
           return View();
        }
    }        
}
```

For any other external methods or MVC Controllers that don't inherit `ServiceStackController` you can execute Services with:

```csharp
//Using Gateway
var gateway = HostContext.AppHost.GetServiceGateway(base.HttpContext.ToRequest());
ViewBag.GreetResult = gateway.Send(new Hello { Name = name }).Result;

//Calling Service Directly
using (var service = HostContext.ResolveService<HelloService>(base.HttpContext.ToRequest()))
{
    ViewBag.GreetResult = service.Any(new Hello { Name = name }).Result;
}
```

Another cleaner way to share functionality between MVC and ServiceStack is to get them both injected with a shared dependency. See the [IGreeter example on StackOverflow](http://stackoverflow.com/a/10572977).

### Adding Mini Profiler

To enable the Mini Profiler add the following lines in to MvcApplication in **Global.asax.cs**:

```csharp
protected void Application_BeginRequest(object src, EventArgs e)
{
    if (Request.IsLocal)
        ServiceStack.MiniProfiler.Profiler.Start();
}

protected void Application_EndRequest(object src, EventArgs e)
{
    ServiceStack.MiniProfiler.Profiler.Stop();
}
```

For more info on the MiniProfiler see the [Built in profiling](/built-in-profiling) docs.

## [Accessing ServiceStack from MVC](/servicestack-integration)

Once you have MVC + ServiceStack up and running checkout [ServiceStack Integration](/servicestack-integration) docs to explore different ways of accessing ServiceStack from MVC.

  [1]: https://github.com/ServiceStack/ServiceStack/blob/master/NuGet/ServiceStack.Host.Mvc/content/README.txt
  [2]: https://nuget.org/packages/ServiceStack.Host.Mvc/
  [3]: https://github.com/ServiceStack/ServiceStack/blob/master/NuGet/ServiceStack.Host.Mvc/content/README.txt#L10
  [4]: http://tech.pro/tutorial/1148/your-first-rest-service-with-servicestack
  [5]: https://github.com/ServiceStack/ServiceStack/wiki
  [6]: http://aspnetwebstack.codeplex.com/workitem/935


# ServiceStack Integration
Source: https://docs.servicestack.net/servicestack-integration

This article explains how to make use of ServiceStack components in existing **ASP.NET MVC** and **WebForms** Web Applications. The base `ServiceStackController` and WebForms `ServiceStackPage` both share a common code-base  to provide easy access to the same clean, high-performance components found in ServiceStack's `Service` base class, directly from within your MVC Controllers and WebForm pages.

This is an outline of the API's found in MVC's `ServiceStackController` and WebForms `ServiceStackPage`:

```csharp
public class ServiceStackController : Controller
{
    //...
    IServiceStackProvider ServiceStackProvider { get; set; }
    IAppSettings AppSettings { get; set; }
    IHttpRequest ServiceStackRequest { get; set; }
    IHttpResponse ServiceStackResponse { get; set; }
    ICacheClient Cache { get; set; }
    IDbConnection Db { get; set; }
    IRedisClient Redis { get; set; }
    IMessageFactory MessageFactory { get; set; }
    IMessageProducer MessageProducer { get; set; }
    ISessionFactory SessionFactory { get; set; }
    ISession SessionBag { get; set; }
    bool IsAuthenticated { get; set; }

    T TryResolve<T>();
    T ResolveService<T>();
    object Execute(object requestDto);
    object ForwardRequestToServiceStack(IRequest request=null);
    IAuthSession GetSession(bool reload = true);
    TUserSession SessionAs<TUserSession>();
    void ClearSession();
    void PublishMessage<T>(T message);
}
```

## Use ServiceStack Authentication

One benefit of integration with ServiceStack is to be able to make use of ServiceStack's simple and flexible [Authentication Providers](/auth/authentication-and-authorization) which require minimal configuration and supports a number of different [Session Providers](/caching) and persistent [Data Store back-ends](/auth/authentication-and-authorization#userauth-persistence---the-iuserauthrepository) to make it easy to integrate with an existing environment.

### MVC and WebForms Examples

To illustrate the seamless integration with ServiceStack, we've created 2 new authentication-enabled example websites:

 - **ASP.NET MVC** Live Demo: [mvc.servicestack.net](http://mvc.servicestack.net/) and [source code](https://github.com/ServiceStack/Test/tree/master/src/Mvc)
 - **ASP.NET WebForms** Live Demo: [webforms.servicestack.net](http://webforms.servicestack.net/) and [source code](https://github.com/ServiceStack/Test/tree/master/src/WebForms)

![MVC with ServiceStack Authentication](https://raw.githubusercontent.com/ServiceStack/Assets/master/img/release-notes/mvc-integration.png)

### Integrating with ServiceStack from MVC or WebForms

We'll go through the MVC example to showcase the different ways you can integrate with ServiceStack from an external Web Framework. 

#### Using ResolveService to call Services directly

The `Login` Action is a standard MVC Action handling HTML Form input accepting 3 parameters, a `userName`, `password` as well as a relative `redirect` url to redirect to when authentication is successful. Login uses the `ResolveService<TService>` API which just resolves an auto-wired instance of the ServiceStack `AuthenticateService` from the IOC and injects the current HTTP Request context, which we then use to call a method on the Service directly:

```csharp
public ActionResult Login(string userName, string password, string redirect=null)
{
    if (ModelState.IsValid)
    {
        try
        {
            using (var authService = ResolveService<AuthenticateService>())
            {
                var response = authService.Authenticate(new Authenticate {
                    provider = CredentialsAuthProvider.Name,
                    UserName = userName,
                    Password = password,
                    RememberMe = true,
                });

                // add ASP.NET auth cookie
                FormsAuthentication.SetAuthCookie(userName, true);

                return Redirect(string.IsNullOrEmpty(redirect) ? "/" : redirect);
            }
        }
        catch (Exception ex)
        {
            ModelState.AddModelError(string.Empty, ex.Message);
        }
    }

    return View("Index", GetViewModel());
}
```

::: info
Since the above example calls the Service method directly any exceptions raised by the Service implementation are thrown and caught as normal
:::

#### Using Execute to process Request DTO's

The `Logout()` MVC Action uses ServiceStack's `Execute()` API which can call the desired ServiceStack Service with just a populated Request DTO:

```csharp
public ActionResult Logout()
{
    Execute(new Authenticate { provider = "logout" });
    FormsAuthentication.SignOut(); 

    return Redirect("/");
}
```

#### Using ForwardRequestToServiceStack to proxy HTTP Requests

The `ForwardingController` handles OAuth callbacks that have been configured to callback to `/auth/*` route which is handled by MVC as ServiceStack is mounted at and only configured to handle `/api` requests. 

Instead of creating new OAuth Applications with each provider to use the new `/api/auth/*` callback url so ServiceStack can handle the OAuth callback, we can use just use the new `ForwardRequestToServiceStack()` which just forwards the incoming HTTP Request from MVC to ServiceStack to process, effectively acting as a proxy:

```csharp
routes.MapRoute("Forwarding", "auth/{*pathinfo}", 
    new { controller = "Forwarding", action = "Index" });
...

public class ForwardingController : ServiceStackController
{
    public ActionResult Index()
    {
        var response = ForwardRequestToServiceStack();
        if (ServiceStackResponse.IsClosed) return new EmptyResult();

        string redirectUrl;
        var httpResult = response as IHttpResult;
        if (httpResult != null && httpResult.Headers.TryGetValue(HttpHeaders.Location, out redirectUrl))
            return Redirect(redirectUrl);

        return Redirect("/");
    }
}
```

The `Execute()` and `ForwardRequestToServiceStack()` are high-level API's that call into ServiceStack's internal Request pipeline, executing any Action Filters and also converts any exceptions into a populated serializable Response DTO with a populated `ResponseStatus` as would be returned to Service Clients.

### Authentication Attributes

Since we're using ServiceStack for Authentication, we're also able to re-use ServiceStack's Authentication Attribute Filters directly on MVC Controllers and WebForm Pages just as if they were ServiceStack Services, e.g:

```csharp
[Authenticate]
public class AuthOnlyController : ServiceStackController 
{
    public ActionResult Index()
    {
        return View(SessionAs<CustomUserSession>());
    }         
}
```

The above controller hanldes the [mvc.servicestack.net/AuthOnly](http://mvc.servicestack.net/AuthOnly) route which only allows access to Authorized users. If a user is not authenticated they're automatically redirected to [/?redirect=/AuthOnly#f=Unauthorized](http://mvc.servicestack.net/?redirect=%2fAuthOnly#f=Unauthorized) to prompt the user to login, after successfully logging in it will redirect back to the original `/AuthOnly` url.

### Required Role or Permission

The `[RequiredRole]` and `[RequiredPermission]` attributes work similar to the `[Authentication]` attribute except they also assert that the user is a member of the specified role:

```csharp
[RequiredRole("TheRole")]
public class RequiresRoleController : ServiceStackController 
{
    public ActionResult Index()
    {
        return View(SessionAs<CustomUserSession>());
    }
}
```

The above Controller handles the [/RequiresRole](http://mvc.servicestack.net/RequiresRole) Route and will only grant access if the Authenticated User is also a member of the **TheRole**.

### Calling ServiceStack Services Directly

The simplest way to consume ServiceStack Services requiring the least effort and moving parts is to call them directly: 

#### Using ServiceStack OAuth in MVC

Integrating with ServiceStack's OAuth providers requires the least effort as they're linkable directly in the format `/api/auth/{provider}` which is handled by ServiceStack's OAuth Service who initiates the Authentication process by redirecting to the selected OAuth provider:

![MVC OAuth with HTML](https://raw.githubusercontent.com/ServiceStack/Assets/master/img/release-notes/mvc-auth.png)

#### Calling ServiceStack with Ajax in MVC

Posting HTML Forms directly to ServiceStack Services isn't that much more effort, Start with a plain HTML Form with field names that match with the Services property names:

![MVC Register with HTML](https://raw.githubusercontent.com/ServiceStack/Assets/master/img/release-notes/mvc-register.png)

We can then use ServiceStack's built-in [ss-utils.js JavaScript Libraray](/ss-utils-js) to take care of Ajaxifying, auto-binding and submitting the form via Ajax. It also has built-in support for [Bootstrap Forms Field Validation conventions](/ss-utils-js#bootstrap-forms) to automatically bind errors to the appropriate fields. The only custom code required is to bind the form is then:

```javascript
$("#form-register").bindForm({
    success: function (r) { location.href = '/'; }
});
```

In this case we've added a success callback to redirect to the home page if the registration was successful which will either be authenticated with the newly registered user if **Auto Login** was checked, otherwise you can use the login form to Sign in as the newly registered user.


# Run side-by-side with another Framework
Source: https://docs.servicestack.net/servicestack-side-by-side-with-another-web-framework

:::tip
These docs only apply to ASP .NET Framework MVC projects, for [.NET Core](/netcore) see [MVC Project Templates](/templates/mvc)
:::

In order to avoid conflicts with your existing ASP.NET web framework it is recommended to host your ServiceStack web services at a custom path.
This will allow you to use ServiceStack together with an existing web framework e.g. ASP.NET MVC 3 or FUBU MVC, etc.

The location configuration (to your root Web.config file) below hosts your webservices at custom path: `/api`

```xml
<configuration>
  <!-- ... --> 
  <location path="api">
    <system.web>
      <httpHandlers>
        <add path="*" type="ServiceStack.HttpHandlerFactory, ServiceStack" verb="*"/>
      </httpHandlers>
    </system.web>

    <!-- Required for IIS 7.0 -->
    <system.webServer>
      <modules runAllManagedModulesForAllRequests="true"/>
      <validation validateIntegratedModeConfiguration="false" />
      <handlers>
        <add path="*" name="ServiceStack.Factory" 
             type="ServiceStack.HttpHandlerFactory, ServiceStack" 
             verb="*" preCondition="integratedMode" 
             resourceType="Unspecified" allowPathInfo="true" />
      </handlers>
    </system.webServer>
  </location>
  <!-- ... --> 
</configuration>
```

Configuration for also running on Mono / IIS 6:

```xml
<!-- Required for MONO -->
<configuration>
  <!-- ... --> 
  <system.web>
    <httpHandlers>
      <add path="api*" type="ServiceStack.HttpHandlerFactory, ServiceStack" verb="*"/>
    </httpHandlers>
  </system.web>
  <system.webServer>
    <validation validateIntegratedModeConfiguration="false" />
  </system.webServer>
  <!-- ... --> 
</configuration>
```

::: info
Due to limitations in IIS 6 - the `/custompath` must end with `.ashx`, e.g: `path="api.ashx"`
:::

You also need to configure the root path in your AppHost.

```csharp
public override void Configure(Container container)
{
    SetConfig(new HostConfig { HandlerFactoryPath = "api" });
}
```

**To avoid conflicts with ASP.NET MVC add an ignore rule** in `Global.asax RegisterRoutes` method e.g: 

```csharp
routes.IgnoreRoute ("api/{*pathInfo}");
```

See [mvc-netfx](https://github.com/NetFrameworkTemplates/mvc-netfx) for a working ServiceStack + MVC Project Template.

**For MVC4 applications you also need to unregister WebApi**, by commenting out this line in `Global.asax.cs`:

```csharp
//WebApiConfig.Register(GlobalConfiguration.Configuration);
```

If you used Nuget to install the bits, remove the original handler from the web.config system.webserver node e.g: 

```xml
<add path="*" name="ServiceStack.Factory"
    type="ServiceStack.HttpHandlerFactory, ServiceStack" verb="*" 
    preCondition="integratedMode" resourceType="Unspecified" allowPathInfo="true" />
```

## Enable ASP.NET Sessions

If you want ServiceStack Services to be able to access ASP.NET Session you can use a decorated `IHttpHandlerFactory` below
that returns a `SessionHandlerDecorator` that's decorated with `IRequiresSessionState` to tell ASP.NET to enable Sessions for these handlers:

```csharp
namespace MyApp
{
    public class SessionHttpHandlerFactory : IHttpHandlerFactory
    {
        private static readonly HttpHandlerFactory Factory = new HttpHandlerFactory();

        public IHttpHandler GetHandler(HttpContext context, string requestType, string url, string path)
        {
            var handler = Factory.GetHandler(context, requestType, url, path);
            return handler == null ? null : new SessionHandlerDecorator((IHttpAsyncHandler)handler);
        }

        public void ReleaseHandler(IHttpHandler handler) => Factory.ReleaseHandler(handler);
    }

    public class SessionHandlerDecorator : IHttpAsyncHandler, IRequiresSessionState
    {
        private IHttpAsyncHandler Handler { get; set; }

        internal SessionHandlerDecorator(IHttpAsyncHandler handler) => Handler = handler;

        public bool IsReusable => Handler.IsReusable;

        public void ProcessRequest(HttpContext context) => Handler.ProcessRequest(context);

        public IAsyncResult BeginProcessRequest(HttpContext context, AsyncCallback cb, object extraData) => 
          Handler.BeginProcessRequest(context, cb, extraData);

        public void EndProcessRequest(IAsyncResult result) => Handler.EndProcessRequest(result);
    }
}
```

Then replace the existing `ServiceStack.HttpHandlerFactory` registration with your decorated implementation above, e.g:

```xml
<system.web>
  <httpHandlers>
    <add path="*" type="MyApp.SessionHttpHandlerFactory, MyApp" verb="*"/>
  </httpHandlers>
</system.web>
```

### Resources

* [Example config files for Starter Templates](https://github.com/ServiceStackApps/LiveDemos#starter-templates)


# Versioning
Source: https://docs.servicestack.net/versioning

## Implicit Versioning

You can populate Version numbers in all Request DTO's implementing `IHasVersion`, i.e:

```csharp
public class Hello : IReturn<HelloResponse>, IHasVersion 
{
    public int Version { get; set; }
    public string Name { get; set; }
}
```

By assigning the `Version` property on the Service Clients, e.g:

```csharp
client.Version = 2;
```

Which will auto populate each Request DTO that implements `IHasVersion`, e.g:

```csharp
client.Get(new Hello { Name = "World" });  // Hello.Version=2
```

### Version Abbreviation Convention

A popular convention for specifying versions in API requests is with the `?v=1` QueryString which ServiceStack now uses as a fallback for populating any Request DTO's that implement `IHasVersion` (as above).

::: info
as ServiceStack's message-based design promotes forward and backwards-compatible Service API designs, our recommendation is to only consider implementing versioning when necessary, at which point check out our [recommended versioning strategy](http://stackoverflow.com/a/12413091/85785)
:::


# Config API
Source: https://docs.servicestack.net/config-api

Despite being avid protesters in the anti-XML config movement, we're still 100% for app Config in general though it should be **limited to what's actually configurable by your application**. Instead of building tiered configSection manatees we prefer to store structured data in Web.config's appSetting's values which are still able to express rich object config graphs but does so in a much more human-friendly and manageable size.

## ServiceStack's Configuration API

To this end we provide our own pluggable [Configuration API](https://github.com/ServiceStack/ServiceStack/blob/master/src/ServiceStack.Interfaces/Configuration/IResourceManager.cs) to provide high-level utility methods to read your Web.config's `<appSetting/>` values into a `List`, `Dictionary` or your own Custom POCO Type using the human friendly [JSV format](/jsv-format).

### Benefits over XML Config

Benefits over existing XML Configuration APIs include: 

  - The ability to store rich data structures in **appSettings** values
  - Much easier and requires less effort and boilerplate to create 
  - Provides more succinct access to typed data
  - Since they're just POCOs can be re-used in all of ServiceStack's libraries and built-in [Auto Mapping](/auto-mapping)

and promotes less-coupling since its only an [interface](https://github.com/ServiceStack/ServiceStack/blob/master/src/ServiceStack.Interfaces/Configuration/IResourceManager.cs) so can easily be swapped to have [Plugins](/plugins) source their complex configuration from an different source (e.g. from a central DB) without a rewrite. 

[OpenId](/auth/openid) providers like the [FacebookAuthProvider](https://github.com/ServiceStack/ServiceStack/blob/master/src/ServiceStack.ServiceInterface/Auth/FacebookAuthProvider.cs#L23) is an example of Plugins that require multiple configuration settings but remain de-coupled from any one configuration source (e.g. Web.config).

### Example AppSettings Usage

By default ServiceStack ships with an [AppSettings](https://github.com/ServiceStack/ServiceStack/blob/master/src/ServiceStack/Configuration/AppSettings.cs) which reads from your Web.Config `<appSettings/>` and a [DictionarySettings](https://github.com/ServiceStack/ServiceStack/blob/master/src/ServiceStack/Configuration/DictionarySettings.cs) provider which can be populated with a standard C# `Dictionary<string,string>`.

Here's a quick example show-casing how to use the popular **AppSettings*:

```xml
<appSettings>
    <add key="LastUpdated" value="01/01/2012 12:00:00" />
    <add key="AllowedUsers" value="Tom,Mick,Harry" />
    <add key="RedisConfig" value="{Host:localhost,Port:6379,Database:1,Timeout:10000}" />
</appSettings>
```

Accessing the above appSettings in C#:

```csharp
var appSettings = new AppSettings();

DateTime lastUpdate = appSettings.Get<DateTime>("LastUpdated");
IList<string> allowedUsers = appSettings.GetList("AllowedUsers");

var redisConf = appSettings.Get<RedisConfig>("RedisConf");

//use default value if no config exists
var searchUrl = appSettings.Get("SearchUrl", "http://www.google.com");
```

### Default configuration in code

The default value support is nice as it allows having workable default options in code whilst still remaining overridable in the **Web.config** when it needs to. This allows local and test projects to work without duplicating and maintaining and their own Web.config files whilst allowing arbitrary settings to be overridable in different deployment environments.

It also allows distributing Stand-alone Console applications like the [PocoPower demo](https://github.com/ServiceStack/ServiceStack.UseCases/blob/master/PocoPower/Program.cs) but still provide the opportunity to override the settings without recompiling the source, e.g:

```csharp
var appSettings = new AppSettings();
var config = appSettings.Get("my.config", 
    new Config { GitHubName = "mythz", TwitterName = "ServiceStack" });

var github = new GithubGateway();
var repos = github.GetAllUserAndOrgsReposFor(config.GitHubName);

var twitter = new TwitterGateway();
var tweets = twitter.GetTimeline(config.TwitterName);
```

## Easy to implement

Despite being so versatile, it's surprisingly easy to implement a new Configuration Provider, e.g. Here's the entire implementation for [DictionarySettings](https://github.com/ServiceStack/ServiceStack/blob/master/src/ServiceStack/Configuration/DictionarySettings.cs) which just needs to implement [ISettings](https://github.com/ServiceStack/ServiceStack/blob/master/src/ServiceStack/Configuration/ISettings.cs) as is able to re-use the built-in `AppSettingsBase` base class:

```csharp
public class DictionarySettings : AppSettingsBase, ISettings
{
    private readonly Dictionary<string, string> map;

    public DictionarySettings(Dictionary<string, string> map=null)
    {
        this.map = map ?? new Dictionary<string, string>();
        settings = this;
    }

    public string Get(string key)
    {
        string value;
        return map.TryGetValue(key, out value) ? value : null;
    }
}
```


# Concurrency Model
Source: https://docs.servicestack.net/concurrency-model

ServiceStack doesn't have a configurable concurrency model per AppHost, it is dependent upon the AppHost that your ServiceStack services are hosted with:

## ASP.NET Host (AppHostBase)

For ASP.NET web hosts, ServiceStack **doesn't create any new threads** itself, the requests are simply handled on the same IIS/Nginx/etc ASP.NET HTTP WebWorker that handles the request.

## HttpListener Self-Host (AppSelfHostBase) 

The default Self-Host HttpListener option for ServiceStack that executes requests on the [SmartThreadPool](http://www.codeproject.com/Articles/7933/Smart-Thread-Pool) managed ThreadPool. By default it executes on `Environment.ProcessorCount * 2` or maximum of 16 worker threads. See this chart for the [performance of the different ServiceStack Hosts](https://github.com/ServiceStack/ServiceStack/blob/master/release-notes.md#new-much-faster-self-host).

## HttpListener Pool Self-Host (AppHostHttpListenerPoolBase)

This is another Self-Host HttpListener option for ServiceStack that uses its own managed ThreadPool to execute requests on (free-ing up the HttpListener async callback thread). The default poolSize of the ThreadPool is **500** threads, though this is configurable in the `AppHostHttpListenerPoolBase(serviceName, handlerPath, poolSize, assembliesWithServices)` constructor.

## HttpListener Single Self-Host (AppHostHttpListenerBase)

ServiceStack only creates a new thread on **Startup** when you call `new AppHost().Start(url)`. There are no new threads created at run-time, i.e. the request is handled on the HttpListener async callback thread.

## RedisMQ Host (RedisMqServer)

A good option for managing long-running tasks is to delegate requests to a [Redis MQ Host](/redis-mq) which is a light-weight MQ Server allowing you to defer and process requests in managed background threads. By default the RedisMqServer spawns a single background thread for each Message type (i.e. Request), though this is configurable on start-up, e.g: in the example below **2 background threads** are used to handle `PostTwitter` requests, whilst only 1 background thread each is used to process `CallFacebook` and `EmailMessage` requests:

```csharp
mqServer.RegisterHandler<PostTwitter>(ServiceController.ExecuteMessage, noOfThreads:2);
mqServer.RegisterHandler<CallFacebook>(ServiceController.ExecuteMessage);
mqServer.RegisterHandler<EmailMessage>(ServiceController.ExecuteMessage);
```


# Form Hijacking Prevention
Source: https://docs.servicestack.net/form-hijacking-prevention

The `SuppressFormsAuthenticationRedirectModule` module prevents the asp.net built in `FormsAuthenticationModule` from hijacking 401 requests and redirecting to a login page.  Normally, this is the desired behavior if you are using a web browser and access an unauthorized page, but in the case of an API, we do not want that.

This module uses a hack to get this done.  It temporarily replaces the 401 error with a 402 to trick the `FormsAuthenticationModule` and then puts the 401 back before the request is finished.   It only does this on the path for your API, the rest of the website will behave as normal.   Note, that there is a non-hack way to do this now, built into .net 4.5 and I have commented the code as to what that is.  When appropriate a .net 4.5 package could be released containing this updated code.

## Usage

To use this, first register the `httpModule`:

```xml
<system.web>
    <httpModules>
      <add name="FormsAuthenticationDisposition" type="ServiceStack.SuppressFormsAuthenticationRedirectModule, ServiceStack" />
    </httpModules>
</system.web>

<!-- Required for IIS 7.0 (and above?) -->
<system.webServer>
  <validation validateIntegratedModeConfiguration="false" />
    <httpModules>
      <add name="FormsAuthenticationDisposition" type="ServiceStack.SuppressFormsAuthenticationRedirectModule, ServiceStack" />
    </httpModules>
</system.webServer>
```

next, configure the module with where your API lives - defaults to `/api`, so in your AppHost Configure:

```csharp
public override void Configure(Funq.Container container)
{
    SetConfig(new HostConfig {
        HandlerFactoryPath = "/yourapipath",
    });

    //this is the configuration for Hijacking prevention
    SuppressFormsAuthenticationRedirectModule.PathToSupress = Config.HandlerFactoryPath;
}
```


# Creating a WebService from scratch
Source: https://docs.servicestack.net/create-webservice-from-scratch

## Step 1: Create an application

ServiceStack can be hosted in a few ways: console application, windows service, ASP.NET Web Form or MVC in IIS, etc.

For this tutorial, an empty ASP.NET Web Application (non MVC) is assumed.

## Step 2: Install ServiceStack

To install ServiceStack into your application, you have two options to get the binaries:

:::copy
`<PackageReference Include="ServiceStack" Version="5.12.0" />`
:::

::: info Tip
You can find an explanation about all NuGet packages which ServiceStack offers [here](/nuget). The package above only adds the binaries, but there also exist some packages which add the required configurations etc
:::

### Register ServiceStack Handler

After you've added the binaries, you need to register ServiceStack in `web.config`:

If you want to host ServiceStack at root path (`/`), you should use this configuration:

```xml
<!-- For IIS 6.0/Mono -->
<system.web>
  <httpHandlers>    
    <add path="*" type="ServiceStack.HttpHandlerFactory, ServiceStack" verb="*"/>
  </httpHandlers>
</system.web>

<!-- For IIS 7.0+ -->
<system.webServer>
  <validation validateIntegratedModeConfiguration="false" />
  <handlers>
    <add path="*" name="ServiceStack.Factory" preCondition="integratedMode" 
         type="ServiceStack.HttpHandlerFactory, ServiceStack" 
         verb="*" resourceType="Unspecified" allowPathInfo="true" />
  </handlers>
</system.webServer>
```

::: info Tip
If you want to host your webservice on a custom path to avoid conflicts with another web framework (eg ASP.Net MVC), see [Run ServiceStack side-by-side with another web framework](/servicestack-side-by-side-with-another-web-framework)
:::

::: warning
Due to limitations in IIS 6 - host [ServiceStack at a /custompath](/mvc-integration#enabling-servicestack-in-webconfig) which must end with `.ashx`, e.g: `path="api.ashx"`
:::

## Step 3: Create your first webservice

If  `Global.asax.cs` doesn't already exist you have to add it manually. To do this **Right-click** on your project and go 
**Add -> New Item**, then select the **Global Application** class.

Each service in ServiceStack consists of three parts:

- Request DTO
- Service implementation
- Response DTO

That's the core philosophy in ServiceStack. Each service has a strongly-typed, code-first (normal POCOs) Request DTO and response DTO. You can read a detailed explanation what advantages exist if you're using DTOs in the [ReadMe](https://github.com/ServiceStack/ServiceStack/blob/master/README.md) or in [Why should I use ServiceStack?] (/why-servicestack).

1) Create the name of your Web Service (i.e. the Request DTO)

```csharp
[Route("/hello")]
[Route("/hello/{Name}")]
public class Hello
{
    public string Name { get; set; }
}
```

2) Define what your Web Service will return (i.e. Response DTO)

```csharp
public class HelloResponse
{
    public string Result { get; set; }
}
```

3) Create your Web Service implementation

```csharp
public class HelloService : Service
{
    public object Any(Hello request)
    {
        return new HelloResponse { Result = "Hello, " + request.Name };
    }
} 
```

## Step 4: Registering your web services and starting your application

The final step is to configure setup to tell ServiceStack where to find your web services. To do that, add this code to your `Global.asax.cs`:

```csharp
public class Global : System.Web.HttpApplication
{
    public class AppHost : AppHostBase
    {
        //Tell ServiceStack the name of your application and where to find your services
        public AppHost() : base("Hello Web Services", typeof(HelloService).Assembly) { }

        public override void Configure(Funq.Container container)
        {
            //register any dependencies your services use, e.g:
            //container.Register<ICacheClient>(new MemoryCacheClient());
        }
    }

    //Initialize your application singleton
    protected void Application_Start(object sender, EventArgs e)
    {
        new AppHost().Init();
    }
}
```

Done! You now have a working application :)

As you can see, you have created an `AppHost`. Mainly all configuration related to ServiceStack is made in the `AppHost`. It's the starting point in your application.

#### Disable WebApi from the default MVC4 VS.NET template

If you are using MVC4 then you need to comment line in global.asax.cs to disable WebApi 

```cs
//WebApiConfig.Register(GlobalConfiguration.Configuration);
```

## ServiceStack is now Ready!

Now that you have a working Web Service lets see what ServiceStack does for you out of the box:

If everything is configured correctly you can go to `http://<root_path>/metadata` to see a list of your web services and the various end points its available on.

![Metadata page](https://raw.githubusercontent.com/ServiceStack/Assets/master/img/wikis/metadata-chat.png)

::: info Tip
In the screenshot the root path is `http://localhost/ServiceStack.Hello/servicestack`. On your development box the root path might be something like `http://localhost:60335` (ie the URL on which your webservice is hosted).
:::

Let's access the HelloWorld service you created in your browser, so write the following URL in your address bar:

```
GET http://<root_path>/hello/YourName
```

> E.g. http://example.org/hello/Max
    
As you can see after clicking on this link, ServiceStack also contains a HTML response format, which makes the XML/Json (...) output human-readable. To change the return format to Json, simply add `?format=json` to the end of the URL. You'll learn more about formats, endpoints (URLs, etc) when you continue reading the documentation.

## Troubleshooting
If you happen to generate requests from the wsdls with a tool like soapUI you may end up with an incorrectly generated request like this:

```xml
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" xmlns:typ="http://schemas.servicestack.net/types">
  <soap:Header/>
  <soap:Body>
    <typ:Hello/>
  </soap:Body>
</soap:Envelope>
```

You can resolve this issue by adding the following line to your AssemblyInfo file
```csharp
[assembly: ContractNamespace("http://schemas.servicestack.net/types", 
           ClrNamespace = "<YOUR NAMESPACE>")]
```

Rebuild and regenerate the request from the updated wsdl. You should get a correct request this time.

```xml
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" xmlns:typ="http://schemas.servicestack.net/types">
   <soap:Header/>
   <soap:Body>
      <typ:Hello>
         <!--Optional:-->
         <typ:Name>?</typ:Name>
      </typ:Hello>
   </soap:Body>
</soap:Envelope>
```

## Explore ServiceStack Documented Demo

The [EmailContacts solution](https://github.com/ServiceStackApps/EmailContacts/) is a new guidance available that walks through the recommended setup and physical layout structure of typical medium-sized ServiceStack projects, including complete documentation of how to create the solution from scratch, whilst explaining all the ServiceStack features it makes use of along the way.

# Community Resources

  - [Creating A Simple Service Using ServiceStack](http://shashijeevan.net/2015/09/20/creating-a-simple-service-using-servicestack/) by [Shashi Jeevan](http://shashijeevan.net/author/shashijeevan/)
  - [Introducing ServiceStack](http://www.dotnetcurry.com/showarticle.aspx?ID=1056) by [@dotnetcurry](https://twitter.com/DotNetCurry)
  - [Create web services in .NET in a snap with ServiceStack](http://www.techrepublic.com/article/create-web-services-in-net-in-a-snap-with-servicestack/) by [@techrepublic](https://twitter.com/techrepublic)
  - [How to build web services in MS.Net using ServiceStack](http://kborra.wordpress.com/2014/07/29/how-to-build-web-services-in-ms-net-using-service-stack/) by [@kishoreborra](http://kborra.wordpress.com/about/)
  - [Getting started with ServiceStack – Creating a service](http://dilanperera.wordpress.com/2014/02/22/getting-started-with-servicestack-creating-a-service/)
  - [Fantastic Step-by-step walk-thru into ServiceStack with Screenshots!](http://nilsnaegele.com/codeedge/servicestack.html) by [@nilsnagele](https://twitter.com/nilsnagele)
  - [Your first REST service with ServiceStack](http://tech.pro/tutorial/1148/your-first-rest-service-with-servicestack) by [@cyberzeddk](https://twitter.com/cyberzeddk)
  - [New course: Using ServiceStack to Build APIs](http://blog.pluralsight.com/2012/11/29/new-course-using-servicestack-to-build-apis/) by [@pluralsight](http://twitter.com/pluralsight)
  - [ServiceStack the way I like it](http://tonyonsoftware.blogspot.co.uk/2012/09/lessons-learned-whilst-using.html) by [@tonydenyer](https://twitter.com/tonydenyer)
  - [Generating a RESTful Api and UI from a database with LLBLGen](http://www.mattjcowan.com/funcoding/2013/03/10/rest-api-with-llblgen-and-servicestack/) by [@mattjcowan](https://twitter.com/mattjcowan)
  - [ServiceStack: Reusing DTOs](http://korneliuk.blogspot.com/2012/08/servicestack-reusing-dtos.html) by [@korneliuk](https://twitter.com/korneliuk)
  - [ServiceStack, Rest Service and EasyHttp](http://blogs.lessthandot.com/index.php/WebDev/ServerProgramming/servicestack-restservice-and-easyhttp) by [@chrissie1](https://twitter.com/chrissie1)
  - [Building a Web API in SharePoint 2010 with ServiceStack](http://www.mattjcowan.com/funcoding/2012/05/04/building-a-web-api-in-sharepoint-2010-with-servicestack)
  - [JQueryMobile and ServiceStack: EventsManager tutorial part #3](http://paymentnetworks.wordpress.com/2012/04/24/jquerymobile-and-service-stack-eventsmanager-tutorial-post-3/) by Kyle Hodgson
  - [REST Raiding. ServiceStack](http://dgondotnet.blogspot.de/2012/04/rest-raiding-servicestack.html) by [Daniel Gonzalez](http://www.blogger.com/profile/13468563783321963413)
  - [JQueryMobile and ServiceStack: EventsManager tutorial](http://kylehodgson.com/2012/04/21/jquerymobile-and-service-stack-eventsmanager-tutorial-post-2/) / [Part 3](http://kylehodgson.com/2012/04/23/jquerymobile-and-service-stack-eventsmanager-tutorial-post-3/) by Kyle Hodgson
  - [Like WCF: Only cleaner!](http://kylehodgson.com/2012/04/18/like-wcf-only-cleaner-9/) by Kyle Hodgson
  - [ServiceStack vs WCF Data Services](http://codealoc.wordpress.com/2012/03/24/service-stack-vs-wcf-data-services/)
  - [Building a Tridion WebService with jQuery and ServiceStack](http://www.curlette.com/?p=161) by [@robrtc](https://twitter.com/robrtc)
  - [Anonymous type + Dynamic + ServiceStack == Consuming cloud has never been easier](http://www.ienablemuch.com/2012/05/anonymous-type-dynamic-servicestack.html) by [@ienablemuch](https://twitter.com/ienablemuch)
  - [Handful of examples of using ServiceStack based on the ServiceStack.Hello Tutorial](https://github.com/jfoshee/TryServiceStack) by [@82unpluggd](https://twitter.com/82unpluggd)


# Content Types
Source: https://docs.servicestack.net/formats

ServiceStack supports the following formats:

- [JSON](json-format)
- [XML](https://docs.microsoft.com/en-us/dotnet/api/system.runtime.serialization.datacontractserializer)
- [CSV](/csv-format)
- [JSONL](/jsonl-format)
- [JSV](/jsv-format) (hybrid CSV-style escaping + JSON format that is optimized for both size and speed)
- [SOAP 1.1/1.2](/soap-support) (requires ASP.NET Framework)
- [Message Pack](/messagepack-format)
- [Protocol Buffers](/protobuf-format)
- HTML
    - [#Script Pages](https://sharpscript.net/docs/script-pages) (Simple, clean, fast alternative to Razor)
    - [Razor](https://razor.netcore.io) (Microsoft's Razor View Engine)
    - [Markdown Razor](/markdown-razor) (Razor-inspired syntax combined with markdown)
    - [HTML5 Report](/html5reportformat) (Human-friendly HTML auto-layout to quickly visualize data returned by services)

### .NET Service Clients

The different Content Types can be easily consumed using [ServiceStack's Typed Generic Service Clients](/csharp-client#httpwebrequest-service-clients).

## HTTP API Formats

ServiceStack Services supports a number of [Content Negotiation](/routing#content-negotiation) options where you can define which 
format should be returned by adding a `.{format}` extension to your `/route.{format}`. Built-in Formats include:

 - `.json`
 - `.xml`
 - `.jsv`
 - `.csv`
 - `.html`

Example: [http://web.web-templates.io/hello/World.json](http://web.web-templates.io/hello/World.json)

Or by appending `?format={format}` to the end of the URL:

- `?format=json`
- `?format=xml`
- `?format=jsv`
- `?format=csv`
- `?format=html`

Example: [http://web.web-templates.io/hello/World?format=json](http://web.web-templates.io/hello/World?format=json)

Alternatively ServiceStack also recognizes which format should be used with the `Accept` [http header](http://en.wikipedia.org/wiki/List_of_HTTP_header_fields):

- `Accept: application/json`
- `Accept: application/xml`

## Default Content-Type

The recommended way to request a specific content type is to add it to the Accept HTTP Request Header, e.g:

```
Accept: application/json
```

Alternatively you can specify to use a specific Content-Type as the default Content Type in your AppHost with:

```csharp
SetConfig(new HostConfig {
     DefaultContentType = MimeTypes.Json 
});
```

Sometimes when calling web services from a web browser they'll ask for `Accept: text/html` and not JSON which by contract ServiceStack obliges by returning back HTML if it is enabled.

To ensure JSON is always returned you can disable the HTML support with:

```csharp
SetConfig(new HostConfig {
    EnableFeatures = Feature.All.Remove(Feature.Html),
});
```

## Pre-defined Routes

    /[xml|json|html|jsv|csv]/[reply|oneway]/[servicename]

Examples:

 - /json/reply/Hello (JSON)
 - /xml/oneway/SendEmail (XML)

### Forcing a Content Type

Whilst ServiceStack Services are typically available on any endpoint and format, there are times when you only want adhoc Services available in a particular format, for instance you may only want the View Models for your dynamic Web Views available in HTML. This can now be easily enabled with the new `[HtmlOnly]` Request Filter Attribute, e.g:
    
```csharp
[HtmlOnly]
public class HtmlServices : Service
{
    public object Any(MyRequest request) => new MyViewModel { .. };
}
```

This feature is also available for other built-in Content Types: `[JsonOnly]`, `[XmlOnly]`, `[JsvOnly]` and `[CsvOnly]`.

## Registering a Custom Format

Registering a custom format is done by registering the Format's Content-Type with to your AppHost's `ContentTypes` API, e.g:

```csharp
//Register the 'text/csv' content-type format
//Note: Format is inferred from the last part of the content-type, e.g. 'csv'

public class CsvFormat : IPlugin
{
    public void Register(IAppHost appHost)
    {
        appHost.ContentTypes.Register(MimeTypes.Csv,
            SerializeToStream, 
            CsvSerializer.DeserializeFromStream);

        //ResponseFilter to add 'Content-Disposition' header for browsers to open in Spreadsheet
        appHost.GlobalResponseFilters.Add((req, res, dto) => {
            if (req.ResponseContentType == MimeTypes.Csv) {
                var fileName = req.OperationName + ".csv";
                res.AddHeader(HttpHeaders.ContentDisposition, 
                    $"attachment;{HttpExt.GetDispositionFileName(fileName)}");
            }
        });
    }

    void SerializeToStream(IRequest req, object request, Stream stream) =>
        CsvSerializer.SerializeToStream(request, stream);
}
```

We recommend encapsulating Custom Formats registrations into a [Plugin](/plugins) as done with the built-in 
[CsvFormat](https://github.com/ServiceStack/ServiceStack/blob/master/src/ServiceStack/Formats/CsvFormat.cs) which is added by default:

```csharp
Plugins.Add(new CsvFormat()); //added by default
```

Which makes it easy to register, detect and remove. E.g. to remove built-in support for CSV you can just remove it from the `Plugins` collection:

```csharp
Plugins.RemoveAll(x => x is CsvFormat);
```

### XmlSerializerFormat Plugin

The `XmlSerializerFormat` plugin changes ServiceStack to serialize XML with .NET `XmlSerializer` instead of .NET XML 
`DataContractSerializer`:

```csharp
Plugins.Add(new XmlSerializerFormat());
```

The implementation provides a typical example of how to register or override different Content-Types in ServiceStack:

```csharp
public class XmlSerializerFormat : IPlugin
{
    public static void Serialize(IRequest req, object response, Stream stream)
    {
        var serializer = new XmlSerializer(response.GetType());
        serializer.Serialize(stream, response);
    }

    public static object Deserialize(Type type, Stream stream)
    {
        var serializer = new XmlSerializer(type.GetType());
        var obj = (Type) serializer.Deserialize(stream);
        return obj;
    }

    public void Register(IAppHost appHost)
    {
        appHost.ContentTypes.Register(MimeTypes.Xml, Serialize, Deserialize);
    }
}
```

## [SOAP Endpoint](/soap-support)

Consume ServiceStack Services via [SOAP](/soap-support) using WCF Add Service Reference or [ServiceStack generic SOAP Clients](/csharp-client#httpwebrequest-service-clients).

## [MQ Endpoint](/messaging)

Consume ServiceStack Services via [Message Queue](/messaging).


# JSON Format
Source: https://docs.servicestack.net/json-format

[ServiceStack.Text](https://github.com/ServiceStack/ServiceStack/tree/main/ServiceStack.Text/src/ServiceStack.Text) is an **independent, dependency-free** serialization library containing ServiceStack's core high-performance utils and text processing functionality, including its premier support for JSON.

### Try out [ServiceStack.Text Live](https://gist.cafe/c71b3f0123b3d9d08c1b11c98c2ff379)

A great way to try out ServiceStack.Text is on [gist.cafe](https://gist.cafe) which lets you immediately 
run and explore all ServiceStack.Text features from the comfort of your browser with zero software install:

<iframe src="https://gist.cafe/embed?gist=c71b3f0123b3d9d08c1b11c98c2ff379" frameborder="0" style="height:750px;width:100%;border:1px solid #ddd"></iframe>

## Install ServiceStack.Text

:::copy
`<PackageReference Include="ServiceStack.Text" Version="8.*" />`
:::

## Simple API

Like most of the interfaces in ServiceStack, the API is simple. Methods that you would commonly use include:

### Convenience Serialization Extension Methods

```csharp
string ToJson(T)
T FromJson()

string ToJsv(T)
T FromJsv()

string ToCsv(T)
T FromCsv()

string ToXml(T)
T FromXml()
```

### Typed JSON

```csharp
string JsonSerializer.SerializeToString<T>(T value)
void JsonSerializer.SerializeToWriter<T>(T value, TextWriter writer)

T JsonSerializer.DeserializeFromString<T>(string value)
T JsonSerializer.DeserializeFromReader<T>(TextReader reader)
```

Where *T* can be any .NET POCO type. That's all there is - the API was intentionally left simple :)

### Dynamic JSON parsing API

```csharp
JsonObject.Parse()
JsonArrayObjects.Parse()
```

### Supports Dynamic JSON

Although usually used to (de)serialize C#/.NET POCO types, it also includes a flexible API allowing you to deserialize any 
JSON payload without it's concrete type, see these real-world examples:

  - [Parsing GitHub's v3 API with typed DTOs](https://github.com/ServiceStack/ServiceStack/blob/main/ServiceStack.Text/tests/ServiceStack.Text.Tests/UseCases/GithubV3ApiTests.cs)
  - [Parsing GitHub's JSON response](https://github.com/ServiceStack/ServiceStack/blob/main/ServiceStack.Text/tests/ServiceStack.Text.Tests/UseCases/GitHubRestTests.cs)
  - [Parsing Google Maps JSON Response](https://github.com/ServiceStack/ServiceStack/blob/main/ServiceStack.Text/tests/ServiceStack.Text.Tests/UseCases/GMapDirectionsTests.cs)
  - [Parsing Centroid](https://github.com/ServiceStack/ServiceStack/blob/main/ServiceStack.Text/tests/ServiceStack.Text.Tests/UseCases/CentroidTests.cs)

Also a thin **.NET 4.0 Dynamic JSON** wrapper around ServiceStack's JSON library is included in the 
[ServiceStack.Razor](https://github.com/ServiceStack/ServiceStack/blob/main/ServiceStack.Text/src/ServiceStack.Text/Pcl.Dynamic.cs) 
project. It provides a dynamic, but more succinct API than the above options.

### JS Utils

ServiceStack.Text APIs for deserializing arbitrary JSON requires specifying the Type to deserialize into. An alternative flexible approach to read any arbitrary JavaScript or JSON data structures is to use the high-performance and memory efficient JSON utils in 
[#Script](https://sharpscript.net/) implementation of JavaScript.

```csharp
JSON.parse("1")       //= int 1 
JSON.parse("1.1")     //= double 1.1
JSON.parse("'a'")     //= string "a"
JSON.parse("{a:1}")   //= new Dictionary<string, object> { {"a", 1 } }
JSON.parse("[{a:1}]") //= new List<object> { new Dictionary<string, object> { { "a", 1 } } }
```

#### Eval

Since JS Utils is an essential part of [#Script](https://sharpscript.net/) it allows for advanced scenarios like implementing a text DSL or scripting language for executing custom logic or business rules you want to be able to change without having to compile or redeploy your App. It uses [#Script Context](https://sharpscript.net/docs/methods) which lets you evaluate the script within a custom scope that defines what functions 
and arguments it has access to, e.g.:

```csharp
public class CustomMethods : ScriptMethods
{
    public string reverse(string text) => new string(text.Reverse().ToArray());
}

var scope = JS.CreateScope(
         args: new Dictionary<string, object> { { "arg", "value"} }, 
    functions: new CustomMethods());

JS.eval("arg", scope)                                        //= "value"
JS.eval("reverse(arg)", scope)                               //= "eulav"
JS.eval("3.itemsOf(arg.reverse().padRight(8, '_'))", scope) //= ["eulav___", "eulav___", "eulav___"]

//= { a: ["eulav___", "eulav___", "eulav___"] }
JS.eval("{a: 3.itemsOf(arg.reverse().padRight(8, '_')) }", scope)
```

### Install JS Utils

ServiceStack's JS Utils is available in the [ServiceStack.Common](https://www.nuget.org/packages/ServiceStack.Common) NuGet package:

:::copy
`<PackageReference Include="ServiceStack.Common" Version="8.*" />`
:::

### Register JS Utils in ServiceStack.Text

JS Utils is already pre-configured in ServiceStack Web Apps to handle serializing & deserializing `object` types. 

You can also configure to use it in **ServiceStack.Text** Typed JSON Serializers **outside of ServiceStack** with:

```csharp
JS.Configure();
```

### Pretty Print JSON

You can format JSON into a more readable format with the `IndentJson()` extension method, e.g: 

```csharp
var prettyJson = dto.ToJson().IndentJson();
```

## ServiceStack's JsonSerializer

ServiceStack's JsonSerializer is optimized for serializing C# POCO types in and out of JSON as fast, compact and cleanly as possible. In most cases C# objects serializes as you would expect them to without added json extensions or serializer-specific artefacts.

JsonSerializer provides a simple API that allows you to serialize any .NET generic or runtime type into a string, TextWriter/TextReader or Stream.

### Serialization API

```csharp
string SerializeToString<T>(T)
void SerializeToWriter<T>(T, TextWriter)
void SerializeToStream<T>(T, Stream)
string SerializeToString(object, Type)
void SerializeToWriter(object, Type, TextWriter)
void SerializeToStream(object, Type, Stream)
```

### Deserialization API

```csharp
T DeserializeFromString<T>(string)
T DeserializeFromReader<T>(TextReader)
object DeserializeFromString(string, Type)
object DeserializeFromReader(reader, Type)
object DeserializeFromStream(Type, Stream)
T DeserializeFromStream<T>(Stream)
```

### Extension methods

```csharp
string ToJson<T>(this T)
T FromJson<T>(this string)
```

Convenient **ToJson/FromJson** extension methods are also included reducing the amount of code required, e.g:

```csharp
new []{ 1, 2, 3 }.ToJson()   //= [1,2,3]
"[1,2,3]".FromJson<int[]>()  //= int []{ 1, 2, 3 }
```

## JSON Format 

JSON is a lightweight text serialization format with a spec that's so simple that it fits on one page: [https://www.json.org](https://www.json.org).

The only valid values in JSON are:

  * string
  * number
  * object
  * array
  * true
  * false
  * null

Where most allowed values are scalar and the only complex types available are objects and arrays. Although limited, the above set of types make a good fit and can express most programming data structures.

### number, true, false types

All C# boolean and numeric data types are stored as-is without quotes.

### null type

For the most compact output null values are omitted from the serialized by default. If you want to include null values set the global configuration:

```csharp
JsConfig.Init(new Config { IncludeNullValues = true });
```

### string type

All other scalar values are stored as strings that are surrounded with double quotes.

### C# Structs and Value Types

Because a C# struct is a value type whose public properties are normally just convenience properties around a single scalar value, they are ignored instead the **TStruct.ToString()** method is used to serialize and either the **static TStruct.Parse()** method or **new TStruct(string)** constructor will be used to deserialize the value type if it exists.

### array type

Any List, Queue, Stack, Array, Collection, Enumerables including custom enumerable types are stored in exactly the same way as a JavaScript array literal, i.e:

```json
[1,2,3,4,5]
```

All elements in an array must be of the same type. If a custom type is both an IEnumerable and has properties it will be treated as an array and the extra properties will be ignored.

### object type

The JSON object type is the most flexible and is how most complex .NET types are serialized. The JSON object type is a key-value pair JavaScript object literal where the key is always a double-quoted string.

Any IDictionary is serialized into a standard JSON object, i.e:

```json
{"A":1,"B":2,"C":3,"D":4}
```

Which happens to be the same as C# POCO types (inc. Interfaces) with the values:

```cs
new MyClass { A=1, B=2, C=3, D=4 }
```

```json
{"A":1,"B":2,"C":3,"D":4}
```

Only public properties on reference types are serialized with the C# Property Name used for object key and the Property Value as the value. At the moment it is not possible to customize the Property Name.

JsonSerializer also supports serialization of anonymous types in much the same way:

```cs
new { A=1, B=2, C=3, D=4 }
```

```json
{"A":1,"B":2,"C":3,"D":4}
```

### Parsing JSON Dates

The default WCF Date that's returned in ServiceStack.Text can be converted with:

```js
function todate (s) { 
    return new Date(parseFloat(/Date\(([^)]+)\)/.exec(s)[1])); 
};
```

Which if you're using the [servicestack-client](/servicestack-client-umd) npm package can be resolved with:

```ts
import { todate } from "servicestack-client";
var date = todate(wcfDateString);
```

Or if using [ss-utils.js](/ss-utils-js) that's built into ServiceStack:

```js
var date = $.ss.todate(wcfDateString);
```

If you change ServiceStack.Text default serialization of Date to either use the ISO8601 date format:

```csharp
JsConfig.DateHandler = DateHandler.ISO8601;
```

It can be parsed natively with:

```js
new Date(dateString)
```

Likewise when configured to return:

```csharp
JsConfig.DateHandler = DateHandler.UnixTimeMs;
```

It can also be converted natively with:

```js
new Date(unixTimeMs)
```

## Global Default JSON Configuration

The JSON/JSV and CSV serialization can be customized globally by configuring the `JsConfig` or type-specific `JsConfig<T>` static classes with your preferred defaults. Global static configuration can be configured once on **Startup** using `JsConfig.Init()`, e.g:

```csharp
JsConfig.Init(new Config {
    DateHandler = DateHandler.ISO8601,
    AlwaysUseUtc = true,
    TextCase = TextCase.CamelCase,
    ExcludeDefaultValues = true,                
});
```

The following is a list of `bool` options you can use to configure many popular preferences:

<table>
    <thead>
        <tr><th>Name</th><th>Alias</th></tr>
    </thead>
    <tr><td>IncludeNullValues</td><td>inv</td></tr>
    <tr><td>IncludeNullValuesInDictionaries</td><td>invid</td></tr>
    <tr><td>IncludeDefaultEnums</td><td>ide</td></tr>
    <tr><td>IncludePublicFields</td><td>ipf</td></tr>
    <tr><td>IncludeTypeInfo</td><td>iti</td></tr>
    <tr><td>ExcludeTypeInfo</td><td>eti</td></tr>
    <tr><td>ExcludeDefaultValues</td><td>edv</td></tr>
    <tr><td>ConvertObjectTypesIntoStringDictionary</td><td>cotisd</td></tr>
    <tr><td>TreatEnumAsInteger</td><td>teai</td></tr>
    <tr><td>TryToParsePrimitiveTypeValues</td><td>ttpptv</td></tr>
    <tr><td>TryToParseNumericType</td><td>ttpnt</td></tr>
    <tr><td>ThrowOnDeserializationError</td><td>tode</td></tr>
    <tr><td>EscapeUnicode</td><td>eu</td></tr>
    <tr><td>EscapeHtmlChars</td><td>ehc</td></tr>
    <tr><td>PreferInterfaces</td><td>pi</td></tr>
    <tr><td>SkipDateTimeConversion</td><td>sdtc</td></tr>
    <tr><td>AlwaysUseUtc</td><td>auu</td></tr>
    <tr><td>AssumeUtc</td><td>au</td></tr>
    <tr><td>AppendUtcOffset</td><td>auo</td></tr>
    <tr><td>EscapeHtmlChars</td><td>ehc</td></tr>
    <tr><td>EscapeUnicode</td><td>eu</td></tr>
    <tr><td>EmitCamelCaseNames</td><td>eccn</td></tr>
    <tr><td>EmitLowercaseUnderscoreNames</td><td>elun</td></tr>
</table>

### DateHandler (dh)

<table>
    <tr><td>TimestampOffset</td><td>to</td></tr>
    <tr><td>DCJSCompatible</td><td>dcjsc</td></tr>
    <tr><td>ISO8601</td><td>iso8601</td></tr>
    <tr><td>ISO8601DateOnly</td><td>iso8601do</td></tr>
    <tr><td>ISO8601DateTime</td><td>iso8601dt</td></tr>
    <tr><td>RFC1123</td><td>rfc1123</td></tr>
    <tr><td>UnixTime</td><td>ut</td></tr>
    <tr><td>UnixTimeMs</td><td>utm</td></tr>
</table>

### TimeSpanHandler (tsh)

<table>
    <tr><td>DurationFormat</td><td>df</td></tr>
    <tr><td>StandardFormat</td><td>sf</td></tr>
</table>

### TextCase (tc)

<table>
    <tr><td>Default</td><td>d</td></tr>
    <tr><td>PascalCase</td><td>pc</td></tr>
    <tr><td>CamelCase</td><td>cc</td></tr>
    <tr><td>SnakeCase</td><td>sc</td></tr>
</table>

### PropertyConvention (pc)

<table>
    <tr><td>Strict</td><td>s</td></tr>
    <tr><td>Lenient</td><td>l</td></tr>
</table>

### Custom Config Scopes

If you need to use different serialization settings from the global static defaults you can use `JsConfig.With()` to create a scoped configuration
using property initializers:

```csharp
using (JsConfig.With(new Config { 
    TextCase = TextCase.CamelCase, 
    PropertyConvention = PropertyConvention.Lenient
}))
{
    return text.FromJson<T>();
}
```

#### Create Custom Scopes using String config

You can also create a custom config scope from a string manually using `JsConfig.CreateScope()` where you can use the full config name or their aliases, e.g:

```csharp
using (JsConfig.CreateScope("IncludeNullValues,EDV,dh:ut")) 
{
    var json = dto.ToJson();
}
```

This feature is used to provide a number of different [JSON customizations in ServiceStack Services](/customize-json-responses).

### Scoped Extension Methods

The convenience serialization methods `.ToJson()`, `.ToJsv()`, `.ToCsv()` also accept a lambda for configuring a custom configuration scope to simplify its usage, e.g:

```csharp
var json = dto.ToJson(config => config.TextCase = TextCase.SnakeCase);

// Equivalent To:
using var scope = JsConfig.With(new Config { TextCase = TextCase.Default });
var json = response.ToJson();
```

### Type Configuration

If you can't change the definition of a Type (e.g. because its in the BCL), you can specify a custom serialization /
deserialization routine to use instead. E.g. here's how you can add support for `System.Drawing.Color` and customize how `Guid` and `TimeSpan` Types are serialized:

```csharp
JsConfig<System.Drawing.Color>.SerializeFn = c => c.ToString().Replace("Color ","").Replace("[","").Replace("]","");
JsConfig<System.Drawing.Color>.DeSerializeFn = System.Drawing.Color.FromName;

JsConfig<Guid>.SerializeFn = guid => guid.ToString("D");
JsConfig<TimeSpan>.SerializeFn = time => 
    (time.Ticks < 0 ? "-" : "") + time.ToString("hh':'mm':'ss'.'fffffff");
```

For more advanced custom JSON serializations, see:

 - [CustomSerializerTests.cs](https://github.com/ServiceStack/ServiceStack/blob/main/ServiceStack.Text/tests/ServiceStack.Text.Tests/JsonTests/CustomSerializerTests.cs)
 - [CustomRawSerializerTests.cs](https://github.com/ServiceStack/ServiceStack/blob/main/ServiceStack.Text/tests/ServiceStack.Text.Tests/JsonTests/CustomRawSerializerTests.cs)

## Strict Parsing

By default ServiceStack Serializers will try to deserialize as much as possible without error, if you prefer you can opt-in to stricter parsing with:

```csharp
Env.StrictMode = true;
```

Where it will instead fail fast and throw Exceptions on deserialization errors.

## Custom Serialization

Although JsonSerializer is optimized for serializing .NET POCO types, it still provides some options to change the convention-based serialization routine.

### Using Structs to Customize JSON

This makes it possible to customize the serialization routine and provide an even more compact wire format. 

E.g. Instead of using a JSON object to represent a point 

```cs
{ Width=20, Height=10 }
```
	
You could use a struct and reduce it to just: 

```cs
"20x10"
```

By overriding **ToString()** and providing a static **Size ParseJson()** method:

```csharp
public struct Size
{
    public double Width { get; set; }
    public double Height { get; set; }

    public override string ToString()
    {
        return Width + "x" + Height;
    }

    public static Size ParseJson(string json)
    {
        var size = json.Split('x');
        return new Size { 
            Width = double.Parse(size[0]), 
            Height = double.Parse(size[1]) 
        };
    }
}
```

Which would change it to the more compact JSON output:

```csharp
    new Size { Width = 20, Height = 10 }.ToJson() // = "20x10"
```

That allows you to deserialize it back in the same way:

```csharp
    var size = "20x10".FromJson<Size>(); 
```

### Using Custom IEnumerable class to serialize a JSON array

In addition to using a Struct you can optionally use a custom C# IEnumerable type to provide a strong-typed wrapper around a JSON array:

```csharp
public class Point : IEnumerable
{
    double[] points = new double[2];

    public double X 
    {
        get { return points[0]; }
        set { points[0] = value; }
    }

    public double Y
    {
        get { return points[1]; }
        set { points[1] = value; }
    }

    public IEnumerator GetEnumerator()
    {
        foreach (var point in points) 
            yield return point;
    }
}
```

Which serializes the Point into a compact JSON array:

```csharp
    new Point { X = 1, Y = 2 }.ToJson() // = [1,2]
```

## Custom Deserialization

Because the same wire format shared between Dictionaries, POCOs and anonymous types, in most cases what you serialize with one type can be deserialized with another, i.e. an Anonymous type can be deserialized back into a Dictionary<string,string> which can be deserialized into a strong-typed POCO and vice-versa.

Although the JSON Serializer is best optimized for serializing and deserializing .NET types, it's flexible enough to consume 3rd party JSON apis although this generally requires custom de-serialization to convert it into an idiomatic .NET type.

[GitHubRestTests.cs](https://github.com/ServiceStack/ServiceStack/blob/main/ServiceStack.Text/tests/ServiceStack.Text.Tests/UseCases/GitHubRestTests.cs)

  1. Using [JsonObject](https://github.com/ServiceStack/ServiceStack/blob/main/ServiceStack.Text/src/ServiceStack.Text/JsonObject.cs)
  2. Using Generic .NET Collection classes
  3. Using Customized DTO's in the shape of the 3rd party JSON response

[CentroidTests](https://github.com/ServiceStack/ServiceStack/blob/main/ServiceStack.Text/tests/ServiceStack.Text.Tests/UseCases/CentroidTests.cs) is another example that uses the JsonObject to parse a complex custom JSON response. 

## Late-bound Object and Interface Runtime Types

In order to be able to deserialize late-bound objects like `object`, `interface` properties or `abstract` classes ServiceStack needs to emit type information
in the JSON payload. By default it uses `__type` property name, but can be customized with:

```csharp
JsConfig.TypeAttr = "$type";
```

You can also configure what Type Information is emitted with:

```csharp
JsConfig.TypeWriter = type => type.Name;
```

Which will just emit the name of the Type (e.g `Dog`) instead of the full Type Name.

By default ServiceStack will scan all loaded Assemblies to find the Type, but you can tell it to use your own Type Resolver implementation by overriding `TypeFinder`, e.g:

```csharp
JsConfig.TypeFinder = typeInfo =>  =>
{
    var regex = new Regex(@"^(?<type>[^:]+):#(?<namespace>.*)$");
    var match = regex.Match(value);
    var typeName = string.Format("{0}.{1}", match.Groups["namespace"].Value, match.Groups["type"].Value.Replace(".", "+"));
    return MyFindType(typeName);
};
```

### Runtime Type Whitelist

ServiceStack only allows you to serialize "known safe Types" in late-bound properties which uses a whitelist that's pre-populated with a safe-list of 
popular Data Types, DTOs and Request DTOs with the default configuration below:

```csharp
// Allow deserializing types with [Serializable], [DataContract] or [RuntimeSerializable] attributes
JsConfig.AllowRuntimeTypeWithAttributesNamed = new HashSet<string>
{
    nameof(SerializableAttribute),
    nameof(DataContractAttribute),
    nameof(RuntimeSerializableAttribute), // in ServiceStack.Text
};
 
// Allow deserializing types implementing any of the interfaces below
JsConfig.AllowRuntimeTypeWithInterfacesNamed = new HashSet<string>
{
    "IConvertible",
    "ISerializable",
    "IRuntimeSerializable", // in ServiceStack.Text
    "IReturn`1",
    "IReturnVoid",
    "IVerb",                // IGet, IPost, IPut, IPatch, etc
    "ICrud",                // ICreateDb<T>, IUpdateDb<T>, etc
    "IMeta",
    "IAuthTokens",
    "IHasResponseStatus",
};
 
// Allow object property in ServiceStack.Messaging MQ classes
JsConfig.AllowRuntimeTypeInTypesWithNamespaces = new HashSet<string>
{
    "ServiceStack.Auth",
    "ServiceStack.Messaging",
};
```

The above rules can be extended to allow your own conventions. If you just need to allow a specific Type you can instead just implement:

```csharp
JsConfig.AllowRuntimeType = type => type == typeof(MyType);
```

If you’re in a trusted intranet environment this can also be used to disable the whitelist completely by allowing all Types to be deserialized into object properties with:

```csharp
JsConfig.AllowRuntimeType = _ => true;
```

### Custom Enum Serialization

You can use `[EnumMember]` to change what Enum value gets serialized, e.g:

```csharp
[DataContract]
public enum Day
{
    [EnumMember(Value = "MON")]
    Monday,
    [EnumMember(Value = "TUE")]
    Tuesday,
    [EnumMember(Value = "WED")]
    Wednesday,
    [EnumMember(Value = "THU")]
    Thursday,
    [EnumMember(Value = "FRI")]
    Friday,
    [EnumMember(Value = "SAT")]
    Saturday,
    [EnumMember(Value = "SUN")]
    Sunday,            
}

class EnumMemberDto
{
    public Day Day { get; set; }
}

var dto = new EnumMemberDto {Day = Day.Sunday};
var json = dto.ToJson();  //= {"Day":"SUN"}

var fromDto = json.FromJson<EnumMemberDto>();
fromDto.Day               //= Day.Sunday
```


# System.Text.Json APIs
Source: https://docs.servicestack.net/system-text-json

From [ServiceStack v8.1](/releases/v8_01), ASP.NET Core .NET 8 Project Templates are configured to use [Endpoint Routing](/endpoint-routing)
that by default utilizes the default high-performance **System.Text.Json** JSON serializer to serialize and deserialize its JSON API Responses:

### Enabled by Default when using Endpoint Routing

```csharp
app.UseServiceStack(new AppHost(), options => {
    options.MapEndpoints();
});
```

### Configure System.Text.Json APIs

You can configure when to use System.Text.Json for APIs when registering to use Endpoint Routing:

```csharp
app.UseServiceStack(new AppHost(), options => {
    // Use for Serialization and Deserialization of JSON APIs (default)
    options.MapEndpoints(useSystemJson:UseSystemJson.Always);

    // Use only for deserializing API Requests
    options.MapEndpoints(useSystemJson:UseSystemJson.Request);

    // Use only for serializing API Responses
    options.MapEndpoints(useSystemJson:UseSystemJson.Response);

    // Don't use System.Text.Json for APIs
    options.MapEndpoints(useSystemJson:UseSystemJson.Never);
});
```

### Enhanced System.Text.Json

To improve compatibility with existing ServiceStack DTOs using ServiceStack.Text [JSON Serializer](/json-format) and
ServiceStack's rich ecosystem of generic [Add ServiceStack Reference](/add-servicestack-reference) Service Clients, 
ServiceStack uses a customized `JsonSerializerOptions` which is configured to:

- Uses `CamelCaseNamingPolicy` for property names
- Supports Case Insensitive Properties
- Not serialize `null` properties
- Serializes `TimeSpan` and `TimeOnly` Data Types with [XML Schema Time format](https://www.w3.org/TR/xmlschema-2/#isoformats)
- Supports `[DataContract]` annotations
- Supports Custom Enum Serialization

### Support for DataContract Annotations

Support for .NET's `DataContract` serialization attributes was added using a custom `TypeInfoResolver`, that supports:

- `[DataContract]` - When annotated, only `[DataMember]` properties are serialized
- `[DataMember]` - Specify a custom **Name** or **Order** of properties
- `[IgnoreDataMember]` - Ignore properties from serialization
- `[EnumMember]` - Specify a custom value for Enum values

### Custom Enum Serialization

Below is a good demonstration of the custom Enum serialization support which matches ServiceStack.Text's behavior:

```csharp
public enum EnumType { Value1, Value2, Value3 }

[Flags]
public enum EnumTypeFlags { Value1, Value2, Value3 }

public enum EnumStyleMembers
{
    [EnumMember(Value = "lower")]
    Lower,
    [EnumMember(Value = "UPPER")]
    Upper,
}

return new EnumExamples {
    EnumProp = EnumType.Value2, // String value by default
    EnumFlags = EnumTypeFlags.Value2 | EnumTypeFlags.Value3, // [Flags] as int
    EnumStyleMembers = EnumStyleMembers.Upper, // Serializes [EnumMember] value
    NullableEnumProp = null, // Ignores nullable enums
};
```

Which serializes to:

```json
{
  "enumProp": "Value2",
  "enumFlags": 3,
  "enumStyleMembers": "UPPER"
}
```

### Custom Configuration

You can further customize the `JsonSerializerOptions` used by ServiceStack by using `ConfigureJsonOptions()` to add
any customizations that you can optionally apply to ASP.NET Core's JSON APIs and MVC with:

```csharp
builder.Services.ConfigureJsonOptions(options => {
    options.PropertyNamingPolicy = JsonNamingPolicy.SnakeCaseLower;
})
.ApplyToApiJsonOptions()  // Apply to ASP.NET Core's JSON APIs
.ApplyToMvcJsonOptions(); // Apply to MVC
```

### Control over when and where System.Text.Json is used

Whilst `System.Text.Json` is highly efficient, it's also very strict in the inputs it accepts where you may want to
revert back to using ServiceStack's JSON Serializer for specific APIs, esp. when needing to support non-updatable 
external clients.

This can be done by annotating Request DTOs with `[SystemJson]` attribute, specifying when to use **System.Text.Json**, 
e.g: you can limit to only use it for serializing an **APIs Response** with:

```csharp
[SystemJson(UseSystemJson.Response)]
public class CreateUser : IReturn<IdResponse>
{
    //...
}
```

Or limit to only use `System.Text.Json` for deserializing an **APIs Request** with:

```csharp
[SystemJson(UseSystemJson.Request)]
public class CreateUser : IReturn<IdResponse>
{
    //...
}
```

Or not use `System.Text.Json` at all for an API with:

```csharp
[SystemJson(UseSystemJson.Never)]
public class CreateUser : IReturn<IdResponse>
{
    //...
}
```

### JsonApiClient Support

When Endpoints Routing is configured, the `JsonApiClient` will also be configured to utilize the same `System.Text.Json`
options to send and receive its JSON API Requests which also respects the `[SystemJson]` specified behavior.

Clients external to the .NET App can be configured to use `System.Text.Json` with:

```csharp
ClientConfig.UseSystemJson = UseSystemJson.Always;
```

Whilst any custom configuration can be applied to its `JsonSerializerOptions` with:

```csharp
TextConfig.ConfigureSystemJsonOptions(options => {
    options.PropertyNamingPolicy = JsonNamingPolicy.SnakeCaseLower;
});
```

### Scoped JSON Configuration

We've also added partial support for [Customized JSON Responses](/customize-json-responses)
for the following customization options:

:::{.table,w-full}
| Name                         | Alias |
|------------------------------|-------|
| EmitCamelCaseNames           | eccn  |
| EmitLowercaseUnderscoreNames | elun  |
| EmitPascalCaseNames          | epcn  |
| ExcludeDefaultValues         | edv   |
| IncludeNullValues            | inv   |
| Indent                       | pp    |
:::

These can be applied to the JSON Response by returning a decorated `HttpResult` with a custom `ResultScope`, e.g:

```csharp
return new HttpResult(responseDto) {
    ResultScope = () => 
        JsConfig.With(new() { IncludeNullValues = true, ExcludeDefaultValues = true })
};
```

They can also be requested by API consumers by adding a `?jsconfig` query string with the desired option or alias, e.g:

```csharp
/api/MyRequest?jsconfig=EmitLowercaseUnderscoreNames,ExcludeDefaultValues
/api/MyRequest?jsconfig=eccn,edv
```

### SystemJsonCompatible

Another configuration automatically applied when `System.Text.Json` is enabled is:

```csharp
JsConfig.SystemJsonCompatible = true;
```

Which is being used to make ServiceStack's JSON Serializer more compatible with `System.Text.Json` output so it's easier
to switch between the two with minimal effort and incompatibility. Currently this is only used to override
`DateTime` and `DateTimeOffset` behavior which uses `System.Text.Json` for its Serialization/Deserialization.


# CSV Format
Source: https://docs.servicestack.net/csv-format

The [CSV format](http://en.wikipedia.org/wiki/Comma-separated_values) is a first-class supported format which means all your existing web services can automatically take accept and return CSV without any config or code changes. 

### Importance of CSV

CSV is an important format for transferring, migrating and quickly visualizing data as all spreadsheets support viewing and editing CSV files directly whilst its supported by most RDBMS support exporting and importing data. Compared with other serialization formats, it provides a compact and efficient way to transfer large datasets in an easy to read text format.

### Speed

The CSV Serializer used was developed using the same tech that makes [ServiceStack's JSV and JSON serializers fast](http://www.servicestack.net/benchmarks/NorthwindDatabaseRowsSerialization.100000-times.2010-08-17.html) (i.e. no run-time reflection, static delegate caching, etc), which should make it the fastest CSV serializer available for .NET.

### Downloadable Separately

The `CsvSerializer` is maintained in the [ServiceStack.Text](https://github.com/ServiceStack/ServiceStack/tree/main/ServiceStack.Text) project which can be downloaded from NuGet at:

:::copy
`<PackageReference Include="ServiceStack.Text" Version="8.*" />`
:::

### How to register your own custom format with ServiceStack

Registering a custom format is done by registering the Format's Content-Type with to your AppHost's `ContentTypes` API, e.g:

```csharp
//Register the 'text/csv' content-type format
//Note: Format is inferred from the last part of the content-type, e.g. 'csv'

public class CsvFormat : IPlugin
{
    public void Register(IAppHost appHost)
    {
        appHost.ContentTypes.Register(MimeTypes.Csv,
            SerializeToStream, 
            CsvSerializer.DeserializeFromStream);

        //ResponseFilter to add 'Content-Disposition' header for browsers to open in Spreadsheet
        appHost.GlobalResponseFilters.Add((req, res, dto) => {
            if (req.ResponseContentType == MimeTypes.Csv) {
                var fileName = req.OperationName + ".csv";
                res.AddHeader(HttpHeaders.ContentDisposition, 
                    $"attachment;{HttpExt.GetDispositionFileName(fileName)}");
            }
        });
    }

    void SerializeToStream(IRequest req, object request, Stream stream) =>
        CsvSerializer.SerializeToStream(request, stream);
}
```

We recommend encapsulating Custom Formats registrations into a [Plugin](/plugins) as done with the built-in 
[CsvFormat](https://github.com/ServiceStack/ServiceStack/blob/master/src/ServiceStack/Formats/CsvFormat.cs) which is added by default:

```csharp
Plugins.Add(new CsvFormat()); //added by default
```

Which makes it easy to register, detect and remove. E.g. to remove built-in support for CSV you can just remove it from the `Plugins` collection:

```csharp
Plugins.RemoveAll(x => x is CsvFormat);
```

The ability to automatically to register another format and provide immediate value and added functionality to all your existing web services (without any code-changes or configuration) we believe is a testament to ServiceStack's clean design of using strongly-typed 'message-based' DTOs to let you develop clean, testable and re-usable web services. No code-gen or marshalling is required to bind to an abstract method signature, every request and calling convention maps naturally to your Web Services DTOs.

## Usage

The CSV format is effectively a first-class supported format so everything should work as expected, including being registered as an available format on ServiceStack's metadata index page:

* [/metadata](https://northwind.netcore.io/metadata)

And being able to preview the output of a service:

* [/csv/metadata?op=CustomerDetails](https://northwind.netcore.io/csv/metadata?op=CustomerDetails)

By default they are automatically available using ServiceStack's standard calling conventions, e.g:

* [/csv/reply/Customers](https://northwind.netcore.io/csv/reply/Customers)
    
### REST Usage

CSV also works just as you would expect with user-defined REST-ful urls, i.e. you can append `?format=csv` to specify the format in the url e.g:

* [/customers?format=csv](https://northwind.netcore.io/customers?format=csv)

This is how the above web service output looks when opened up in [google docs](https://spreadsheets.google.com/pub?key=0AjnFdBrbn8_fdDBwX0Rha04wSTNWZDZlQXctcmp2bVE&hl=en_GB&output=html)


Alternative in following with the HTTP specification you can also specify content-type `"text/csv"` in the *Accept* header of your HttpClient as done in [HTTP Utils](/http-utils) extension methods:

```csharp
var csv = "http://nortwind.netcore.io/customers".GetCsvFromUrl();
```

## CSV Deserialization Support

The introduction of the new [AutoQuery Data](/autoquery/data) feature and it's `MemorySource` has made full CSV support
a lot more appealing which caused CSV Deserialization support where it's implementation is now complete. This now unlocks the ability to create fully-queryable Services over flat-file .csv's (or Excel spreadsheets exported to .csv) by just deserializing CSV into a List of POCO's and registering it with AutoQuery Data:

```csharp
var pocos = File.ReadAllText("path/to/data.csv").FromCsv<List<Poco>>();

//AutoQuery Data Plugin
Plugins.Add(new AutoQueryDataFeature()
    .AddDataSource(ctx => ctx.MemorySource(pocos)));

// AutoQuery DTO
[Route("/pocos")]
public class QueryPocos : QueryData<Poco> {}
```

### Super CSV Format

A noteworthy feature that sets ServiceStack's CSV support apart is that it's built on the compact and very fast
[JSV format](/jsv-format) which not only can 
deserialize a tabular flat file of scalar values at high-speed, it also supports deeply nested object graphs
which are encoded in JSV and escaped in a CSV field as normal. An example of this can be seen in a HTTP 
sample log fragment below where the HTTP Request Headers are a serialized from a `Dictionary<string,string>`:

```csv
Id,HttpMethod,AbsoluteUri,Headers
1,GET,http://localhost:55799,"{Connection:keep-alive,Accept:""text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,*/*;q=0.8"",Accept-Encoding:""gzip, deflate, sdch"",Accept-Language:""en-US,en;q=0.8"",Host:""localhost:55799"",User-Agent:""Mozilla/5.0 (Windows NT 10.0; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/49.0.2623.112 Safari/537.36"",Upgrade-Insecure-Requests:1}"
```

Being such a versatile file format opens up a lot of new possibilities, e.g. instead of capturing seed data
in code you could maintain them in plain-text .csv files and effortlessly load them on App Startup, e.g:

```csharp
using (var db = container.Resolve<IDbConnectionFactory>().Open())
{
    if (db.CreateTableIfNotExists<Country>()) //returns true if Table created
    {
        List<Country> countries = "~/App_Data/countries.csv".MapHostAbsolutePath()
            .ReadAllText().FromCsv<List<Country>>();
    
        db.InsertAll(countries);
    }
}
```

### All Services now accept CSV Content-Types

Another immediate benefit of CSV Deserialization is that now all Services can now process the CSV Content-Type. 
Being a tabular data format, CSV shines when it's processing a list of DTO's, one way to do that in 
ServiceStack is to have your Request DTO inherit `List<T>`:

```csharp
[Route("/pocos")]
public class Pocos : List<Poco>, IReturn<Pocos>
{
    public Pocos() {}
    public Pocos(IEnumerable<Poco> collection) : base(collection) {}
}
```

It also behaves the same way as CSV Serialization but in reverse where if your Request DTO is annotated 
with either `[DataContract]` or the more explicit `[Csv(CsvBehavior.FirstEnumerable)]` it will automatically 
deserialize the CSV into the first `IEnumerable` property, so these 2 Request DTO's are equivalent to above:

```csharp
[Route("/pocos")]
[DataContract]
public class Pocos : IReturn<Pocos>
{
    [DataMember]
    public List<Poco> Items { get; set; }
}

[Route("/pocos")]
[Csv(CsvBehavior.FirstEnumerable)]
public class Pocos : IReturn<Pocos>
{
    public List<Poco> Items { get; set; }
}
```

In addition to the above flexible options for defining CSV-friendly Services, there's also a few different 
options for sending CSV Requests to the above Services. You can use the CSV `PostCsvToUrl()` extension 
methods added to [HTTP Utils](/http-utils):

```csharp
string csvText = File.ReadAllText("pocos.csv");

//Send CSV Text
List<Poco> response = "http://example.org/pocos"
    .PostCsvToUrl(csvText)
    .FromCsv<List<Poco>>();
    
//Send POCO DTO's
List<Poco> dtos = csvText.FromCsv<List<Poco>>();
List<Poco> response = "http://example.org/pocos"
    .PostCsvToUrl(dtos)
    .FromCsv<List<Poco>>();    
```

Alternatively you can use the `CsvServiceClient` which has the nice Typed API's you'd expect from a 
Service Client:

```csharp
var client = new CsvServiceClient(baseUrl);

Pocos response = client.Post(new Pocos(dtos));
```

### Ideal for Auto Batched Requests

The `CsvServiceClient` by virtue of being configured to use a well-defined Tabular data format is perfect 
for sending 
[Auto-Batched Requests](/auto-batched-requests) 
which by definition send a batch of POCO's making the CSV format the most compact text format to send them with:

```csharp
var requests = new[]
{
    new Request { ... },
    new Request { ... },
    new Request { ... },
};

var responses = client.SendAll(requests);
```

## Limitations

As most readers familiar with the CSV format will know there are some inherent limitations with CSV-format namely it is a flat-structured tabular data format that really only supports serialization of a single resultset. 

This limitation remains, although if you decorate your Response DTO with a `[Csv(CsvBehavior.FirstEnumerable)]` or standard .NET `[DataContract]/[DataMember]` attributes the CSV Serializer will change to use the following conventions: 

* If you only return one result in your DTO it will serialize that.
* If you return multiple results it will pick the first IEnumerable<> property or if it doesn't exist picks the first property.
* Non-enumerable results are treated like a single row.

Basically if you only return 1 result it should work as expected otherwise it will chose the best candidate based on the rules above.

The second major limitation is that it doesn't yet include a CSV Deserializer (currently on the TODO list), so while you can view the results in CSV format you can't post data to your web service in CSV and have it automatically deserialize for you. You can however still upload a CSV file and parse it manually yourself.

# Features

Unlike most CSV serializers that can only serialize rows of primitive values, the CsvSerializer uses the [JSV format](/jsv-format) under the hood so even [complex types](https://spreadsheets.google.com/pub?key=0AjnFdBrbn8_fdG83eWdGM1lnVW9PMlplcmVDYWtXeVE&hl=en_GB&output=html) will be serialized in fields in a easy to read format - no matter how deep its hierarchy.


# JSV Format
Source: https://docs.servicestack.net/jsv-format

ServiceStack provides a fast, compact format called JSV:

## JSV Text Format (JSON + CSV)

JSV is a text-based format that is optimized for both size and speed.

In many ways it is similar to JavaScript, e.g. any List, Array, Collection of ints, longs, etc are stored in exactly the same way, i.e:

```js
[1,2,3,4,5]
```

Any IDictionary is serialized like JavaScript, i.e:

```js
{A:1,B:2,C:3,D:4}
```

Which also happens to be the same as C# POCO class with the values 

```csharp
new MyClass { A=1, B=2, C=3, D=4 }
```

Which serializes to:

```js
{A:1,B:2,C:3,D:4}
```

JSV is *white-space significant*, which means normal string values can be serialized without quotes, e.g: 

```csharp
new MyClass { Foo="Bar", Greet="Hello World!"}
```

is serialized as:

```js
{Foo:Bar,Greet:Hello World!}
```

### CSV escaping

Any string with any of the following characters: `[]{},"`
is escaped using CSV-style escaping where the value is wrapped in double quotes, e.g:

```csharp
new MyClass { Name = "Me, Junior" }
```

is serialized as:
	
```js
{Name:"Me, Junior"}
```

A value with a double-quote is escaped with another double quote e.g:

```csharp
new MyClass { Size = "2\" x 1\"" }
```

is serialized as:

```js
{Size:"2"" x 1"""}
```

#### [.NET JsvServiceClient](/csharp-client#httpwebrequest-service-clients)

Thanks to the performance benefits of JSV's CSV-style escaping, the `JsvServiceClient` 
is our fastest text-based [.NET ServiceClient](/csharp-client):

```csharp
var client = new JsvServiceClient(baseUrl);
var response = client.Get(new Hello { Name = "World" });
```

### [JavaScript JSV Serializer](https://github.com/ServiceStack/ServiceStack/blob/v5.4.1/lib/js/JSV.js)

A JavaScript JSV parser is also available from [JSV.js](https://github.com/ServiceStack/ServiceStack/blob/v5.4.1/lib/js/JSV.js):

```javascript
var jsv = JSV.stringify(model);
var dto = JSV.parse(jsv);
```

#### JavaScript JsvServiceClient

[JSV.js](https://github.com/ServiceStack/ServiceStack/blob/v5.4.1/lib/js/JSV.js#L464) also includes the `JsvServiceClient` for consuming JSV Services:

```javascript
var client = new JsvServiceClient(baseUrl);
client.getFromService("Hello", { name: "World" }, 
    function(r) {
    });
```


# JSON Lines Data Format
Source: https://docs.servicestack.net/jsonl-format

<div class="not-prose my-8 flex justify-center">
   <a class="block max-w-2xl" href="https://jsonlines.org">
      <div class="block flex justify-center">
         <img class="py-8 h-80" src="/img/pages/release-notes/v6.10/jsonl.png">
      </div>
   </a>
</div>

<div class="py-8 max-w-7xl mx-auto">
    <lite-youtube class="w-full mx-4 my-4" width="560" height="315" videoid="m0tAfjvJaZg" style="background-image: url('https://img.youtube.com/vi/m0tAfjvJaZg/maxresdefault.jpg')"></lite-youtube>
</div>

[JSON Lines](https://jsonlines.org) is an efficient JSON data format parseable by streaming parsers and text processing tools
like Unix shell pipelines, whose streamable properties is making it a popular data format for maintaining large datasets
like the large AI datasets maintained on https://huggingface.co which is now accessible on [Auto HTML API](/auto-html-api) pages:

<div class="not-prose my-8 flex justify-center">
   <a class="block max-w-2xl" href="https://blazor-gallery.servicestack.net/albums">
      <div class="block flex justify-center shadow hover:shadow-lg rounded overflow-hidden">
         <img class="py-8" src="/img/pages/release-notes/v6.10/jsonl-format.png">
      </div>
   </a>
</div>

It's added by default, which can be removed with:

```csharp
Plugins.RemoveAll(x => x is JsonlFormat);
```

Which lists the `.jsonl` format like other data formats where it's accessible from `.jsonl` extension for `?format=jsonl` query string, e.g:

- https://blazor-gallery.servicestack.net/albums.jsonl
- https://blazor-gallery.servicestack.net/api/QueryAlbums?format=jsonl

In addition to the standard `Accept: text/jsonl` HTTP Header.

### CSV Enumerable Behavior

The JSON Lines data format behaves the same way as the CSV format where if your Request DTO is annotated with either
`[DataContract]` or the more explicit `[Csv(CsvBehavior.FirstEnumerable)]` it will automatically serialize the
**first IEnumerable property**, where all [AutoQuery APIs](/autoquery/) and the Request DTO's below will return their
`IEnumerable` datasets in the streamable JSON Lines format:

```csharp
public class QueryPocos : QueryDb<Poco> {}

[Route("/pocos")]
public class Pocos : List<Poco>, IReturn<Pocos>
{
    public Pocos() {}
    public Pocos(IEnumerable<Poco> collection) : base(collection) {}
}

[Route("/pocos")]
[DataContract]
public class Pocos : IReturn<Pocos>
{
    [DataMember]
    public List<Poco> Items { get; set; }
}

[Route("/pocos")]
[Csv(CsvBehavior.FirstEnumerable)]
public class Pocos : IReturn<Pocos>
{
    public List<Poco> Items { get; set; }
}
```

JSON Lines format is similar to the [CSV format](/csv-format) where each line in the file represents a separate JSON object. 
This makes it easy to process large datasets incrementally, without having to load the entire file into memory.

```json
{"id": 1, "name": "John Doe"}
{"id": 2, "name": "Jane Doe"}
{"id": 3, "name": "John Smith"}
```

These streamable properties in combination of the ubiquitous JSON format has led to its popularity where it can be processed by 
streaming parsers and text processing tools like Unix shell pipelines, making it an ideal format for handling large datasets efficiently, 
or quickly putting together a data pipeline for quick large scale experimentation.

For example, you can pull out the `title` property from a JSON Lines file using the following command line using just `curl` and `jq`:

:::sh
curl https://blazor-gallery.servicestack.net/albums.jsonl -s | jq '.title'
:::

### Async Streaming Parsing Example

The [HTTP Utils](/http-utils) extension methods makes it trivial to implement async streaming parsing where you can process
each row one at a time to avoid large allocations:

```csharp
const string BaseUrl = "https://blazor-gallery.servicestack.net";
var url = BaseUrl.CombineWith("albums.jsonl");
await using var stream = await url.GetStreamFromUrlAsync();
await foreach (var line in stream.ReadLinesAsync())
{
    var row = line.FromJson<Album>();
    //...
}
```

### JsonlSerializer

Alternatively if streaming the results isn't important it can be deserialized like any other format using the `JsonlSerializer` directly:

```csharp
var jsonl = await url.GetStringFromUrlAsync();
var albums = JsonlSerializer.DeserializeFromString<List<Album>>(jsonl);
```

Which can also serialize to a `string`, `Stream` or `TextWriter`:

```csharp
var jsonl = JsonlSerializer.SerializeToString(albums);
JsonlSerializer.SerializeToStream(albums, stream);
JsonlSerializer.SerializeToWriter(albums, textWriter);
```


## Indexing AI-Generated Art Albums with JSONL

In this example, we will walk you through a practical demonstration of using JSON Lines to index AI-generated art albums. We will fetch data 
from the Blazor Diffusion API, which provides "Creatives" generated based on user-provided text prompts. Our goal is to index the text and 
image URLs of these Creatives into a Typesense search server.

Here is the code snippet with a practical implementation of interacting with `creatives.jsonl` endpoint:

```csharp
const string ApiUrl = "https://localhost:5001/creatives.jsonl";

var provider = TypesenseUtils.InitProvider();
var typesenseClient = provider.GetRequiredService<ITypesenseClient>();
await typesenseClient.InitCollection();
var sw = new Stopwatch();
sw.Start();

var lastIndexedCreative = 0;

while (true)
{
    await using var stream = await ApiUrl.AddQueryParams(new() {
            ["IdGreaterThan"] = lastIndexedCreative,
            ["OrderBy"] = "Id",
        })
        .GetStreamFromUrlAsync();
    await foreach (var line in stream.ReadLinesAsync())
    {
        var creative = line.FromJson<Creative>();
        lastIndexedCreative = creative.Id;
        // processing
        if (creative.Artifacts.Count == 0)
            return;
        var imageId = creative.PrimaryArtifactId 
            ?? creative.CuratedArtifactId 
            ?? creative.Artifacts.First().Id;
        var artifact = creative.Artifacts.First(x => x.Id == imageId);
        var indexedCreative = new IndexedCreative
        {
            Text = creative.Prompt,
            Url = $"https://cdn.diffusion.works{artifact.FilePath}"
        };
        // Process and index the creative data
        await typesenseClient.CreateDocument("Creatives", indexedCreative);
    } 
    
    // sleep if no new data ..
}
```

Here we have the service client initialization with the `TypesenseUtils.InitProvider()`. Then, inside an infinite loop, we fetch data using `GetStreamFromUrlAsync()` and stream it line by line using the `ReadLinesAsync()` method. After processing each line, we index the creative item into typesense.

## Indexing Creative Data into Typesense

With Typesense, implementation of full-text search for our data can be achieved efficiently. Once we have fetched the Creative data from Blazor Diffusion's API, we can proceed to index it into Typesense for easy searching and analysis of the indexed documents. To index the Creative data, we're using [a C# client library built by the community](https://github.com/DAXGRID/typesense-dotnet).

Processed data are saved into IndexedCreative instances and are added into the Typesense server. Under the hood, the C# client library interacts with Typesense's API and handles all HTTP requests and responses for us.

### Memory Foot Print

Our application logs the memory usage over time, and we see it’s constant relative to the size of our process. Streamed JSONL parsing and async indexing allows us processing infinite datasets size without hitting the memory bounds.

## Skipping Already Indexed Data Example

For increased efficiency, instead of re-indexing all the data each time our program runs, we will only fetch and index data that hasn't been indexed already. We use `lastIndexedCreative` integer variable to keep track of the last creative indexed. On subsequent runs of our program, we fetch only new data by modifying the API URL to fetch Creative objects starting from the ID greater than `lastIndexedCreative`.

This is done by appending the `IdGreaterThan` query parameter to our AutoQuery endpoint.

```csharp
await using var stream = await ApiUrl.AddQueryParams(new() {
        ["IdGreaterThan"] = lastIndexedCreative,
        ["OrderBy"] = "Id",
    }).GetStreamFromUrlAsync();
```

## Visualizing Indexed Documents with Typesense Dashboard

Another great community feature is the [Typesense dashboard project](https://github.com/bfritscher/typesense-dashboard), providing a user-friendly interface to manage and browse collections in a Typesense search server. The dashboard, which can be accessed via the browser or as a downloadable desktop app, provides real-time statistics and overview over the indexed collections.

The indexed creative data can now be explored and analyzed using the dashboard's intuitive interface. You can apply filters, perform searches, and manipulate the stored data through the user interface.

## Conclusion

The JSON lines format is a versatile and efficient standard for working with large datasets. Its streamable properties make it particularly useful for handling big data and its ease of use makes it an ideal choice for developers working in any client language.

Streaming data directly to and from HTTP APIs — a major power of the JSON lines format — can dramatically improve the performance of data-intensive applications. Furthermore, ServiceStack's new JSON Lines support makes it straight forward serve and consume these streams.


# MsgPack Format
Source: https://docs.servicestack.net/messagepack-format

[Message Pack](http://msgpack.org/) is an efficient binary serialization format. It lets you exchange data among multiple languages like JSON but it's faster and smaller. 

If you ever wished to use JSON for convenience (e.g. storing an image with metadata) but could not for technical reasons (encoding, size, speed...), MessagePack offers a great replacement. Despite the name it ends up being a much [better "Binary JSON" than BSON is](http://stackoverflow.com/questions/6355497/performant-entity-serialization-bson-vs-messagepack-vs-json), as it's much faster, smaller and doesn't require the foreign types like "ObjectId", "UUID" that BSON has.

MsgPack is a great addition to your ServiceStack's web services as it has [similar performance to Protocol Buffers](http://theburningmonk.com/2012/02/performance-test-binary-serializers-part-iii/) (.NET's fastest binary serializer) but is also schema-less like JSON so already works with your Un-Attributed, **Clean POCOs** - no code-changes required. (as opposed to [Protobuf format](/protobuf-format) which requires decorating every serializable property with `[DataMember(Order=N)]`).

## Installing via NuGet

Message Pack is easily installed with the [ServiceStack.MsgPack](https://nuget.org/packages/ServiceStack.MsgPack) NuGet package:

:::copy
`<PackageReference Include="ServiceStack.MsgPack" Version="8.*" />`
:::

After the NuGet Package is added to your Project, enable the MsgPack format in your `AppHost` with:

```cs
Plugins.Add(new MsgPackFormat());
```

The NuGet plugin also includes the **MsgPackServiceClient** client below so you can easily call it from any C# Client.

## Client Usage

Just like the rest of ServiceStack C# Clients, MsgPackServiceClient is interchangeable with the other clients that equally supports all your ServiceStack's services including the [New API Design](/api-design), e.g:

```csharp
var client = new MsgPackServiceClient(BaseUri);
List<Todo> all = client.Get(new Todos());           // Count = 0

var todo = client.Post(
    new Todo { Content = "New TODO", Order = 1 });  // todo.Id = 1
all = client.Get(new Todos());                      // Count = 1

todo.Content = "Updated TODO";
todo = client.Put(todo);                            // todo.Content = Updated TODO

client.Delete(new Todos(todo.Id));
all = client.Get(new Todos());   
```

More examples of using MsgPackServiceClient can be found in the [New APIs Integration Test Suite](https://github.com/ServiceStack/ServiceStack/blob/master/tests/RazorRockstars.Console.Files/ReqStarsService.cs).


# ProtoBuf Format
Source: https://docs.servicestack.net/protobuf-format

[Protocol Buffers](http://code.google.com/p/protobuf/) is a high-performance, compact binary wire format invented by Google who use it internally so they can communicate with their internal network services at very high speed.

For .NET [@marcgravell](http://twitter.com/marcgravell) has developed **[protobuf-net](http://code.google.com/p/protobuf-net/)** - a robust implementation of the Protocol Buffers wire format that provides the [fastest serialization](http://www.servicestack.net/benchmarks/#northwind-serializer) option available for .NET.

ProtoBuf is a great addition to your ServiceStack's web services as it provides the **fastest binary serializer** to go along with the **2 fastest text serializers** for .NET in [JSON](http://www.servicestack.net/mythz_blog/?p=344) and [JSV](http://www.servicestack.net/mythz_blog/?p=176) formats (already included by default). 

Otherwise another fast binary serializer that supports attribute-less POCOs is the new [MessagePack Format](/messagepack-format).

## Installing via NuGet

As it requires an external **protobuf-net.dll** dependency ProtoBuf support is not automatically bundled inside ServiceStack, but it is easily installed with the [ServiceStack.ProtoBuf](https://nuget.org/packages/ServiceStack.ProtoBuf) NuGet package:

:::copy
`<PackageReference Include="ServiceStack.ProtoBuf" Version="8.*" />`
:::

After the NuGet Package is added to your Project, enable the ProtoBuf format in your `AppHost` with:

```cs
Plugins.Add(new ProtoBufFormat());
```

The NuGet plugin also includes the **ProtoBufServiceClient** client below so you can easily call it from any C# Client.

## Registering ProtoBuf Manually

The API for adding custom Formats and Content Types in ServiceStack is so easy we use it ourselves :) Where the CSV, HTML, Markdown and now ProtoBuf format are all registered in the same way by registering the new ContentType with your AppHost's **ContentTypeFilters**.

Adding support for ProtoBuf is equally simple.  It can be added by calling a single method:

```csharp
appHost.ContentTypeFilters.Register(ContentType.ProtoBuf,
    (reqCtx, res, stream) => ProtoBuf.Serializer.NonGeneric.Serialize(stream, res),
    ProtoBuf.Serializer.NonGeneric.Deserialize);
```

This makes the ProtoBuf format available in all of ServiceStack:

  - A new **X-PROTOBUF** column added for all services on the metadata pages
  - New `/x-protobuf/syncreply/{Service}` and `/x-protobuf/asynconeway/{Service}` pre-defined routes
  - Clients can request it with `Accept: application/x-protobuf` HTTP Header or **?format=x-protobuf** query string

## End to End happiness

However simply registering ProtoBuf is not enough to ensure end-to-end happiness so we also make it easy to create your own generic strong-typed ProtoBuf ServiceClient with the following code:

```csharp
public class ProtoBufServiceClient : ServiceClientBase
{
    public override string Format
    {
        get { return "x-protobuf"; }
    }

    public ProtoBufServiceClient(string baseUri)
    {
        SetBaseUri(baseUri);
    }

    public ProtoBufServiceClient(string syncReplyBaseUri, string asyncOneWayBaseUri)
        : base(syncReplyBaseUri, asyncOneWayBaseUri) { }

    public override void SerializeToStream(IRequest req, object request, Stream stream)
    {
        Serializer.NonGeneric.Serialize(stream, request);
    }

    public override T DeserializeFromStream<T>(Stream stream)
    {
        return Serializer.Deserialize<T>(stream);
    }

    public override string ContentType
    {
        get { return MimeTypes.ProtoBuf; }
    }

    public override StreamDeserializerDelegate StreamDeserializer
    {
        get { return Deserialize; }
    }

    private static object Deserialize(Type type, Stream source)
    {
        return Serializer.NonGeneric.Deserialize(type, source);
    }
}
```

This now lets you call each of your services with a Strong Typed service client of your very own:

```csharp
var client = new ProtoBufServiceClient(BaseUri);
var response = client.Send<HelloResponse>(new Hello { Name = "ProtoBuf" });
```

The above ProtoBufServiceClient works like all the other strong-typed ServiceClients in ServiceStack where it also implements `IServiceClient` and `IRestClient` interfaces so you can easily swap out your existing clients to take advantage of the performance boost offered by ProtoBuf with minimal effort!


# Community Resources

  - [REST with ProtoBuf - Web Services in 5 easy steps](http://stevenhollidge.blogspot.com/2012/04/servicestack-rest-with-protobuf.html) by [@stevenhollidge](https://twitter.com/stevenhollidge)


# HTML5 JSON Report Format
Source: https://docs.servicestack.net/html5reportformat

These examples are simply links to existing ServiceStack web services, which based on your browsers user-agent (i.e. Accept: 'text/html') provides this HTML format instead of the other serialization formats.

| Northwind API    |                                                      |                                                           |
| ---------------- | ---------------------------------------------------- | --------------------------------------------------------- |
| All Customers    | [html](https://northwind.netcore.io/customers)       | [json](https://northwind.netcore.io/customers.json)       |
| Customer Details | [html](https://northwind.netcore.io/customers/ALFKI) | [json](https://northwind.netcore.io/customers/ALFKI.json) |
| Customer Orders  | [html](https://northwind.netcore.io/orders)          | [json](https://northwind.netcore.io/orders.json)          |

<div class="not-prose mt-8 flex items-center">
    <a class="block" href="https://northwind.netcore.io/customers/ALFKI.json">
        <img class="" src="/img/pages/formats/CustomerDetails-json.png">
    </a>
    <div class="flex flex-col items-center px-2 text-lg font-bold text-green-700">
      <div>JSON</div>
      <svg class="w-8 h-8" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path fill="currentColor" d="M16.01 11H4v2h12.01v3L20 12l-3.99-4z"/></svg>
      <div>HTML</div>
    </div>
    <a class="block" href="https://northwind.netcore.io/customers/ALFKI">
        <img class="" src="/img/pages/formats/CustomerDetails-html.png">
    </a>
</div>


To see it in action, **view the source** in your browser. Webkit and Firefox users can simply go to the url below:

```
view-source:https://northwind.netcore.io/customers/ALFKI
```

Note: To view the web services in a different format simply append either **.{ext}** or **?format={ext}** to the query string, e.g:

```
/customers.json
/customers?format=[json|xml|html|csv|jsv]
```

## Lightweight Customizable HTML Templates

ServiceStack's auto HTML response pages can be overridden specific routes by populating `HtmlFormat.PathTemplates`
with a lightweight HTML template, e.g. the `/auth` page is pre-configured with:

```csharp
GetPlugin<HtmlFormat>.PathTemplates["/auth"] = "/Templates/Auth.html";
```

Specifying the **/path/info** to override and the **VirtualPath** of the static HTML page that should be returned instead.

That instead of the JSON HTML Dump of the `/auth` endpoint, now returns a static `.html` page to display the `AuthenticateResponse`
DTO in a beautified custom HTML view:

![](/img/pages/release-notes/v5.9/auth-page.png)

The static HTML templates will replace these variable placeholders which will allow you to render a custom view of service responses:

- `${Dto}` JSON Response DTO
- `${BaseUrl}` - `IRequest.GetBaseUrl()`
- `${ServiceUrl}` - Service URL

### [The Magic AutoGrid Partial](https://github.com/ServiceStackApps/HttpBenchmarks#the-magic-autogrid-partial)

[![Search Test Results](https://raw.githubusercontent.com/ServiceStack/HttpBenchmarks/master/src/BenchmarksAnalyzer/Content/img/search-filter.png)](https://github.com/ServiceStack/HttpBenchmarks/blob/master/src/BenchmarksAnalyzer/Views/SearchTestResults.cshtml)

A bootstrap themed version of HTML Format is also encapsulated within an [AutoGrid.cshtml](https://github.com/ServiceStack/HttpBenchmarks/blob/master/src/BenchmarksAnalyzer/Views/Shared/AutoGrid.cshtml)
partial which does the heavy lifting of converting any C# enumerable into a human optimized dynamic sortable datagrid with just 1 Line of Code:

```csharp
@Html.Partial("AutoGrid", Model.Results)
```

### Human Friendly output

The primary focus for the HTML Format is to provide a readable and semantic HTML layout letting you visualize all the data returned by your web service with a single glance.
Features include:

Based on convention, it generates a recursive and cascading view of your data using a combination of different sized definition lists and tables where appropriate.
After it's rendered convenience behaviour is applied allowing you to sort your tabular data, view the embedded JSON contents as well as providing links back to the original web service that generated the report including links to the other formats supported.

### Completely self-contained

The report does not have any external CSS, JavaScript or Images which also helps achieve its super-fast load-time and rendering speed.

### Embeds the complete snapshot of your web services data

The report embeds a complete, unaltered version of your 'JSON webservice' capturing a snapshot of the state of your data at a given point in time.
It's perfect for backups with the same document containing a human and programatic access to the data.
The JSON data is embedded inside a valid and well-formed document, making it programmatically accessible using a standard XML/HTML parser.
The report also includes an interface to allow humans to copy it from a textbox.

### It's Fast

Like the other web services, the HTML format is just a raw C# IHttpHandler using
[.NET's fastest JSON Serializer](http://www.servicestack.net/mythz_blog/?p=344)
to serialize the response DTO to a JSON string which is embedded inside a **static HTML string template**.
No other .aspx page or MVC web framework is used to get in the way to slow things down.
High performance JavaScript techniques are also used to start generating the report at the earliest possible time.

### Well supported in all modern browsers

It's tested and works equally well on the latest versions of Chrome, Firefox, Safari, Opera and IE9.
[v1.83](https://github.com/ServiceStack/ServiceStack/downloads) Now works in IE8 but needs internet connection to download json2.js. (not tested in <=IE7)

### It Validates (as reported by validator.w3.org)

This shouldn't be important but as the technique of using JavaScript to generate the entire report is likely to ire the semantic HTML police, I thought I'd make this point. Personally I believe this style of report is more useful since it caters for both human and scripted clients.

# How it works - 'view-source' reveals all :)

This is a new type of HTML5 report that breaks the normal conventional techniques of generating a HTML page.
Instead of using a server programming and template language to generate the HTML on the server, the data is simply embedded as JSON, unaltered inside the tag:

```xml
<script id="dto" type="text/json">{jsondto}</script>
```

Because of the browser behaviour of the script tag, you can embed any markup or javascript unescaped.
Unless it has none or a 'javascript' type attribute, the browser doesn't execute it letting you to access the contents with:

```js
document.getElementById("dto").innerHTML;
```

From there, javascript invoked just before the closing body tag (i.e. the fastest time to run DOM-altering javascript) which takes the data,
builds up a html string and injects the generated markup in the contents of the page.

After the report is rendered, and because JavaScript can :) UX-friendly behaviours are applied to the document allowing the user to sort the table data on each column as well as providing an easy way to take a copy of the JSON datasource.

For what it does, the JavaScript is very terse considering no JavaScript framework was used. In most cases the JSON payload is a lot larger than the entire JavaScript used to render the report :)

### Advantages of a strong-typed, code-first web service framework

Although hard to believe, most of the above web service examples were developed before ServiceStack's CSV and HTML format existed.
No code-changes were required in order to take advantage of the new formats, they were automatically available after replacing the ServiceStack.dlls with the latest version (v1.81+)

Being able to generically provide new features like this shows the advantage of ServiceStack's strong-typed, code-first approach to developing web services that lets you focus on your app-specific logic as you only need to return C#/.NET objects or throw C#/.NET exceptions which gets automatically handled, and hosted on a number of different endpoints in a variety of different formats.

Out of the box REST, RPC and SOAP endpoints types are automatically provided, in JSON, XML, CSV, JSV and now the new HTML report format above.

### Disable Auto HTML Pages

ServiceStack's fallback [Auto HTML Report Pages](/html5reportformat) can be disabled with:

```csharp
SetConfig(new HostConfig {
    EnableAutoHtmlResponses = false
})
```

When disabled it will render Response DTOs from Browser requests (i.e. `Accept:text/html`) in the next `Config.PreferredContentTypes` - (JSON by default).


# .NET Core Overview
Source: https://docs.servicestack.net/netcore

![](https://raw.githubusercontent.com/ServiceStack/Assets/master/img/release-notes/netcore-banner.png?t)

Most of ServiceStack's features are also available on .NET Core, where it's all maintained within a single code-base 
enabling excellent source-code compatibility to maximize existing knowledge and code-reuse and reducing portability efforts, 
and released within the same suite of NuGet packages, all without breaking changes to existing .NET 4.5 Customers.

### .NET Core - the future of .NET on Linux

.NET Core enables an exciting era of .NET Web and Server App development - the kind .NET hasn't seen before. 
The existing Windows hosting and VS.NET restraints have been freed, now anyone can develop using .NET's
productive expertly-designed and statically-typed mainstream C#/F# languages in their preferred editor and 
host it on the most popular server Operating Systems, in either an all-Linux, all-Windows or mixed ecosystem. 
Not only does this flexibility increase the value of existing .NET investments but it also makes .NET appeal 
to the wider and highly productive developer ecosystem who've previously disregarded .NET as an option. 

.NET Core offers significant performance and stability improvements over Mono that's derived from a shared 
cross-platform code-base and supported by a well-resourced, active and responsive team. 
If you're currently running **ServiceStack on Mono**, we strongly recommend **upgrading to .NET Core** to 
take advantage of its superior performance, stability and its top-to-bottom supported Technology Stack.

and with that let's jump into seeing some ServiceStack Live Demos running on .NET Core in Linux...

### ServiceStack .NET Core Apps running in Docker

Hosting .NET Core Apps immediately exposes us to the benefits of .NET Core. We've ported the Live Demos using 
the most productive IDE and tooling combination we've found for us - which is still VS.NET with ReSharper. 
But for deployments and hosting we now have an array of options at our disposal, including joining the 
thriving state-of-the-art ecosystem around building Linux Docker images and deploying them to the cloud. 

For .NET Core Live Demos we've settled on the popular power combo of:

 - Using [travis-ci.org](https://travis-ci.org/) (free for OSS projects) for running CI scripts to rebuild Docker App Images on every check-in
 - Using [AWS EC2 Container Service](https://aws.amazon.com/ecs/) for managing Docker images and instance deployments
 - Using [nginx-proxy](https://github.com/jwilder/nginx-proxy) setting up an nginx reverse proxy and automatically bind virtual hosts to Docker Instances

You can checkout our [Deploy .NET Core with Docker to AWS ECS Guide](/deploy-netcore-docker-aws-ecs) 
for the details on how we've deployed the .NET Core Live Demos, but ultimately packaging .NET Core Apps 
inside Docker images enables a higher-level of abstraction letting you define your entire App Server 
Instance with a repeatable recipe that lets you treat and deploy instances like opaque self-contained units.

With our [.NET 4.5 Windows Live Demos](https://github.com/ServiceStackApps/LiveDemos) we're effectively 
mutating a static Windows Server VM that required pre-configuring with IIS Virtual Hosts. Any infrastructure 
Servers each Live Demo needs, are set up out-of-band and to minimize the System administration burden, 
all Demos share the same Redis server instance.

#### Repeatable, Isolated, no-touch automated Deployments

But for our .NET Core Docker deployments we have proper isolation and repeatable no-touch deployments 
where any infrastructure services each App needs are declared in configuration and deployed in a separate 
Docker container along side each App to an ECS cluster - decoupling your deployments from static EC2 instances.
This lets you treat your server infrastructure and deployment automation story like code, where it's 
checked-in with your Repo and run with your CI who packages it in a Docker Container, publishes it as an 
opaque Image and deploys it to the [AWS EC2 Container Service](https://aws.amazon.com/ecs/).

#### Linux Cost Savings

In addition to the thriving ecosystem and superior automation, another benefit of hosting .NET Core Apps 
on Linux is the considerable cost savings of hosting on a Linux infrastructure. Docker instances enable 
isolation with considerably more efficiency than VM's allowing you to pack them with greater density. 
For .NET Core Live Demos the single T2 medium instance (**$25 /month**) is hosting 15 Docker Images whilst
running at **~50% Memory Utilization** and **&lt;1% CPU Utilization** in its current idle state.

### Exceptional Code reuse

Thanks to ServiceStack's high-level host agnostic API and our approach to decouple from concrete HTTP abstractions behind lightweight `IRequest` interfaces, ServiceStack projects enjoy near perfect code reuse, which allows the same ServiceStack Services to be able to run on ASP.NET, HttpListener SelfHosts, SOAP Endpoints, multiple MQ Hosts and .NET Core Apps. The [HelloMobile Server Hosts](https://github.com/ServiceStackApps/HelloMobile#servicestack-server-app) shows an example of this where the same [AppHost Configuration and WebServices implementation](https://github.com/ServiceStackApps/HelloMobile/blob/master/src/Server.Common/WebServices.cs) is used in all:

 - .NET 6.0 Server
 - ASP.NET Core running on .NET Framework
 - ASP.NET Web App (.NET Framework)
 - HttpListener Self-Host (.NET Framework)
 
The primary advantage of this is simplicity, in both effort and cognitive overhead for creating Services that target multiple platforms, reuse of existing knowledge and investments in using ServiceStack libraries and features as well as significantly reduced migration efforts for porting existing .NET Framework code-bases to run on .NET Core where it enjoys near perfect source code compatibility. 
 
ServiceStack's exceptional source compatibility is visible in our new .NET 6.0 and .NET Framework project templates where all templates utilize the same recommended [Physical Project Structure](/physical-project-structure), reference the same NuGet packages, share the same source code for its Server and Client App implementations as well as Client and Server Unit and Integration Tests.

The primary difference between the .NET Core and .NET Framework project templates is how ServiceStack's `AppHost` is initialized, in ASP.NET it's done in `Global.asax` whilst for .NET Core it's registered in .NET Core's pipeline as standard. The `.csproj` are also different with .NET Core using MSBuild's new and minimal human-friendly format and the ASP.NET Framework templates continuing to use VS.NET's classic project format for compatibility with older VS .NET versions.

## New .NET 6.0 Project Templates
 
There are **11 .NET 6.0 project templates** for each of ServiceStack's most popular starting templates. Each .NET 6.0 template has an equivalent .NET Framework template except for ServiceStack [Sharp Apps](https://sharpscript.net/docs/sharp-apps) which is itself a pre-built .NET 6.0 App that lets you develop Web Applications and HTTP APIs on-the-fly without any compilation.

All .NET 6.0 Templates can be developed using your preferred choice of either VS Code, VS.NET or JetBrains Project Rider on your preferred Desktop OS. Given the diverse ecosystem used to develop .NET Core Applications, the new Project Templates are being maintained on GitHub and made available via our new [x new](/web-new) command-line utility, installable from npm with:
 
:::sh
dotnet tool install --global x 
:::
 
This makes the `x` .NET Core tool globally available which can be run without arguments to view all templates available:

::include web-new-netcore.md::

### Usage

That can be used to create new projects with:
 
:::sh
x new `<template-name>` `<project-name>`
:::
 
Example of creating a new **Vue SPA** project called **Acme**:
 
:::sh
x new vue-spa Acme
:::
 
The resulting `Acme.sln` can be opened in VS 2017 which will automatically restore and install both the .NET and npm packages upon first load and build. This can take a while to install all client and server dependencies, once finished the `wwwroot` folder will be populated with your generated Webpack App contained within a `/dist` folder alongside a generated `index.html` page. After these are generated you can run your App with **F5** to run your project as normal:

![](/img/pages/ssvs/dotnet-new-spa-files.png)

If using JetBrains Rider the npm packages can be installed by opening `package.json` and clicking on the **"npm install"** tooltip on the **bottom right**. In VS Code you'll need to run `npm install` manually from the command-line.

## .NET Core Live Demos

To showcase ServiceStack features running on .NET Core we've forked several of our existing 
[Live Demos](https://github.com/ServiceStackApps/LiveDemos) and ported them to .NET Core and 
listed them side-by-side with their original ASP.NET 4.5 code-bases so they can be easily compared.

The Live Demos cover a broad spectrum of ServiceStack features including:


### Multi-stage Docker Builds

The [.NET Core Apps deployed using Docker](/deploy-netcore-docker-aws-ecs) use ASP.NET Team's [recommended multi-stage Docker Builds](https://docs.microsoft.com/en-us/dotnet/core/docker/building-net-docker-images#your-first-aspnet-core-docker-app) where the App is built inside an `aspnetcore-build` Docker container with its published output copied inside a new `aspnetcore` runtime Docker container:

```docker
FROM mcr.microsoft.com/dotnet/core/sdk:3.1 AS build
WORKDIR /app

# copy csproj and restore as distinct layers
COPY src/*.sln .
COPY src/Chat/*.csproj ./Chat/
RUN dotnet restore

# copy everything else and build app
COPY src/Chat/. ./Chat/
WORKDIR /app/Chat
RUN dotnet publish -c Release -o out

FROM mcr.microsoft.com/dotnet/core/aspnet:3.1 AS runtime
WORKDIR /app
COPY --from=build /app/Chat/out ./
ENV ASPNETCORE_URLS http://*:5000
ENTRYPOINT ["dotnet", "Chat.dll"]
```

The smaller footprint required by the `aspnetcore` runtime reduced the footprint of [.NET Core Chat](https://github.com/NetCoreApps/Chat) from **567MB** to **126MB** whilst continuing to run flawlessly in AWS ECS at [chat.netcore.io](http://chat.netcore.io).

### .NET Core Web Apps

.NET 6.0 is also used to enable [Sharp Apps](https://sharpscript.net/docs/sharp-apps) which is a new approach to dramatically simplify .NET Wep App development and provide the most productive development experience possible whilst maximizing reuse and component sharing. 

Web Apps let you develop dynamic websites without needing to write any C# code or perform any app builds which dramatically reduces the cognitive overhead and conceptual knowledge required for development where the only thing front-end Web developers need to know is [ServiceStack #Script Syntax](https://sharpscript.net/docs/syntax) and [what scripts are available](https://sharpscript.net/docs/filters-reference) to call. Because of #Script's high-fidelity with JavaScript, developing a Website with Templates will be instantly familiar to JavaScript devs despite calling and binding directly to .NET APIs behind the scenes.

#### [Web App Examples](https://gist.github.com/gistlyn/f555677c98fb235dccadcf6d87b9d098#live-demos#live-demos)

To illustrate the various features available we've developed a number of Web Apps examples to showcase the different kind of Apps that can easily be developed. The source code for each app is available from [github.com/NetCoreWebApps](https://github.com/sharp-apps). Each app runs the same unmodified [Web App Binary](https://github.com/ServiceStack/Web) that's also used in the Bare Web App project above.

You can quickly get started by creating a Web App from the project template:

:::sh
dotnet-new bare-app ProjectName
:::

## Run ASP.NET Core Apps on the .NET Framework

A primary use-case prevented from having unified NuGet packages containing both **.NET Standard** and **.NET Framework** builds is being able to run ASP.NET Core Apps on the **.NET Framework** which stems from:

  - `net45` - Contains support for running **ASP.NET** Web or Self-Hosting **HttpListener** App Hosts
  - `netstandard2.0` - Contains support for only running on **ASP.NET Core** App Hosts

Where the `net45` builds always get used when they're added to any **.NET Framework** project. To support running ASP.NET Core Apps on the .NET Framework you can use the `.Core` NuGet packages which contains only the **.NET Standard 2.0** builds in order to force .NET Framework projects to use **.NET Standard 2.0** builds. Currently the complete list of `.Core` packages which contains only **.NET Standard 2.0** builds include:

 - ServiceStack.Text.Core
 - ServiceStack.Interfaces.Core
 - ServiceStack.Client.Core
 - ServiceStack.HttpClient.Core
 - ServiceStack.Core
 - ServiceStack.Common.Core
 - ServiceStack.Mvc.Core
 - ServiceStack.Server.Core
 - ServiceStack.Redis.Core
 - ServiceStack.OrmLite.Core
 - ServiceStack.OrmLite.Sqlite.Core
 - ServiceStack.OrmLite.SqlServer.Core
 - ServiceStack.OrmLite.PostgreSQL.Core
 - ServiceStack.OrmLite.MySql.Core
 - ServiceStack.OrmLite.MySqlConnector.Core
 - ServiceStack.Aws.Core
 - ServiceStack.Azure.Core
 - ServiceStack.RabbitMq.Core
 - ServiceStack.Api.OpenApi.Core
 - ServiceStack.Admin.Core
 - ServiceStack.Stripe.Core
 - ServiceStack.Kestrel

::: warning
Ultimately support for whether a **.NET Standard 2.0** library will run on the .NET Framework depends on whether external dependencies also support this scenario which as it's a more niche use-case, will be a less tested scenario
:::

Other issues from being a less popular scenario is not being able to reference the [Microsoft.AspNetCore.All](https://www.nuget.org/packages/Microsoft.AspNetCore.All) meta package which only supports .NET Core 2.1 projects, instead ASP.NET .NET Standard packages will need to be referenced individually. 

To make it as easy as possible to get started you can use the [NetFrameworkCoreTemplates](https://github.com/NetFrameworkCoreTemplates) containing popular starting templates for running ASP.NET Core Apps on .NET Framework (default v4.7) which as a convention all have the `-corefx` suffix: 

 - [web-corefx](https://github.com/NetFrameworkCoreTemplates/web-corefx) - .NET Framework ASP.NET Core Website
 - [empty-corefx](https://github.com/NetFrameworkCoreTemplates/empty-corefx) - .NET Framework ASP.NET Core Single Project Website
 - [selfhost-corefx](https://github.com/NetFrameworkCoreTemplates/selfhost-corefx) - .NET Framework ASP.NET Core self-hosting Console App
 - [mvc-corefx](https://github.com/NetFrameworkCoreTemplates/mvc-corefx) - .NET Framework ASP.NET Core MVC Website
 - [razor-corefx](https://github.com/NetFrameworkCoreTemplates/razor-corefx) - .NET Framework ASP.NET Core Website with ServiceStack.Razor
 - [templates-corefx](https://github.com/NetFrameworkCoreTemplates/templates-corefx) - .NET Framework ASP.NET Core Templates Bootstrap Website

This will let you create an ASP.NET Core App running on the .NET Framework v4.7 with the [dotnet tool](/dotnet-tool):

:::sh
dotnet tool install --global x 
:::

Then create a new project with:

:::sh
x new web-corefx AcmeNetFx
:::

Which can then be opened in your preferred VS.NET or Project Rider C# IDE.

### ServiceStack features that won't be supported in .NET Core

Whilst we were able to make most of ServiceStack's features available in .NET Core there are a number of 
features that we're not able to support, these include:

 - **HttpListener** inc. all .NET 4.5 Self Host AppHosts - replaced with .NET Core's Kestrel
 - **SOAP Support** inc. WSDLs, XSDs - missing WCF implementations in .NET Core
 - **Mini Profiler** - tightly coupled to System.Web
 - **Markdown Razor** - CodeDom not available in .NET Core (vanilla Markdown still supported)
 - **ServiceStack.Authentication.OAuth2** - DotNetOpenAuth dependency not available in .NET Core
 - **ServiceStack.Authentication.OpenId** - DotNetOpenAuth dependency not available in .NET Core
 - **MVC FluentValidation Validators** - tightly coupled to old System.Web MVC
 - **ServiceStack.Razor** inc all existing `Html.*` helpers - tightly coupled to System.Web Razor

Whilst we lost our beloved **ServiceStack.Razor** support we developed a completely new implementation backed 
by .NET Core MVC where we were able to implement most of ServiceStack.Razor user-facing features
so porting should still be relatively straightforward with some minor syntax and configuration changes needed. 
This new implementation is available in **ServiceStack.Mvc** package and can be seen in action in 
the [Razor Rockstars .NET Core demo](http://razor.netcore.io).

### AppSelfHostBase Source-compatible Self-Host

The **ServiceStack.Kestrel** NuGet package encapsulates .NET Core's Kestrel HTTP Server dependency 
behind a source-compatible `AppSelfHostBase` which can be used to create source-compatible Self Hosted Apps
and is what enables the exact same .NET Framework Template's [Integration Tests](https://github.com/NetFrameworkTemplates/vue-spa-netfx/blob/master/MyApp.Tests/IntegrationTest.cs) to 
be used in .NET Core Template's [Integration Tests](https://github.com/NetCoreTemplates/vue-spa/blob/master/MyApp.Tests/IntegrationTest.cs).

### AppHostBase .NET Core Module

Whilst `AppSelfHostBase` enables the same development experience for developing Self-Hosted ServiceStack
Solutions, when developing .NET Core-only Web Apps we instead recommend inheriting from `AppHostBase` and 
registering ServiceStack as a .NET Core module in order to remain consistent with all other .NET Core solutions. 

In ASP.NET 4.5, `AppHostBase` is used to create an ASP.NET ServiceStack Host, but in .NET Core all Web Apps 
are Console Apps, `AppHostBase` in this case just refers to a normal ServiceStack `AppHost` you'll use to 
idiomatically register your ServiceStack AppHost into .NET Core's `IApplicationBuilder` pipeline as a standard 
.NET Core Module.

### Binding to .NET Core

To see how ServiceStack integrates with .NET Core we'll walk through porting the stand-alone 
[Todos Live Demo](https://github.com/NetCoreApps/Todos) which contains the entire implementation of
a functional Todos Web App back-end in a single 
[Startup.cs](https://github.com/NetCoreApps/Todos/blob/master/src/Todos/Startup.cs) that we created using 
the **ASP.NET Core Web Application (.NET Core)** Empty VS.NET Template.

```csharp
public class Program
{
    public static void Main(string[] args)
    {
        var host = new WebHostBuilder()
            .UseKestrel()
            .UseContentRoot(Directory.GetCurrentDirectory())
            .UseIISIntegration()
            .UseStartup<Startup>()
            .Build();

        host.Run();
    }
}
```

### .NET Core Startup


Alternatively you can start with any of the [.NET Core Templates](https://github.com/NetCoreTemplates/) which 
uses ASP .NET Core's recommended [Top-level statements](https://learn.microsoft.com/en-us/dotnet/csharp/fundamentals/program-structure/top-level-statements) for its [Program.cs](https://github.com/NetCoreTemplates/razor-pages/blob/main/MyApp/Program.cs) Startup class, e.g:

```csharp
var builder = WebApplication.CreateBuilder(args);

// Configure ASP .NET Core Dependencies

var app = builder.Build();

if (app.Environment.IsDevelopment())
{
    app.UseDeveloperExceptionPage();
}

//Register your ServiceStack AppHost as a .NET Core module
app.UseServiceStack(new AppHost()); 

app.Run(async (context) =>
{
    await context.Response.WriteAsync("Hello World!");
});
```

This shows the minimum code required to configure ServiceStack to run in .NET Core. It works similarly to the 
[Wildcard HttpHandler configuration](https://github.com/ServiceStackApps/Todos/blob/fdcffd37d4ad49daa82b01b5876a9f308442db8c/src/Todos/Web.config#L37) in your ASP.NET **Web.config** telling ASP.NET to route all requests to ServiceStack. The difference here 
is that ServiceStack is registered in a pipeline and only receives requests that weren't handled in any of
the preceding modules. Likewise ServiceStack will just call the next Module in the pipeline for any Requests 
that it's not configured to handle, this is in contrast to ASP.NET 4.5 where ServiceStack was designed to handle 
all requests it receives, so it instead returns a `NotFoundHandler` and responds with a 404 Response.

In the above configuration any Request that ServiceStack doesn't handle gets passed on to the next module 
registered, which in this case will return a `Hello World!` plain text response.

### .NET Core AppHost Integration

Once inside your `AppHost` you're back in ServiceStack-land where it's business as usual and your AppHost 
configuration remains the same as before: 

```csharp
// Create your ServiceStack Web Service with a singleton AppHost
public class AppHost : AppHostBase
{
    // Initializes your AppHost Instance, with the Service Name and assembly containing the Services
    public AppHost() : base("Backbone.js TODO", typeof(TodoService).Assembly) { }

    // Configure your AppHost with the necessary configuration and dependencies your App needs
    public override void Configure(Container container)
    {
        //Register Redis Client Manager singleton in ServiceStack's built-in Func IOC
        container.Register<IRedisClientsManager>(new BasicRedisClientManager("localhost"));
    }
}
```

This was all it took to port the 
[Todos back-end Services](https://github.com/NetCoreApps/Todos/blob/c742da45c9a70217980c2f2b323813fe7821df06/src/Todos/Startup.cs#L61-L110)
to run on .NET Core which was able to reuse the entire existing Service implementation as-is. 

The other change needed outside the Todos ServiceStack implementation was to match .NET Core's default convention 
of serving static files from the **WebRootPath** which just required moving all static resources into the 
[/wwwroot](https://github.com/NetCoreApps/Todos/tree/master/src/Todos/wwwroot) folder.

And with that the [Todos port](https://github.com/NetCoreApps/Todos) was complete.

## Seamless Integration with .NET Core

In addition to running flawlessly on .NET Core we're also actively striving to find how we can best 
integrate with and leverage the surrounding .NET Core ecosystem and have made several changes to that end:

### CamelCase

The JSON and JSV Text serializers are following .NET Core's default convention to use **camelCase** properties
by default. This can be reverted back to **PascalCase** with:

```csharp
SetConfig(new HostConfig { UseCamelCase = false })
```

We also agree with this default, .NET Core seems to be centered around embracing the surrounding 
developer ecosystem where .NET's default **PascalCase** protrudes in a sea of **camelCase** and 
**snake_case** JSON APIs. This won't have an impact on .NET Service Clients or Text Serialization which 
supports case-insensitive properties, however Ajax and JS clients will need to be updated to use matching properties.
You can use [ss-utils normalize()](/ss-utils-js.html#normalize-and-normalizekey) methods
to help with handling both conventions by recursively normalizing and converting all properties to **lowercase**.

### .NET Core Container Adapter

Like ServiceStack, .NET Core now has a built-in IOC where you can register any dependencies you need in
your Startup `ConfigureServices()`, e.g:

```csharp
public class Startup
{
    public void ConfigureServices(IServiceCollection services)
    {
        services.AddTransient<IFoo, Foo>()
                .AddScoped<IScoped, Scoped>()
                .AddSingleton<IBar>(c => new Bar { Name = "bar" });
    }
}
```

#### Scoped Dependencies

In .NET Core ServiceStack is pre-configured to use a `NetCoreContainerAdapter` where it will also resolve any 
dependencies declared in your .NET Core Startup using `app.ApplicationServices`. One side-effect of this is that 
when resolving **Scoped** dependencies it resolves them in a Singleton scope instead of the Request Scope had 
they instead been resolved from `context.RequestServices.GetService<T>()`.

One way to be able to inject scoped dependencies into your Services is to register the `IHttpContextAccessor`
where they'll be resolved from ASP.NET Core's RequestServices context:

```csharp
public void ConfigureServices(IServiceCollection services)
{
     services.AddHttpContextAccessor();
     services.AddScoped<IScoped, Scoped>();
}
```

Otherwise if you need to resolve Request Scoped .NET Core dependencies you can resolve them from `IRequest`, e.g:

```csharp
public object Any(MyRequest request)
{
    var requestScope = base.Request.TryResolve<IScoped>();
}
```

Alternatively you can register the dependencies in ServiceStack's IOC instead, e.g:

```csharp
public override void Configure(Container container)
{
    services.RegisterAutoWiredAs<Scoped,IScoped>()
        .ReusedWithin(ReuseScope.Request);
}
```

Where they'd be resolved within ServiceStack's Request Scope instead of via ASP.NET Core's RequestServices.

### ASP.NET Core IServiceProvider APIs

Registering dependencies in ServiceStack's IOC are only available within ServiceStack, you can access 
**scoped ASP.NET Core dependencies** and create Custom IOC Scopes using the `IRequest` APIs below:

 - `IRequest.TryResolveScoped<T>()`
 - `IRequest.TryResolveScoped()`
 - `IRequest.ResolveScoped<T>()`
 - `IRequest.ResolveScoped()`
 - `IRequest.CreateScope()`
 - `IRequest.GetServices()`
 - `IRequest.GetServices<T>()`

Which can be used to create custom scopes that utilizes ASP.NET Entity Framework Identity classes in your ServiceStack Services:

```csharp
using (var scope = Request.CreateScope())
{
    var RoleManager = scope.ServiceProvider.GetRequiredService<RoleManager<IdentityRole>>();
    var UserManager = scope.ServiceProvider.GetRequiredService<UserManager<ApplicationUser>>();

    var managerUser = await UserManager.FindByEmailAsync("manager@gmail.com");
    if (managerUser == null)
    {
        assertResult(await UserManager.CreateAsync(new ApplicationUser {
            DisplayName = "Test Manager",
            Email = "manager@gmail.com",
            UserName = "manager@gmail.com",
            FirstName = "Test",
            LastName = "Manager",
        }, "p@55wOrd"));
        
        managerUser = await UserManager.FindByEmailAsync("manager@gmail.com");
        await UserManager.AddToRoleAsync(managerUser, "Manager");
    }
}
```

### Register ASP.NET Core dependencies in AppHost

Any dependencies registered .NET Core Startup are also available to ServiceStack but dependencies registered in ServiceStack's IOC 
are **only** visible to ServiceStack.

This is due to the limitation of ASP.NET Core requiring all dependencies needing to be registered in `ConfigureServices()` before any App Modules 
are loaded and why dependencies registered in ServiceStack's AppHost `Configure()` are only accessible from ServiceStack and 
not the rest of ASP.NET Core. 

But in [Modular Startup](/modular-startup) Apps you can override ASP.NET Core's `builder.ConfigureServices(IServiceCollection)` method in your AppHost
`Configure(IWebHostBuilder builder)` to register IOC dependencies where they'll now be accessible to both ServiceStack and the rest of your ASP.NET Core App, e.g:

```csharp
[assembly: HostingStartup(typeof(MyApp.AppHost))]

namespace MyApp;

public class AppHost : AppHostBase, IHostingStartup
{
    public void Configure(IWebHostBuilder builder) => builder
        .ConfigureServices(services => {
            // Configure ASP .NET Core IOC Dependencies
        });

    public AppHost() : base("MyApp", typeof(MyServices).Assembly) {}

    public override void Configure(Container container)
    {
        // Configure ServiceStack only IOC, Config & Plugins
        SetConfig(new HostConfig {
            UseSameSiteCookies = true,
        });
    }
}
```

The `IWebHostBuilder` can also be used to hook into the `Configure(IApplicationBuilder)` to inject ASP.NET Core middleware, including ServiceStack and
 the `AppHost` itself.

::: info
Reason for only conditionally registering ServiceStack with `if (!HasInit)` is to allow other plugins (like Auth) the opportunity
to precisely control where ServiceStack is registered within its preferred ASP .NET Core's pipeline
:::

This will let you drop-in your custom `AppHost` into a [ModularStartup enabled ASP.NET Core App](/modular-startup) to enable the same 
"no-touch" auto-registration.

### .NET Core IAppSettings Adapter

.NET Core Templates are also pre-configured to use the new `NetCoreAppSettings` adapter to utilize .NET Core's new `IConfiguration` config model in ServiceStack by default.

This lets you use **appsettings.json** and .NET Core's other Configuration Sources from ServiceStack's `IAppSettings` API where it continues to resolve both primitive values and complex Types, e.g:

```csharp
bool debug = AppSettings.Get<bool>("DebugMode", false);
MyConfig myConfig = AppSettings.Get<MyConfig>();
List<string>  ghScopes = AppSettings.Get<List<string>>("oauth.github.Scopes");
IList<string> fbScopes = AppSettings.GetList("oauth.facebook.Permissions");
```

But instead of a single JSV string value, you'll need to use the appropriate JSON data type, e.g:

```json
{
    "DebugMode": true,    
    "MyConfig": {
        "Name": "Kurt",
        "Age": 27
    },
    "oauth.facebook.Permissions": ["email"],
    "oauth.github.Scopes": ["user"]
}
```

### Consistent Registration APIs

To retain the same nomenclature that .NET Core uses to register dependencies we've added several 
[Overloads to ServiceStack's IOC](https://github.com/ServiceStack/ServiceStack/blob/master/src/ServiceStack/ContainerNetCoreExtensions.cs)
letting you use a single consistent API to register dependencies in both ServiceStack and .NET Core IOC's 
making it easy to move registrations between the two, e.g:

```csharp
public void Configure(Container container)
{
    container.AddTransient<IFoo, Foo>()
             .AddScoped<IScoped, Scoped>()
             .AddSingleton<IBar>(c => new Bar { Name = "bar" });
}
```

ServiceStack's `Container` also implements .NET Core's `IServiceProvider` interface giving it access to 
.NET Core's convenience extension methods for resolving dependencies, e.g:

```csharp
var foo = container.GetService<IFoo>();
```

### ServiceStack.Logging Adapters

The default 
Logging is an example of an abstraction which didn't make sense to maintain a separate implementation 
as any adapter would only be able to support logging within ServiceStack. With logging you'll want to
configure it one place and have it apply to your whole application, so we've instead pre-configured 
ServiceStack.Logging to proxy all messages to .NET Core's 
[logging abstraction](https://docs.asp.net/en/latest/fundamentals/logging.html)
where you'll only need to configure logging once in `Startup` and have it handle all logging solution-wide.


### .NET Standard 2.0 Logging Providers

Whilst our recommendation is to use .NET Core's Logging Abstraction, if you prefer you can avoid this abstraction and 
configure logging with ServiceStack directly with the logging providers below which maintains **.NET Standard 2.0** versions:

 - ServiceStack.Logging.Serilog
 - ServiceStack.Logging.Slack

### WebRootPath and ContentRootPath

Classic ASP.NET serves static resources from your Host project's folder but in .NET Core this has been moved 
to your App's `/wwwroot` folder, separated from your App's non-public assets which remain in
your projects root folder.

To match this convention we've configured the read-only `VirtualFileSources` to point to the `/wwwroot` 
**WebRootPath** whilst the read/write `IVirtualFiles` is configured to your projects **ContentRootPath** folder.

#### MapProjectPath

As ServiceStack can be hosted in variety of different platforms encompassing several AppHost's, we've
added a new `IAppHost.MapProjectPath()` API that can be used to consistently resolve an absolute file path 
using a **virtualPath** from your Host Project root folder, e.g:

```csharp
var filePath = appHost.MapProjectPath("~/path/to/settings.txt");
```

### Hosting ASP.NET Core Apps on Custom Path

Use the `PathBase` property on AppHost for hosting a ServiceStack .NET Core App at a custom path, e.g:

```csharp
app.UseServiceStack(new AppHost {
    PathBase = "/api",
});
```

Resulting in both `Config.PathBase` and `Config.HandlerFactoryPath` getting populated with and without the `/` suffix:

```csharp
Config.PathBase           //= /api
Config.HandlerFactoryPath //= api
```

When necessary the `PathBase` property is available in both server rendered views:

::: v-pre
  - `{{PathBase}}` variable in [#Script Pages](https://sharpscript.net/docs/script-pages)
  - `PathBase` in Razor Views
:::

### HostContext.TryGetCurrentRequest()

ASP.NET Web Applications let you resolve the `IRequest` of the current executing HTTP Request with:

```
IRequest req = HostContext.TryGetCurrentRequest();
```

Which is a wrapper over accessing the `HttpContext.Current` singleton but as there's no equivalent in 
HttpListener self hosts this returns `null`. .NET Core also doesn't enable singleton access to the current 
HttpRequest by default but can be enabled by registering:

```csharp
services.AddSingleton<IHttpContextAccessor, HttpContextAccessor>();
```

Although this should only be registered if needed as it has 
[non-trivial performance costs](https://github.com/aspnet/Hosting/issues/793).

### OrmLite LIKE Queries

One of our primary goals with ServiceStack providers is compatibility which lets you easily switch 
providers without having to change any call-site logic using the abstraction.

One case where this has an impact on performance is in OrmLite **LIKE** queries where some RDBMS 
providers will perform case-sensitive LIKE queries so in order to retain consistent behavior across 
all RDBMS providers OrmLite generates queries using `UPPER(Field)` to ensure case-insensitive searches. 

However given .NET Core's strong focus on performance we've removed this feature and reverted to the 
behavior of the underlying RDBMS so it no longer invalidates any DB Indexes on Fields. A more efficient 
alternative to get case-insensitive LIKE queries (where it's not the default) is to use a case-insensitive 
collation.

This behavior also applies to AutoQuery LIKE queries and can be reverted with:

```csharp
OrmLiteConfig.StripUpperInLike = false;
```

### Register ServiceStack HttpHandlers as .NET Core Modules

Under the hood ServiceStack's functionality is split into different HTTP Handlers that implements 
[ASP.NET's IHttpAsyncHandler](https://msdn.microsoft.com/en-us/library/ms227433.aspx) and is also adapted to 
support HttpListener self-hosts behind ServiceStack's `IRequest` abstractions. 

We're happy to report that ServiceStack's HTTP Handlers can also be registered as a .NET Core module in 
the `IApplicationBuilder` pipeline. This lets you for instance return the same information as ServiceStack's
[?debug=requestinfo](/debugging.html#request-info) route for any unhandled 
requests by registering the `RequestInfoHandler` as the last module in .NET Core's `IApplicationBuilder` 
pipeline, e.g:

```csharp
app.UseServiceStack(new AppHost());

app.Use(new RequestInfoHandler());
```

Some other examples of HTTP Handlers you could use is returning an image by registering a `StaticFileHandler`
configured with the **virtualPath** of the image (from **ContentRootPath**):

```csharp
app.Use(new StaticFileHandler("wwwroot/img/404.png"));
```

Or you can even render an MVC Razor View by returning it in a `RazorHandler`, e.g:

```csharp
app.Use(new RazorHandler("/login"));
```

Which will render the `/wwwroot/login.cshtml` Razor Page using the 
[MVC Smart Razor Pages support](/netcore-razor)

# Community Resources

  - [ASP.NET Core 2 + React + Docker + ServiceStack](https://medium.com/@williams.jackj/asp-net-core-2-react-docker-servicestack-96be42933e86) by [@jackkedd](https://twitter.com/jackkedd)


# ServiceStack.Redis on .NET Core
Source: https://docs.servicestack.net/netcore-redis

Documentation for ServiceStack.Redis can be found on [ServiceStack.Redis Project Page](https://github.com/ServiceStack/ServiceStack.Redis).

The [ServiceStack.Redis](https://www.nuget.org/packages/ServiceStack.Redis) NuGet package supports both .NET Framework and .NET Core Applications:

:::copy
`<PackageReference Include="ServiceStack.Redis" Version="8.*" />`
:::

Use [ServiceStack.Redis.Core](https://www.nuget.org/packages/ServiceStack.Redis.Core) instead if you're running 
[ASP.NET Core Apps on the .NET Framework](/templates/corefx)

:::copy
`<PackageReference Include="ServiceStack.Redis.Core" Version="8.*" />`
:::

### Basic Example

```csharp
using System;
using ServiceStack.Redis;

namespace MyApp
{
    public class Program
    {
        public static void Main(string[] args)
        {
            var manager = new RedisManagerPool("localhost:6379");
            using (var client = manager.GetClient())
            {
                client.Set("foo", "bar");
                Console.WriteLine("foo={0}", client.Get<string>("foo"));
            }
        }
    }
}
```

Then hit "run" button **(F5)**. You should get following output:

![Output](/img/pages/8-Output.png)

## Run ServiceStack.Redis on Linux

### Install .NET Core

Suppose that you have Ubuntu 19.10 installed (to see installation instructions for other OS you can 
visit [.NET Core site](https://www.microsoft.com/net/core). Run commands in the console:

#### Register Microsoft key and feed

```
wget https://packages.microsoft.com/config/ubuntu/19.10/packages-microsoft-prod.deb -O packages-microsoft-prod.deb
sudo dpkg -i packages-microsoft-prod.deb    
```

#### Install the .NET Core SDK

```
sudo apt-get update
sudo apt-get install apt-transport-https
sudo apt-get update
sudo apt-get install dotnet-sdk-3.1
```


# Configure localhost development dev certificate
Source: https://docs.servicestack.net/netcore-localhost-cert

Due to the environmental pressures to [use HTTPS everywhere](https://web.dev/why-https-matters/) with 
[Browsers marking HTTP as not secure](https://blog.google/products/chrome/milestone-chrome-security-marking-http-not-secure/) and 
[operating systems and mobile platforms](https://developer.apple.com/documentation/security/preventing_insecure_network_connections) requiring
all connections to be secure by default, it's become the defacto standard to both host production sites with HTTPS as well as
[developing locally under HTTPS with a Self-Signed Certificate](https://www.hanselman.com/blog/DevelopingLocallyWithASPNETCoreUnderHTTPSSSLAndSelfSignedCerts.aspx).

In most cases it's sufficient to run .NET Core Apps on `https://localhost:5001` for normal browser development and if you receive an invalid certificate
error you can run:

:::sh
dotnet dev-certs https --trust
:::

To trust the local development certificate and remove the SSL Certificate error in your browser.

## When localhost is not allowed

However for Apps needing to support OAuth providers that don't allow `localhost` domains like **Sign In with Apple** you would need
to use a different domain. A popular workaround is to use a DNS name that resolves to `127.0.0.1` in which case you can use:

```
local.servicestack.com
```

Which you can use to view your local Web App typically on `https://localhost:5001` at `https://local.servicestack.com:5001` which
will allow you to register as valid domains & callback URLs in OAuth Apps you want to support. As this is a real DNS A record
it will also work in emulators & different environments like WSL.

## When developing for Android

But to be able to access your local dev server from an Android Emulator you'd instead need to use the special `10.0.2.2` loopback
IP, which you could support by [updating your Android Emulator /system/etc/hosts file](https://stackoverflow.com/a/53929946/85785)
mapping to include:

```
10.0.2.2       local.servicestack.com
```

Which can be quite cumbersome to change, alternatively an easier solution is to use a DNS record that resolves to `10.0.2.2`:

```
dev.servicestack.com
```

and instead update your OS hosts file (e.g. `%SystemRoot%\System32\drivers\etc\hosts` for Windows or `/etc/hosts` on macOS/Linux) to include:

```
127.0.0.1       dev.servicestack.com
```

Which will let you use the same `dev.servicestack.com` to access your local dev server in both Android Emulators and your Host OS 
so you can have a single domain & callback URL you can use in your OAuth Apps configuration.

## When developing for iOS

As iOS is a heavily locked down OS you wont have the same opportunity to modify iOS's hosts file, instead the easiest way to configure 
a custom address for a given domain is to configure it on the DNS Server. Fortunately this easy to setup in macOS with a 
[lightweight, easy to configure DNS Server like Dnsmasq](https://passingcuriosity.com/2013/dnsmasq-dev-osx/) which lets
you easily add custom DNS rules whilst falling back to use its default DNS resolution for non-configured addresses.

The easiest way to install Dnsmasq on macOS is to use [Homebrew](https://brew.sh):

:::sh
brew install dnsmasq
:::

Once installed copy over the default configuration files:

```bash
cp $(brew list dnsmasq | grep /dnsmasq.conf.example$) /usr/local/etc/dnsmasq.conf
sudo cp $(brew list dnsmasq | grep /homebrew.mxcl.dnsmasq.plist$) /Library/LaunchDaemons/
```

Then configure Dnsmasq to start automatically by registering it with **launchd**:

:::sh
sudo launchctl load /Library/LaunchDaemons/homebrew.mxcl.dnsmasq.plist
:::

The easiest to configure the IP Address for a single domain is to still add it to `/etc/hosts`, e.g. if your local ASP.NET
dev server is on a different server to your macOS being used to develop/test iOS Apps, you would use that IP Address instead:

```
192.168.0.2     dev.servicestack.com
```

Alternatively you can maintain these rules in Dnsmasq's config which offers far greater flexibility:

:::sh
sudo vi /usr/local/etc/dnsmasq.conf
:::

```
address=/dev.servicestack.com/192.168.0.2
```

In which case you'll also want to update the OS's resolver config to 
[query your local DNS Server when resolving these addresses](https://www.stevenrombauts.be/2018/01/use-dnsmasq-instead-of-etc-hosts/#2-only-send-test-and-box-queries-to-dnsmasq).

### Restart Dnsmasq to apply changes

After making changes to your DNS configuration, restart dnsmasq for it to take effect:

```bash
sudo launchctl stop homebrew.mxcl.dnsmasq
sudo launchctl start homebrew.mxcl.dnsmasq
```

### Update iOS to use your custom DNS Server

First find out the current IP Address of your macOS instance:

:::sh
ipconfig getifaddr en0
:::

Which you can get your iOS development device to use by going into your **Wi-Fi** Network Info in iOS **Settings**:

![](/img/pages/dev/ios-network-info.jpeg)

Going to **Configure DNS**:

![](/img/pages/dev/ios-wifi-info.png)

Then switching to use **Manual** DNS servers and adding your macOS IP Address where it will now be used to resolve DNS queries:

![](/img/pages/dev/ios-configure-dns.jpeg)

## Generating self-signed SSL Certificates for Custom Domains

Whether you use `local.servicestack.com` or `dev.servicestack.com` or your own hostname, you'll need to create and trust
a self-signed certificate to be able to view it in a browser without certificate errors.

To simplify creation of self-signed certificate for `*.servicestack.com` you can use the [dotnet mix tool](/mix-tool)
to download the openssl script and running it:

```bash
x mix gen-dev-crt.sh
bash gen-dev-crt.sh
```

Which will write this script below to your projects HOST project:

```csharp
PASSWORD=dev
if [ $# -ge 1 ]
  then
    PASSWORD=$1
fi

openssl req -x509 -out dev.crt -keyout dev.key -days 825 \
  -newkey rsa:2048 -nodes -sha256 \
  -subj '/CN=*.servicestack.com' -extensions EXT -config <( \
   printf "[dn]\nCN=*.servicestack.com\n[req]\ndistinguished_name = dn\n[EXT]\nsubjectAltName=DNS:*.servicestack.com\nkeyUsage=digitalSignature\nextendedKeyUsage=serverAuth")

openssl pkcs12 -export -out dev.pfx -inkey dev.key -in dev.crt -password pass:$PASSWORD
```

Which uses OpenSSL to generate a self-signed certificate `dev.crt`, private key `dev.key` and a PKCS #12 `dev.pfx` certificate in macOS, Linux & Windows using WSL.

### Trust self-signed certificate

After generating a new self-signed certificate you'll need to trust it in your OS's certificate store so it's recognized & treated as a valid certificate.

#### Windows

On Windows you can trust certificates by running the powershell command below in **Administrator** mode:

```
Import-Certificate -FilePath dev.crt -CertStoreLocation Cert:\CurrentUser\Root
```

Where it will import the Certificate into the [Current User Certificate Store](https://docs.microsoft.com/en-us/windows/win32/seccrypto/system-store-locations#cert_system_store_current_user)
which you can view/remove in **regedit.msc** at:

```
Computer\HKEY_CURRENT_USER\SOFTWARE\Microsoft\SystemCertificates\Root\Certificates\
```

#### macOS

In macOS you can [add a trusted root certificate to your System.keychain](https://derflounder.wordpress.com/2011/03/13/adding-new-trusted-root-certificates-to-system-keychain/) with:

:::sh
sudo security add-trusted-cert -d -r trustRoot -k "/Library/Keychains/System.keychain" dev.crt
:::

#### Linux

Unfortunately it's not as cohesive in Linux where different Distro's & Apps handle it differently, however this existing answer
covers [installation in Debian/Ubuntu distributions](https://unix.stackexchange.com/a/90607/698).

### Configure in .NET Core

You can configure the .NET Core to use this self-signed certificate during development by specifying the path to `dev.pfx` and the password used
in your `appsettings.Development.json`:

```json
{
  "Kestrel": {
    "Endpoints": {
      "Http": {
        "Url": "https://*:5001",
        "Protocols": "Http1",
        "Certificate": {
          "Path": "dev.pfx",
          "Password": "dev"
        }
      }
  }
}
```

### Accessing from Browsers

Now after restarting your browser to reset its SSL caches you'll be able to use either `*.servicestack.com` domains to view your local development without SSL Errors:

![](/img/pages/security/dev-certs.png)

### Accessing from C# Clients

As .NET has access your OS's trusted certificates you'll be able to access the custom domains without additional configuration:

```csharp
var client = new JsonApiClient("https://dev.servicestack.com:5001"); //.NET HttpWebRequest
var response = await client.GetAsync(new Hello { Name = "World" });

var client = new JsonHttpClient("https://dev.servicestack.com:5001");    //.NET HttpClient
var response = await client.GetAsync(new Hello { Name = "World" });
```

### Accessing from Native Applications

Something you want to avoid is including your [certificate & private key with your Native application](https://letsencrypt.org/docs/certificates-for-localhost/#for-native-apps-talking-to-web-apps)
which is considered a compromise of your private key that attackers can use to implement a successful [MitM attack](https://en.wikipedia.org/wiki/Man-in-the-middle_attack).

### Flutter Android

Instead you'll want to either [install the self-signed certificate](https://blog.netspi.com/four-ways-bypass-android-ssl-verification-certificate-pinning/) on your local
device/emulator where it wont be trusted by anyone else.

Otherwise a far easier solution is to ignore SSL certificates when accessing your local dev server which you can do with Dart/Flutter using the `HttpClient` 
[badCertificateCallback](https://api.flutter.dev/flutter/dart-io/HttpClient/badCertificateCallback.html) property:

```dart
var httpClient = new HttpClient()
    ..badCertificateCallback =
        ((X509Certificate cert, String host, int port) => host == 'dev.servicestack.com' && port == 5001);
```

Although ideally you'd use a constant value like [kDebugMode](https://api.flutter.dev/flutter/foundation/kDebugMode-constant.html) so that
the `badCertificateCallback` pass-through doesn't make it into production builds. Here's an example configuring a [ServiceStack Dart Service Client](/dart-add-servicestack-reference)
to use development or production APIs:

```dart
var client = kDebugMode
    ? ClientFactory.createWith(ClientOptions(baseUrl:'https://dev.servicestack.com:5001', ignoreCert:true))
    : ClientFactory.create('https://prod.app');

var response = await client.get(Hello()..name=='World');
```

### Removing Certificate Artifacts

If you're only using Windows you'll typically only end up using the PKCS #12 `dev.pfx` certificate combining both certificate & private key 
which can be safely removed to clear unnecessary generated artifacts & clear-text copy of the private key:

```bash
del dev.key
del dev.crt
```

Where as other OS's predominantly use Certificates & Private Keys, which if needed can be later extracted from the `dev.pfx`:

#### Extract Certificate

:::sh
openssl pkcs12 -in dev.pfx -clcerts -nokeys -out dev.crt
:::

#### Extract Private Key

:::sh
openssl pkcs12 -in dev.pfx -nocerts -nodes | openssl rsa -out dev.key
:::


# Deploying .NET Core Apps to Amazon Linux 2 AMI
Source: https://docs.servicestack.net/deploy-netcore-to-amazon-linux-2-ami

A common way for reliably hosting .NET Core Apps on Linux is to use [supervisor](http://supervisord.org/index.html) to monitor the `dotnet` self-hosting processes behind an nginx reverse proxy which handles external HTTP requests to your website and proxies them to the dotnet process running your Web App on a local port. You'll need access to a Unix environment on your client Desktop, either using Linux, OSX or [Installing Windows Subsystem for Linux (WSL)](https://github.com/ServiceStack/redis-windows#option-1-install-redis-on-ubuntu-on-windows).

## Amazon Linux 2

[Amazon Linux 2](https://aws.amazon.com/amazon-linux-2/) is the next-generation Amazon Linux operating system that provides modern application 
environment with the latest enhancements from the Linux community and offers long-term support.

It is optimized for use in Amazon EC2 with a latest and tuned Linux kernel version. As a result, many customer workloads perform better on Amazon Linux 2. 

We'll start by SSH'ing into your Amazon Linux server, e.g:

```bash
ssh -i ~/pem/<my>.pem ec2-user@ec2-<ip-address>.compute-1.amazonaws.com
```

### Install .NET 6.0

Being based on RHEL you can use yum and the [Cent OS 7 Install Instructions](https://docs.microsoft.com/en-us/dotnet/core/install/linux-centos#centos-7-)
to install .NET Core on Amazon Linux 2:

:::sh
sudo rpm -Uvh https://packages.microsoft.com/config/centos/7/packages-microsoft-prod.rpm
:::

If you just want a minimal ASP.NET Core runtime to run Web Apps you can just install:

:::sh
sudo yum install aspnetcore-runtime-6.0
:::

But if you'd also like to use dotnet tools like the [x super utility](/dotnet-tool) you'll need to install the SDK:

:::sh
sudo yum install dotnet-sdk-6.0
:::

Then install dotnet tools you want which will install under the `ec2-user` home directory at `~/.dotnet/tools`:

:::sh
dotnet tool install --global x
:::

You'll either need to exit & re login to configure the dotnet tool path or you can import it manually with:

:::sh
. /etc/profile.d/dotnet-cli-tools-bin-path.sh
:::

Where you should now be able be able to run dotnet tools, e.g:

:::sh
x
:::

### Setup the deploy User Account

We'll then create a dedicated user account for hosting and running your .NET Core Apps to mitigate potential abuse. 
Create the `deploy` user account with a `/home/deploy` home directory and add them to the `sudo` group:

:::sh
sudo useradd -m deploy
:::

Create a password (optional):

:::sh
sudo passwd deploy
:::

For seamless deployments use `visudo`:

:::sh
sudo visudo
:::

To allow `deploy` to run `supervisorctl` without prompting for a password:

```ini
## Same thing without a password
# %wheel        ALL=(ALL)       NOPASSWD: ALL
%deploy ALL=(ALL:ALL) NOPASSWD: /usr/bin/supervisorctl
```

To give `sudo` commands access to installed dotnet tools add it to `secure_path`:

```ini
Defaults    secure_path = /sbin:/bin:/usr/sbin:/usr/bin:/home/ec2-user/.dotnet/tools
```

::: info Tip
In vi type `i` to start editing a file and `ESC` to quit edit mode and `:wq` to save your changes before exiting
:::

Now we'll create an `~/apps` folder as the `deploy` user where your .NET Core Apps should be deployed to, e.g:

```bash
sudo su - deploy
mkdir ~/apps
exit
```

### Setup supervisor

Install **supervisor** on Amazon Linux 2 by first [enabling the EPEL repository](https://aws.amazon.com/premiumsupport/knowledge-center/ec2-enable-epel/):

:::sh
sudo amazon-linux-extras install epel
:::

Then use `yum` to install `supervisor`

:::sh
sudo yum install supervisor
:::

You'll also need to create a `supervisord.service` systemd script which you can install with:

:::sh
sudo x mix supervisord.service
:::

Which will write this [supervisord.service](https://gist.github.com/gistlyn/18dbaa471ea09f744493d5866ede599e) gist to `/usr/lib/systemd/system`.

We'll also want to configure supervisor to look for our `*.conf` scripts in the conventional location:

:::sh
echo 'files = /etc/supervisor/conf.d/*.conf' | sudo tee -a /etc/supervisord.conf
:::

We can then enable & start the systemd supervisord.service with:

```bash
sudo systemctl enable supervisord.service
sudo systemctl start supervisord
```

You'll then need to create a separate config file for each app in `/etc/supervisor/conf.d/`. 

We can use the same template below by replacing `my-app` with the name of your App:

#### /etc/supervisor/conf.d/app.my-app.conf 

```ini
[program:app-my-app]
command=/usr/local/bin/dotnet /home/deploy/apps/my-app/MyApp.dll
directory=/home/deploy/apps/my-app
autostart=true
autorestart=true
stderr_logfile=/var/log/app-my-app.err.log
stdout_logfile=/var/log/app-my-app.out.log
environment=ASPNETCORE_ENVIRONMENT=Production,ASPNETCORE_URLS="http://*:5000/"
user=deploy
stopsignal=INT
```

We can use [x mix](/mix-tool) to simplify this by downloading & renaming the `supervisor` configuration template above:

:::sh
sudo x mix supervisor -name acme
:::

You can further customize the template by adding any number of `-replace term=with` switches, e.g. you can replace the `port` with:

:::sh
sudo x mix supervisor -name acme -replace 5000=5002
:::

Then tell supervisor to register our App configuration:

:::sh
sudo supervisorctl update
:::
        
### Setup nginx

Use `yum` to install nginx:

:::sh
sudo yum install nginx
:::

### Start nginx

:::sh
sudo systemctl start nginx.service
:::

### Create Virtual Host Configuration

You'll also need to create a separate config for each website on nginx in `/etc/nginx/conf.d/`. You can use the same template for each website but you'll need to change the server_name with the domain name you want to use for the App and use a different port number for each App:

### /etc/nginx/conf.d/my-app.org.conf

```nginx
server {
    listen       80;
    server_name my-app.org;

    location / {
        proxy_pass http://localhost:5000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection keep-alive;
        proxy_cache_bypass $http_upgrade;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_buffering off;
        proxy_ignore_client_abort off;
        proxy_intercept_errors on;

        client_max_body_size 500m;
    }
}
```

Or use [x mix](/mix-tool) to write the above template using your preferred **port** and **TLD** with:

:::sh
sudo x mix nginx-yum -name acme -replace 5000=5002 -replace org=io
:::

After this we can tell nginx to reload its configuration, as there's nothing listening to `http://localhost:5002` yet nginx will return a 502 Bad Gateway response but will start working as soon as our deployed .NET Core Apps are up and running.

:::sh
sudo nginx -s reload
:::

### Setting up SSH keys

We can now exit our remote Linux server and return to our local machine and prepare our deployment script. Before doing this we recommend [setting up SSH and copying your SSH public key to your remote server](https://www.digitalocean.com/community/tutorials/how-to-set-up-ssh-keys--2) which is both more secure and more convenient than using a password. You'll want to configure the `~/.ssh/authorized_keys` for your `deploy` user account as well as `ec2-user` account for convenience.

A manual 'tool-free' solution if you're using WSL is to copy your SSH public key to the clipboard, e.g:

:::sh
cat ~/.ssh/id_rsa.pub | clip.exe
:::

Then as the `deploy` user paste the contents of `id_rsa.pub` to `/home/deploy/.ssh/authorized_keys` and ensure it has the correct restrictive permissions:

```bash
mkdir ~/.ssh
vi ~/.ssh/authorized_keys
# i + paste clipboard + <esc>:wq
chmod 700 ~/.ssh
chmod 600 ~/.ssh/authorized_keys
```

### Create the deployment script

[rsync](https://rsync.samba.org/) is a beautiful utility that provides a fast, secure file transfer over SSH which you can use to sync the contents of folders to a remote site. There's only 2 commands you need to run to deploy a local .NET Core App remotely, `rsync` to sync the published .NET Core App files and `supervisorctl` to restart the `supervisord` process that runs and monitor the .NET Core App which you can add to a [deploy.sh](https://github.com/NetCoreApps/TechStacks/blob/master/src/TechStacks/deploy.sh) that you can run with WSL bash:

```bash
rsync -avz -e 'ssh' bin/Release/net5/publish/ deploy@ec2-<ip-address>.compute-1.amazonaws.com:/home/deploy/apps/acme
ssh deploy@ec2-<ip-address>.compute-1.amazonaws.com "sudo supervisorctl restart app-acme"
```

To automate the entire deployment down to a single command you can add an npm script to your project's `package.json` that creates a production client and server build of your App before running WSL's `bash` to run the deploy script. All [Webpack Single Page App Templates](/templates/single-page-apps) already have a **publish** npm script, so you would just need to add a **deploy** script to run publish before running the above `deploy.sh`

```json
{
    "publish": "dotnet publish -c Release",
    "deploy": "npm run publish && bash deploy.sh",
}
```

Now to deploy your App you can just run:

:::sh
npm run deploy
:::

Which deploys your published App to your remote Linux server instance using `rsync` to only copy the incremental parts of the App that's changed (typically completing in <1s) and `ssh` to run a remote command to restart the `suprvisord` process, starting the .NET Core App with the latest deployed version.

After you deploy your and restart your `supervisor` Service your .NET Core App should now be publicly available at your chosen domain, if you have issues
you can view your App's error log for info, e.g:

:::sh
tail -n 50 /var/log/app-[my-app].err.log
:::

### Setup Lets Encrypt

If you're configuring an Internet Website you'll also likely want to configure it to use SSL, the easiest & free way is to use 
[letsencrypt.org](https://letsencrypt.org/) which you can install with:

:::sh
sudo yum install certbot python2-certbot-nginx 
:::

Then use `certbot` to automatically configure the domains you want to configure to use SSL, e.g:

:::sh
sudo certbot -d acme.io -d www.acme.io
:::

Now you're .NET Core creation should be accessible via `https://` & the shiny new secure badge in the users Browsers URL.


# Deploy .NET Core with Docker to EC2 Container Service
Source: https://docs.servicestack.net/deploy-netcore-docker-aws-ecs

![](/img/pages/aws/ecs/ecs-banner.png)

One of the primary benefits of [.NET Core's](https://www.microsoft.com/net/core) first-class 
support for Linux is being able to leverage the thriving ecosystem that's formed around automating, 
deploying and hosting Server Apps on Linux. Whilst there have been a number of deployment strategies 
that have been adopted over the years, the current state-of-the-art is the standardization around the 
[Docker container format](https://www.docker.com/) which hits the sweet spot of providing isolation within 
a minimal footprint over encapsulating your App and its dependencies which is contrast to including an entire 
Operating System when using VM's. In addition to being lightweight and efficient to run, Docker also enables 
fast, reproducible builds where your entire App's Image can be rebuilt by your CI Server on each 
check-in - bringing the same benefits of version control and continuous integration on your code to your 
Server infrastructure - which can now be easily be versioned, replicated, scaled and automated.

Once built, your Docker App is treated like an opaque Image where the fact it's running .NET Core 
instead of a pure LAMP stack becomes a transparent implementation detail that doesn't impact the utility 
of your App, who are both able to equally benefit from Docker's rich ecosystem. 
E.g. your Docker App can be uploaded to any public Docker repository where it can be easily shared and 
run on any [supported Linux Distrobution](https://docs.docker.com/engine/installation/linux/).
In addition to being able to run any published Docker image on any Docker-enabled OS, you're also
able to use it as a the source image for your own custom Docker Image, a feature that you'll take 
advantage of when building your own .NET Core Docker App which is based on Microsoft's 
[microsoft/dotnet](https://hub.docker.com/r/microsoft/dotnet/) Docker Image that's published on 
[Docker's public repository](https://hub.docker.com/explore/).

## Native Docker Integration in the Cloud

As the premier Container format for packaging Server Apps, all major cloud providers include native
support for Docker that goes beyond the basic hosting of Docker Images to also include repository management, 
monitoring, inspection and orchestration which lets you easily (or automatically) scale your Docker App on 
a managed cluster of VMs. You can learn more about the Docker integration offerings of the major Cloud 
providers in the links below:

 - **AWS** - [Amazon EC2 Container Service](https://aws.amazon.com/ecs/) 
 - **Azure** - [Azure Container Service](https://azure.microsoft.com/en-us/services/container-service/) 
 - **Google Cloud** - [Google Container Engine](https://cloud.google.com/container-engine/) 

Whilst other popular Cloud providers like [Digital Ocean](https://www.digitalocean.com) make it trivial to 
[setup a Docker Server in seconds](https://www.digitalocean.com/products/one-click-apps/docker/).

## AWS EC2 Container Service 

For this guide we'll walk through how we've deployed our 
[.NET Core Live Demos](https://github.com/NetCoreApps/LiveDemos) using the popular power combo of:

 - Using [travis-ci.org](https://travis-ci.org/) (free for OSS projects) for running CI scripts to rebuild Docker App Images on every check-in
 - Using [AWS EC2 Container Service](https://aws.amazon.com/ecs/) for managing Docker images and instance deployments
 - Using [nginx-proxy](https://github.com/jwilder/nginx-proxy) setting up an nginx reverse proxy and automatically bind virtual hosts to Docker Instances

We'll also look at covering [Azure Container Service](https://azure.microsoft.com/en-us/services/container-service/) 
in future as it's another popular option for deploying and hosting .NET Core Docker Apps.

## Deploying to AWS Container Service Overview

In this guide we'll go through setting up your AWS Account to enable Docker deployments using AWS EC2 
Container Service and have them deploy to a single EC2 Instance for optimal value and minimal cost. There's 
[no additional cost for using AWS's EC2 Container Service](https://aws.amazon.com/ecs/pricing/) beyond the
cost of the EBS and EC2 resources for storing and running your Docker Containers. Thanks to the 
small footprint of Docker Containers and .NET Core's lean profile you'll be able to host a few small 
Docker Apps on a **T2 Micro** instance costing less than **<$10 per month** or if you haven't created an 
account with AWS before, you can run it **free for 12 months** courtesy of [AWS Free Tier](https://aws.amazon.com/free/).

### Deploying fork of redis-geo .NET Core App

We'll be deploying a fork of the .NET Core [Redis GEO Live Demo](https://github.com/NetCoreApps/redis-geo) 
as it's a good representative of a small multi-project .NET Core solution that requires an external Redis 
Server infrastructure dependency which we'll deploy alongside our App in a separate Docker container. 

We'll use [Travis CI](https://travis-ci.org/) to do the actual build and deployments by running the 
plain bash scripts that lives alongside your code in the same 
[Github Repo](https://github.com/NetCoreApps/redis-geo) which builds and deploys your Docker App. 
Most of the bash scripts are generic and can be reused for deploying different projects with only minor config 
changes to specify the solution to build and the AWS Account to deploy to, with any sensitive information 
maintained in Travis-CI private Environment Variables so they're kept out of the public Github repositories. 

### Running build scripts locally

A nice property of using plain Bash scripts to build Docker images is being able to run them locally where 
you can run the resulting Docker Image natively on your Linux Dev or OSX workstation with
[Docker for Mac](https://docs.docker.com/engine/installation/mac/) which is nicely integrated courtesy of
OS X's built-in Bash support. Whilst less integrated, there's also support for building and running Docker 
Images with [Docker for Windows](https://docs.docker.com/docker-for-windows/).

### Walkthrough Overview

The basic steps for deploy your .NET Core App with Docker that's covered in this guide include:

 1. Creating a `ecsInstanceRole` Role that your **EC2 Instance** will run as
 2. Creating a `ecsDemoUser` User for remotely running AWS CLI utils to deploy to your AWS Account
 3. Launching a new **EC2 Instance** with the `ecsInstanceRole` Role to use as your Docker Server
 4. Configuring DNS and associating an **Elastic IP** to the new **EC2 Instance**
 5. SSH into the **EC2 Instance** to run the `nginx-proxy` Docker Container
 6. Forking the `redis-geo` Github project
 7. Configure **Travis CI** to deploy your `redis-geo` fork to your AWS ECS Service
 8. Playing with your deployed .NET Core Docker App!

Whilst this may seem like a lot of effort to deploy a Docker App, most of the above steps only need to be done 
once - only **steps 6-8** are repeatable for each new project that you want to deploy to your ECS Container 
EC2 Instance.

At the end of the rainbow an instance of **your redis-geo fork** .NET Core App will be running on your
AWS **EC2 Instance**, re-deployed on every check-in by triggering **Travis CI** into action to rebuild and 
package the latest version of your App in a new Docker App Image that it also publishes to your ECS Service. 

ECS also maintains a complete history of every Docker App Image and related task definition deployed in 
its private Docker Repository. ECS also lets you inspect your running EC2 Instance to see how much CPU 
and memory is used - providing valuable insight in how many more Docker Apps you'll be able to pack into 
your EC2 Instance.

Now we know what we're getting, let's jump in!

## 1. Create the `ecsInstanceRole` Role

Our first port of call is to create a new `ecsInstanceRole` in IAM, this is a 
[special Role for EC2 Container Instances](http://docs.aws.amazon.com/AmazonECS/latest/developerguide/instance_IAM_role.html)
that contains the necessary permissions for your EC2 Instance to communicate with the ECS API. 

When launching a new EC2 Instance with the `ecsInstanceRole`, it will automatically create the 
**default cluster** in ECS and registers itself to the set of EC2 instances that are available to run 
Docker Apps deployed to that cluster.

Creating new Roles are done within **Identity & Access Management (IAM)** in your AWS dashboard under the 
**Roles** tab which you can jump directly to using the deep link:
[https://console.aws.amazon.com/iam/home#roles](https://console.aws.amazon.com/iam/home#roles). 
Then click on **Create New Role** button to start the Create Role Wizard:

Type `ecsInstanceRole` for the **Role Name** then click **Next Step**:

![](/img/pages/aws/ecs/role-01.png)

Select the **Amazon EC2 Role for EC2 Container Service** Role Type:

![](/img/pages/aws/ecs/role-02.png)

You'll also need to attach the `AmazonEC2ContainerServiceforEC2Role` policy which you can quickly find by 
pasting it in the **Policy Type** filter and selecting the only result and proceeding to the **Next Step**:

![](/img/pages/aws/ecs/role-03.png)

The last page in the Wizard lets you review details of the Role you'll creating after clicking **Create Role**:

![](/img/pages/aws/ecs/role-04.png)

The new `ecsInstanceRole` will be available in the **Roles** tab which you can click on to open its Detail View:

![](/img/pages/aws/ecs/role-05.png)

## 2. Create a new IAM User 

We now need to create a new User in IAM to allow remote Servers we want to access our ECS Container Service. 
**Travis CI** needs to authenticate as this User in order to use the [AWS CLI](https://aws.amazon.com/cli/) 
utils so it can deploy our Docker App to our ECS **default** Cluster.

Similar to creating a role, to create a new User select the **Users** tab then click **Create New Users**.
On the next screen add your preferred Username for this new User in the first textbox then click **Create**: 

![](/img/pages/aws/ecs/user-01.png)

You'll need to copy both the **Access Key ID** and **Secret Access Key** which is **only available** 
from the next screen. These credentials **need to be saved** as you'll need to configure it with 
**Travis CI** later so it can authenticate as this new User. 

![](/img/pages/aws/ecs/user-02.png)

We also need to assign the following permissions to the new User to give it access to our ECS Service.
The easiest way to select these policies is to copy each into the **Policy Type** Filter then select
the filtered result, you'll need to do this for each of the policies below:

 1. `AmazonEC2ContainerRegistryFullAccess`
 2. `AmazonEC2ContainerServiceFullAccess`
 3. `AmazonEC2ContainerServiceRole`

After clearing the filter you should see 3 Policies selected, then click **Attach Policy** to add them 
to the User.

![](/img/pages/aws/ecs/user-03.png)

As the names were cropped in the previous screen, double-check that you have the same policy names selected 
below:

![](/img/pages/aws/ecs/user-04.png)

## Checkout AWS Container Service

This point is a good time to check out the **EC2 Container Service** by clicking on it in the AWS dashboard 
or following the direct link: 
[https://console.aws.amazon.com/ecs/home](https://console.aws.amazon.com/ecs/home)

We're not going to do anything within ECS just yet other than observe its emptiness :) The first time
you go there you'll be presented with the splash page below which you can skip on through by clicking 
**Get Started**:

![](/img/pages/aws/ecs/ecs-01.png)

In the next screen AWS will try to guide you into populating your ECS Service with something, but as we're 
after a blank slate, you'll want to click **Cancel**:

![](/img/pages/aws/ecs/ecs-02.png)

Which will arrive us to our destination - the empty state:

![](/img/pages/aws/ecs/ecs-03.png)

But we needn't worry, everything in our ECS Service will be created outside ECS by our **new EC2 Instance**
and **Travis CI** builds.

## 3. Launch new EC2 Docker Server Instance

At this point we now have everything we need to light up the bits where our Docker Apps will run on.
We want any EC2 Instances in the Container Service to use the purpose-specific 
**Amazon ECS-Optimized Amazon Linux AMI** which you can quickly find by selecting the **AWS Marketplace** tab
and adding `ecs-optimized` in the filter then click **Select** on the first Amazon AMI result:

![](/img/pages/aws/ecs/launch-01.png)

Which will start the Launch Instance Wizard where you can select the Instance Type you want to run. 
The **t2.micro** is more than enough for what we need but you can select any preferred Instance Type 
then click **Next: Configure instance Details**:

![](/img/pages/aws/ecs/launch-02.png)

The important option in the **Configure Instance Details** screen is to select the `ecsInstanceRole` for the 
EC2 Instance's **IAM Role**, you'll also want to choose `Enable` for the **Auto-assign Public IP** option
(if it's not already the default):

![](/img/pages/aws/ecs/launch-03.png)

You can skip past the defaults on the **Add Storage** screen, in the **Tag Instance** screen you'll be able 
to assign a human-friendly label to identify this instance, e.g:

![](/img/pages/aws/ecs/launch-04.png)

The **Configure Security Group** page is where you specify the ports you want open. You'll want **SSH** open
so you can login to your instance and for Web Apps you'll also typically want **HTTP** and **HTTPS** open 
as well. With the warning message AWS is encouraging you to limit your SSH access to a limited IP Range
which if you have a **static IP** from your ISP is a good idea to lock down the **Source** to `My IP`, 
otherwise leaving it open to any IP is ok as we'll be using a Private Key to login to our Instance.

![](/img/pages/aws/ecs/launch-05.png)

On the next page you want to either create a new Public/Private Key Pair or use an existing one. If creating 
a new Pair you need to click **Download Key Pair** as you'll need it to SSH into your instance.

![](/img/pages/aws/ecs/launch-06.png)

After clicking **Launch Instances** you'll be redirected to your EC2 **Instances** tab where you can 
watch your new Instance start up:

![](/img/pages/aws/ecs/launch-07.png)

## Revisit AWS Container Service

Once **running** go back and refresh your **EC2 Container Service** page where you should now see a 
**default** cluster that was created:

![](/img/pages/aws/ecs/ecs-04.png)

Clicking on **ECS Instances** tab will show your new Instance with an **ACTIVE** state:

![](/img/pages/aws/ecs/ecs-05.png)

If you don't see a **default** cluster created with your new Instance attached, terminate your Instance 
then go back and create it again, triple-checking it has the `ecsInstanceRole` **IAM Role** when Configuring
the Instance. If that fails, try re-creating the `ecsInstanceRole` ROLE making sure it has the 
`AmazonEC2ContainerServiceforEC2Role` Policy. 

## 4. Associating Elastic IP to new EC2 Instance

Before connecting to the Instance lets assign it a domain name so it has a canonical reference to make it 
easier to remember and refer to later. Before doing this you should assign your instance an **Elastic IP** 
so it has a **persistent Public IP** within your control that you can assign a domain name to. 

To do this, click on the **Elastic IPs** tab then click on **Allocate New Address**, this will issue you a 
new **Elastic IP** that you can assign to your new instance, e.g:

![](/img/pages/aws/ecs/elasticip-01.png)

After clicking **Associate** it will show up in the **Elastic IPs** tab:

![](/img/pages/aws/ecs/elasticip-02.png)

## Assign a Domain Name to your Elastic IP

This is going to different for each Domain Registrar but you'll want to assign a new **A Record** to 
point to your new **Elastic IP**. If you're using Google Domains you can refer to their 
[Google Domains Help Documentation](https://support.google.com/domains/answer/3290309?hl=en&ref_topic=3251230).

For the purposes of this tutorial we've used the `ecsdemo.netcore.io` domain name which resolves to our 
**Elastic IP** Address.

## 5. Log into the new EC2 Instance

With the new Instance up and running we can login to it, but you'll need access to a `ssh` client to make 
that happen. If you're fortunate to have a Unix-based OS at your disposal you're already set, if you're 
on Windows 10 you can enable [Bash on Ubuntu on Windows](https://msdn.microsoft.com/en-us/commandline/wsl/about)
otherwise you'll need to install a [SSH Client for Windows](http://www.putty.org/).

When you're ready open a Terminal and copy the **EC2 Instance Key Pair** that you downloaded previously and 
copy it into a permanent location, e.g `~/pem/ecs-demo.pem`.

Before we can SSH with the Private Key we need to lock down the permissions so only we can read it which you 
can do with:

:::sh
chmod 400 ~/pem/ecs-demo.pem
:::

Once locked down you can use it to SSH into your instance using the `-i` flag, logging in as the `ec2-user`:

:::sh
ssh -i ~/pem/ecs-demo.pem ec2-user@ecsdemo.netcore.io
:::

Replace `ecsdemo.netcore.io` with your domain name or Elastic IP. If everything went to plan you should now
be logged into your EC2 Instance:

![](/img/pages/aws/ecs/ssh-01.png)

We're only assigned one task while we're here which is to run an instance of the `jwilder/nginx-proxy` 
Docker App copying the command below:

:::sh
docker run -d -p 80:80 -v /var/run/docker.sock:/tmp/docker.sock:ro jwilder/nginx-proxy
:::

This will pull the [jwilder/nginx-proxy](https://hub.docker.com/r/jwilder/nginx-proxy/) Docker Image from 
[Dockers public repository](https://hub.docker.com/explore/) which sets up 
a new Docker container running [nginx](https://nginx.org/en/) and 
[docker-gen](https://github.com/jwilder/docker-gen) which is what will enable our no-touch deployments where 
it will generate the reverse proxy configs for nginx each time a new Docker App is deployed where it will
use its `VIRTUAL_HOST` Environment Variable that it was created with. 

It's not important to 
[know exactly how it works](http://jasonwilder.com/blog/2014/03/25/automated-nginx-reverse-proxy-for-docker/) 
only that it's responsible for setting up **nginx** to **reverse proxy requests** from our App's custom 
`VIRTUAL_HOST` (e.g. ecsdemo.netcore.io) to our .NET Core Kestrel HTTP Server that's listening on port **5000**.

If successful you'll get an output similar to:

![](/img/pages/aws/ecs/ssh-02.png)

For the curious you can run `docker ps` at this point to see the running Docker Containers which should 
include this **nginx-proxy** and AWS's ECS agent.

### Enable support for SSL

If you wanted to host any of your Apps under SSL you'll instead need to run your `jwilder/nginx-proxy` container with:

:::sh
docker run --detach --name nginx-proxy --publish 80:80 --publish 443:443 \
    --volume /etc/nginx/certs --volume /etc/nginx/vhost.d --volume /usr/share/nginx/html \
    --volume /var/run/docker.sock:/tmp/docker.sock:ro jwilder/nginx-proxy
:::

You'll also need to run the [letsencrypt-nginx-proxy-companion](https://github.com/JrCs/docker-letsencrypt-nginx-proxy-companion)
companion Docker container for `nginx-proxy` with:

:::sh
docker run --detach --name nginx-proxy-letsencrypt --volumes-from nginx-proxy \
    --volume /var/run/docker.sock:/var/run/docker.sock:ro jrcs/letsencrypt-nginx-proxy-companion
:::

SSL Requires additional info added via environment variables included your .NET Core Docker App's deployment script
which are documented in [Configure support for SSL](#configure-support-for-ssl).

## 6. Fork redis-geo Demo

With all the prep work for setting up our Docker Server out of the way, we can now get to the fun part 
of deploying Docker Apps to it. Let's get started by forking the existing
[https://github.com/NetCoreApps/redis-geo](https://github.com/NetCoreApps/redis-geo) project:

![](/img/pages/aws/ecs/fork-01.png)

This will create our own fork of the `redis-geo` Github project into our own Github User Account. We then
need to **Clone** our local fork which we can do from the [Github Desktop App](https://desktop.github.com/)
to a local folder:

![](/img/pages/aws/ecs/fork-02.png)

### Inspect the Build Scripts

Lets open the folder in VS code to inspect what deployment scripts we have:

:::sh
C:\src\redis-geo>code .
:::

The `.travis.yml` is used to configure the environment which **Travis CI** will execute your build under.
Here we're telling Travis we want a **csharp** environment for our solution located at **src/RedisGeo.sln**
using an Ubuntu 14.04 Linux distribution with .NET Core installed. The **script** section tells Travis how 
it should build our project, which is to just run the build scripts in the repo:

![](/img/pages/aws/ecs/code-01.png)

The `DockerFile` tells Docker how to build our Docker App Image: 

 - that's based on the **microsoft/dotnet:latest** Docker Image from Docker's public Repository 
 - includes a copy of our .NET Core solution files
 - runs `dotnet restore` on to pull down all NuGet dependencies
 - builds the .NET Core Solutions **Host Project** using `dotnet build`
 - notifies Docker our App will run a TCP Service listening on port `5000` that it should expose
 - sets the `ASPNETCORE_URLS` Environment Variable
 - tells Docker what to execute when our App is run

This is a fairly generic template for building a .NET Core multi-project App which typically only
requires changing the **WORKDIR** to point to your Solutions **Host Project**:

![](/img/pages/aws/ecs/code-02.png)

The primary config changes you'll need to make are in `/deploy-env.sh` which contains public deployment and 
project-specific info. Here you'll want to change `AWS_DEFAULT_REGION` with the AWS region where your 
ECS Service is located. You'll also need to change `AWS_VIRTUAL_HOST` with your `VIRTUAL_HOST`:

![](/img/pages/aws/ecs/code-03.png)

### ECS task-definition.json

The `task-definition.json` is specific to AWS ECS which lets you declaratively define an atomic collection
of Docker Containers ECS should run when it deploys this "Task". It's essentially a thin wrapper around
[docker run](https://docs.docker.com/engine/reference/run/) where most features can be easily mapped 
to its command-line switches. 

The `task-definition.json` is where we tell ECS what Docker Containers our App needs. Here in addition to 
our Docker App we also need an instance of `redis:3.2` that's made available to our App via Docker's
`--link` feature which lets us connect to the redis-server instance using the `ecsdemo-redisgeo-redis` 
Hostname that we make available to our App via the `REDIS_HOST` Environment variable:

![](/img/pages/aws/ecs/code-04.png)

## Configure support for SSL

If you want to host your .NET Core Apps under SSL you'll need to include some additional information in your 
deployment scripts that will be passed to the [docker-letsencrypt-nginx-proxy-companion](https://github.com/JrCs/docker-letsencrypt-nginx-proxy-companion)
container which is a run as a companion Docker container to [nginx-proxy](https://github.com/jwilder/nginx-proxy) which will
automate the creation/renewal of Lets Encrypt SSL Certificates and the necessary nginx configuration to redirect HTTP Requests
to SSL Requests which are "SSL terminated" at the nginx reverse proxy and proxied as HTTP to your downstream .NET Core App.

Instead of starting with `redis-geo` you'll want to start with the deployment scripts in [/ServiceStack/sharpscript](https://github.com/ServiceStack/sharpscript)
which contain a working example of a .NET Core App hosted under SSL at [https://sharpscript.net](https://sharpscript.net).

Essentially your [deploy-envs.sh](https://github.com/ServiceStack/sharpscript/blob/master/deploy-envs.sh) deployment configuration
script needs to include `LETSENCRYPT_HOST` and `LETSENCRYPT_EMAIL` variables:

```bash
#!/bin/bash

# set environment variables used in deploy.sh and AWS task-definition.json:
export IMAGE_NAME=netcoreapps-sharpscript
export IMAGE_VERSION=latest

export AWS_DEFAULT_REGION=us-east-1
export AWS_ECS_CLUSTER_NAME=default
export AWS_VIRTUAL_HOST=sharpscript.net
export LETSENCRYPT_HOST=$AWS_VIRTUAL_HOST
export LETSENCRYPT_EMAIL=team@servicestack.net
```

The only other change required is to pass these environment variables to your App's Docker container defined in 
[task-definition.json](https://github.com/ServiceStack/sharpscript/blob/master/scripts/task-definition.json):

```json
{
    "family": "${ECS_TASK}",
    "networkMode": "bridge",
    "containerDefinitions": [
        {
            "image": "${AWS_ECS_REPO_DOMAIN}/${IMAGE_NAME}:${IMAGE_VERSION}",
            "name": "${IMAGE_NAME}",
            "cpu": 128,
            "memory": 256,
            "essential": true,
            "portMappings": [
                {
                    "containerPort": 5000,
                    "hostPort": 0,
                    "protocol": "tcp"
                }
            ],
            "environment": [
                {
                    "name": "VIRTUAL_HOST",
                    "value": "${AWS_VIRTUAL_HOST}"
                },
                {
                    "name": "LETSENCRYPT_HOST",
                    "value": "${LETSENCRYPT_HOST}"
                },
                {
                    "name": "LETSENCRYPT_EMAIL",
                    "value": "${LETSENCRYPT_EMAIL}"
                }
            ]
        }
    ]
}
```

Otherwise all other deployment scripts remain the same as a normal ECS .NET Core Docker App, the primary difference being 
that after it's deployed by AWS ECS, it triggers the nginx-proxy-companion to retrieve and auto-configure 
an SSL Certificate from [Lets Encrypt](https://letsencrypt.org) for the App's external domain defined in `LETSENCRYPT_HOST`
which it registers with nginx to enable its SSL-terminated `https` support for that domain.

## Create project in Travis-CI

After making the necessary changes in `/deploy-env.sh` we can register our project in **Travis CI**, 
fortunately for us Travis's UX is streamlined making this effortless. Start by clicking on **Sign Up** 
button on Travis's home page [https://travis-ci.org](https://travis-ci.org):

![](/img/pages/aws/ecs/travis-01.png)

Then click on the `+` link next to **My Repositories**:

![](/img/pages/aws/ecs/travis-02.png)

This takes you to your Github Profile view where you just need to click on the the switch icon next to your
**redis-geo fork**, e.g:

![](/img/pages/aws/ecs/travis-03.png)

### CI Environment Variables

After enabling your project it will appear in your repositories list. Here we need to click on 
the **Settings** Menu Item in the **More Options** drop down menu in order to provide Travis the 
sensitive `ecsDemoUser` credentials that we don't want to include in a public Github Repository. 
At a minimum you'll need to add Environment variables for the `ecsDemoUser` IAM User you copied above:

 - `AWS_ACCOUNT_NUMBER`
 - `AWS_ACCESS_KEY_ID`
 - `AWS_SECRET_ACCESS_KEY`

The **Settings** page is where you can define any sensitive information you want your Docker App to have
access to. E.g. although it's not needed for this Demo you can specify your `SERVICESTACK_LICENSE` here
where its inject into your Docker App with the **"environment"** Key/Value list in your projects 
`task-definition.json`. If your App requires a lot of confidential information it can be easier to instead
register a connection string to a [Remote AppSettings data source](/appsettings), 
that way you can have a centralized location for managing the keys and connection strings for all your Apps.

![](/img/pages/aws/ecs/travis-04.png)

If it's not on hand, you can get the `AWS_ACCOUNT_NUMBER` for your `ecsDemoUser` from the number embedded 
in its **User ARN**:

![](/img/pages/aws/ecs/travis-05.png)

After adding your `ecsDemoUser` credentials above, commit and push your changes to `deploy-env.sh` in order 
to trigger a new **Travis CI** build. If you've previously committed the changes you can click 
**Restart build** to rerun the build using your latest Environment Variables. This will trigger a new build 
which if everything is in place should result in a successful green build:

![](/img/pages/aws/ecs/travis-06.png)

## Inspect AWS Container Service

Now we can go back into **EC2 Container Service** and have a look at what the generic `deploy.sh` script 
created for us. Clicking the **Repositories** tab will display your Apps 
[private ECR Repository](http://docs.aws.amazon.com/AmazonECS/latest/developerguide/ECS_Console_Repositories.html)
which contains a list of all Docker Images that were deployed to ECS with the one that's currently used by 
the running Docker Container, tagged with the **latest** Image tag:

![](/img/pages/aws/ecs/ecs-06.png)

In the **Clusters** tab you'll see that your **default** Cluster contains an 
[ECS Service](http://docs.aws.amazon.com/AmazonECS/latest/developerguide/ecs_services.html) 
aptly named `ecsdemo-redisgeo-service`: 

![](/img/pages/aws/ecs/ecs-07.png)

The [ECS Service](http://docs.aws.amazon.com/AmazonECS/latest/developerguide/ecs_services.html) 
is what manages your running Tasks where if your Docker App goes down for whatever reason, the Service will 
restart new Task Instances based on its 
[Task Definition](http://docs.aws.amazon.com/AmazonECS/latest/developerguide/task_defintions.html) 
until the **Desired count** of instances is reached.  

![](/img/pages/aws/ecs/ecs-08.png)

### View list of running Docker Containers

If your Service contains a **RUNNING** Task that means your time here was a success. We can further verify 
that's everything's in order by SSH'ing back into our EC2 Instance and running `docker ps` to see our 
running Docker Containers:

![](/img/pages/aws/ecs/ssh-03.png)

Where we should see **4 running** Docker Containers:

 1. nginx-proxy
 2. Our .NET Core Docker App
 3. redis-server
 4. AWS ECS agent

## Problems with the task not running

If you don't have a **RUNNING** Task then you might need to [restart the ECS container agent](http://docs.aws.amazon.com/AmazonECS/latest/developerguide/troubleshooting.html) by SSH'ing into the EC2 Instance and running the commands below:

```
[ec2-user ~]$ sudo stop ecs
ecs stop/waiting
[ec2-user ~]$ sudo start ecs
ecs start/running, process 26119
```

If that still doesn't work you should see if any of the containers are stopping shortly after they have started. A good way of doing this is to run `docker ps -a` which will show you all the containers that have started (without the -a, it only shows the currently running ones). If you see that some are exiting with a code that is not 0, then you may have a problem with that container. Run that container using `docker run` using its image name and omitting the -d flag. For example:

```
docker run 473481601643.dkr.ecr.ap-southeast-2.amazonaws.com/netcoreapps-redisgeo:latest
```

That will run the container and show its output, which might give you some indication of the problem.

## Things to try

### 1. Make a change to your App

With your .NET Core Docker mission officially a success the first thing you're going to want to do 
is to commit a change to your fork whilst watching your **Travis CI** bot working away so you can see your
Continuous Docker deployments in action :)

### 2. Go through this tutorial again

If you've stuttered hazily through parts of this tutorial we recommend going through it again from scratch as
things should become a lot clearer and faster the next time around. After doing this a few times everything 
will appear intuitive and you won't need to refer to this tutorial again.

### 3. Copy the build scripts to Dockerize own .NET Core Apps

Customizing the deploy scripts to your own Apps will help familiarize yourself with Docker and identify 
the areas which are customizable.

### 4. Exec build scripts to Create and Run your Docker App locally 

Install [Docker for Mac](https://docs.docker.com/engine/installation/mac/) or 
[Docker for Windows](https://docs.docker.com/engine/installation/windows/) and try building and running the
Docker Images locally. Since you're running locally you'll need to set any required **Travis CI** Environment 
Variables then have a look at translating what ECS does with its `task-definition.json` into docker commands. 
This example is a little tricky due to the use of Docker's `--link` feature but with some trial and error and
the [Docker run reference](https://docs.docker.com/engine/reference/run/) to guide you, you'll have your 
Docker App running locally - acquainting you with one of Docker's killer features!


# Deploying .NET Core Apps to Ubuntu with rsync
Source: https://docs.servicestack.net/netcore-deploy-rsync

A common way for reliably hosting .NET Core Apps on Ubuntu is to use [supervisor](http://supervisord.org/index.html) to monitor the `dotnet` self-hosting processes behind an nginx reverse proxy which handles external HTTP requests to your website and proxies them to the dotnet process running your Web App on a local port. You'll need access to a Unix environment on your client Desktop, either using Linux, OSX or [Installing Windows Subsystem for Linux (WSL)](https://github.com/ServiceStack/redis-windows#option-1-install-redis-on-ubuntu-on-windows).

## Setup the deploy User Account

We'll start by creating a dedicated user account for hosting and running your .NET Core Apps to mitigate potential abuse. SSH into your Ubuntu server and create the `deploy` user account with a `/home/deploy` home directory and add them to the `sudo` group:

```bash
$ sudo useradd -m deploy
$ sudo usermod -aG sudo deploy
```

For seamless deployments use `visudo`:

:::sh
visudo
:::

To allow `deploy` to run `supervisorctl` without prompting for a password:

```ini
# Allow members of group sudo to execute any command
%sudo   ALL=(ALL:ALL) ALL
%deploy ALL=(ALL:ALL) NOPASSWD: /usr/bin/supervisorctl
```

::: info Tip
In vi type `i` to start editing a file and `ESC` to quit edit mode and `:wq` to save your changes before exiting
:::

## Setup supervisor

Install supervisor using apt-get:

:::sh
sudo apt-get install supervisor
:::

You'll need to create a separate config file for each app in `/etc/supervisor/conf.d/`. We can use the same template below by replacing `myapp` with the name of your App:

### /etc/supervisor/conf.d/web.myapp.conf

```ini
[program:web-myapp]
command=/usr/bin/dotnet /home/deploy/apps/myapp/MyApp.dll
directory=/home/deploy/apps/myapp
autostart=true
autorestart=true
stderr_logfile=/var/log/web-myapp.err.log
stdout_logfile=/var/log/web-myapp.out.log
environment=ASPNETCORE_ENVIRONMENT=Production
user=deploy
stopsignal=INT
```

## Setup nginx

You'll also need to create a separate config for each website on nginx in /etc/nginx/sites-available/. You can use the same template for each website but you'll need to change the server_name with the domain name you want to use for the App and use a different port number for each App:

### /etc/nginx/sites-available/myapp.example.org

```nginx
server {
    listen       80;
    server_name myapp.example.org;

    location / {
        proxy_pass http://localhost:5001;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection keep-alive;
        proxy_cache_bypass $http_upgrade;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_buffering off;
        proxy_ignore_client_abort off;
        proxy_intercept_errors on;

        client_max_body_size 500m;
    }
}
```

You'll then need to create symlink for each website to tell nginx you want each website to be enabled:

:::sh
ln -s /etc/nginx/sites-available/myapp.example.org /etc/nginx/sites-enabled/myapp.example.org
:::

After this we can tell nginx to reload its configuration, as there's nothing listening to `http://localhost:5001` yet nginx will return a 502 Bad Gateway response but will start working as soon as our deployed .NET Core Apps are up and running.

:::sh
/etc/init.d/nginx reload
:::

## Setting up SSH keys

We can now exit our remote Linux server and return to our local machine and prepare our deployment script. Before doing this we recommend [setting up SSH and copying your SSH public key to your remote server](https://www.digitalocean.com/community/tutorials/how-to-set-up-ssh-keys--2) which is both more secure and more convenient than using a password.

## Create the deployment script

[rsync](https://rsync.samba.org/) is a beautiful utility that provides a fast, secure file transfer over SSH which you can use to sync the contents of folders to a remote site. There's only 2 commands you need to run to deploy a local .NET Core App remotely, `rsync` to sync the published .NET Core App files and `supervisorctl` to restart the `supervisord` process that runs and monitor the .NET Core App which you can add to a [deploy.sh](https://github.com/NetCoreApps/TechStacks/blob/master/src/TechStacks/deploy.sh) that you can run with WSL bash:

```shell
rsync -avz -e 'ssh' bin/Release/netcoreapp3.1/publish/ ubuntu@myapp.example.org:/home/deploy/apps/myapp
ssh ubuntu@myapp.example.org "sudo supervisorctl restart web-myapp"
```

To automate the entire deployment down to a single command you can add an npm script to your project's `package.json` that creates a production client and server build of your App before running WSL's `bash` to run the deploy script. All [Webpack Single Page App Templates](/templates/single-page-apps) already have a **publish** npm script, so you would just need to add a **deploy** script to run publish before running the above `deploy.sh`

```json
{
    "publish": "nuxt build && dotnet publish -c Release",
    "deploy": "npm run publish && bash deploy.sh"
}
```

Now to deploy your App you can just run:

:::sh
npm run deploy
:::

Which deploys your published App to your remote Ubuntu server instance using `rsync` to only copy the incremental parts of the App that's changed (typically completing in <1s) and `ssh` to run a remote command to restart the `suprvisord` process, starting the .NET Core App with the latest deployed version.


# ServiceStack.Text
Source: https://docs.servicestack.net/text

Deep inside all of ServiceStack's premium libraries lies a high-performance core containing ServiceStack's text powers. Centered around .NET's fastest full-featured JSON Serializer is a convenient utility belt containing 100's of extensions enhancing .NET's built-in String, Stream, Bytes, List, Dictionary, Reflection, Task, WebRequest types and more.

ServiceStack.Text is an **independent, dependency-free** serialization library containing ServiceStack's core high-performance utils and text processing functionality, including:

- [JSON](/json-format), [CSV](/csv-format), [JSON Lines](/jsonl-format) and [JSV](/jsv-format) Text Serializers
- [AutoMapping Utils](/auto-mapping)
- [JavaScript Utils](/js-utils)
- [HTTP Utils](/http-utils)
- [Dump Utils](/dump-utils)
- [Fast Reflection Utils](/reflection-utils)
- [Mobile Apps Support](https://github.com/ServiceStackApps/HelloMobile)

## Try out [ServiceStack.Text Live](https://gist.cafe/c71b3f0123b3d9d08c1b11c98c2ff379)

A great way to try out ServiceStack.Text is on [gist.cafe](https://gist.cafe) which lets you immediately
run and explore all ServiceStack.Text features from the comfort of your browser with zero software install:

[![](/img/pages/gistcafe/gistcafe-csharp.png)](https://gist.cafe/c71b3f0123b3d9d08c1b11c98c2ff379)


# HTTP Utils
Source: https://docs.servicestack.net/http-utils

The recommended way to call ServiceStack services is to use any of the [C# Service Clients](/csharp-client) which have a nice DRY and typed API optimized for this use. However when doing server programming you will often need to consume 3rd Party HTTP APIs, unfortunately the built-in way to do this in .NET doesn't make for a good development experience since it makes use of **WebRequest** - one of the legacy classes inherited from the early .NET days. WebRequest is an example of a class that's both versatile but also suffers from exposing an out-dated and unpleasant API for your application code to bind to.

### HTTP Utils - a pleasant DRY API using extension methods

Rather than taking the normal .NET approach of wrapping WebRequest inside a suite of proxy and abstraction classes, we prefer to instead encapsulate any unnecessary boilerplate behind extension methods DRYing common access patterns behind terse, readable and chained APIs without any loss of flexibility since the underlying WebRequest remains accessible whenever it's needed. 

The [PocoPower project](https://github.com/ServiceStack/ServiceStack.UseCases/tree/master/PocoPower) shows some good examples of what this looks like in Practice. Here's how you can retrieve a typed list of GitHub User Repos from GitHub's JSON REST API:

```csharp
List<GithubRepo> repos = $"https://api.github.com/users/{user}/repos"
    .GetJsonFromUrl()
    .FromJson<List<GithubRepo>>();
```

## Uses HttpClient in .NET 6

As .NET's existing `HttpWebRequest` has been officially deprecated, the UX-friendly HTTP Utils extension methods utilize the recommended **HttpClient** implementation from .NET 6+ builds.

### Source Compatible API

Given .NET 6 HttpClient uses a different implementation to .NET's `HttpWebRequest` in previous .NET Versions it wasn't possible to enable 100% compatibility with existing code that utilize custom Request & Response **filters** however you can use the source compatible `.With()` APIs to customize a HTTP Request to support using the same source code in multi-targeted code-bases, e.g:

```csharp
var response = url.GetJsonFromUrl(requestFilter:req => req.With(c => c.UserAgent = UserAgent));
var response = await url.GetJsonFromUrlAsync(requestFilter:req => req.With(c => c.UserAgent = UserAgent));
```

Which lets you configure a [HttpRequestConfig](https://github.com/ServiceStack/ServiceStack/blob/main/ServiceStack.Text/src/ServiceStack.Text/HttpRequestConfig.cs) that is equally applied to their `HttpClient` and `HttpWebRequest` implementations. 

It also includes `Set*` methods to simplify common tasks like creating Authenticated Requests, e.g:

```csharp
var json = await url.GetJsonFromUrlAsync(requestFilter: req => 
    req.With(c => {
        c.UserAgent = UserAgent;
        c.SetAuthBasic(ClientId, ClientSecret);
    }), token: token).ConfigAwait();
```

The full [HttpRequestConfig](https://github.com/ServiceStack/ServiceStack/blob/main/ServiceStack.Text/src/ServiceStack.Text/HttpRequestConfig.cs) API available in this release include:

```csharp
public class HttpRequestConfig 
{
    public string? Accept { get; set; } 
    public string? UserAgent { get; set; } 
    public string? ContentType { get; set; }
    public string? Referer { get; set; }
    public string? Expect { get; set; }
    public string[]? TransferEncoding { get; set; }
    public bool? TransferEncodingChunked { get; set; }
    public NameValue? Authorization { get; set; }
    public LongRange? Range { get; set; }
    public List<NameValue> Headers { get; set; } = new();

    public void SetAuthBearer(string value) => Authorization = new("Bearer", value);
    public void SetAuthBasic(string name, string value) => 
        Authorization = new("Basic", Convert.ToBase64String(Encoding.UTF8.GetBytes(name + ":" + value)));
    public void SetRange(long from, long? to = null) => Range = new(from, to);

    public void AddHeader(string name, string value) => Headers.Add(new(name, value));
}
```

#### Inspecting Responses

For source compatible APIs to inspect HTTP Responses you can use `GetHeader()` to retrieve HTTP Response Headers, `GetContentLength()` to retrieve the **Content-Length** if exists and `MatchesContentType()` to compare against existing MimeTypes which ignores whitespace, casing and charset suffixes, e.g:

```csharp
var response = baseUrl.AppendPath("dir","sub").AddQueryParam("id", 1)
    .SendStringToUrl(method: "HEAD",
        responseFilter: res => {
            Assert.That(res.GetHeader("X-Method"), Is.EqualTo("HEAD"));
            Assert.That(res.GetHeader("X-Id"), Is.EqualTo("1"));
            Assert.That(res.MatchesContentType("video/mp4"));
            Assert.That(res.GetContentLength(), Is.EqualTo(100));
        });
```

#### Connect to HttpFactory

The HttpClient HttpUtils use a lazy singleton for efficiency however if you're using it in a host that has an ASP.NET IOC you can configure it to make use of a HttpClient factory by using the `IServiceCollection.AddHttpUtilsClient()` extension method, e.g:

```csharp
public class AppHost : AppHostBase, IHostingStartup
{
    public void Configure(IWebHostBuilder builder) => builder
        .ConfigureServices(services => {
            services.AddHttpUtilsClient();
        });
}
```

#### Custom HttpClient

Alternatively you can configure it to use your own client factory with:

```csharp
HttpUtils.CreateClient = () => UseMyHttpClient()
```

Or to utilize a custom Proxy with:

```csharp
HttpUtils.HttpClientHandlerFactory = () => new() {
    UseDefaultCredentials = true,
    AutomaticDecompression = DecompressionMethods.Brotli | DecompressionMethods.Deflate | DecompressionMethods.GZip,
    Proxy = new WebProxy(proxyUrl)
};
```

The following Core APIs also have extension methods on `HttpClient` which existing HttpClient instances can make use of:

 - `SendStringToUrl()`
 - `SendStringToUrlAsync()`
 - `SendBytesToUrl()`
 - `SendBytesToUrlAsync()`
 - `SendStreamToUrl()`
 - `SendStreamToUrlAsync()`

## HTTP Client Factory HTTP Utils

ServiceStack registers a named `IHttpClientFactory` that's configured with the same defaults as the built-in [HttpUtils](/http-utils) including using Default Credentials and support for Brotli, Deflate and GZip compression.

You can access this via `IHttpClientFactory.HttpUtilsClient()` extension method, e.g:

```csharp
public class MyServices(IHttpClientFactory clientFactory) : Service
{
    public async Task<object> Any(MyRequest request)
    {
        using HttpClient client = clientFactory.HttpUtilsClient();
        //...
    }
}
```

### Url Extensions

You can make use of the accompanying String Extensions to programmatically construct a url as seen in this Twitter API example:

```csharp
var url = $"http://api.twitter.com/statuses/user_timeline.json?screen_name={name}";
if (sinceId != null)
    url = url.AddQueryParam("since_id", sinceId);
if (maxId != null)
    url = url.AddQueryParam("max_id", maxId);

var tweets = url.GetJsonFromUrl()
    .FromJson<List<Tweet>>();
```

In both these cases it uses `WebRequest` to make a HTTP **GET** request asking for the "application/json" Content-Type, that's preferably compressed with `gzip` or `deflate` encoding (if the remote web server supports it).

### Alternative Content-Type

In addition to `GetJsonFromUrl` there's also `GetXmlFromUrl` covering the 2 widely used content-types used for data containers:

```csharp
List<User> users = "http://example.org/xml-rpc/users"
    .GetXmlFromUrl()
    .FromXml<List<User>>();
```

For any other Content-Type you can specify it with the optional `accept` param:

```csharp
var csv = "http://example.org/users.csv"
    .GetStringFromUrl(accept:"text/csv");
```

### Customizing the WebRequest

Although most extension methods start on string urls, you can customize the HttpWebRequest used to make the request by specifying a `requestFilter`. e.g:

```csharp
var json = "http://example.org/users".GetJsonFromUrl(requestFilter:webReq =>{
    webReq.Headers["X-Api-Key"] = apiKey;
});
```

### Parsing Custom Responses

This also works for Response Filters as well where if you need access to the Response HTTP Headers as well as the body you can add a callback for the response filter:

```csharp
List<GithubRepo> repos = $"https://api.github.com/users/{user}/repos"
    .GetJsonFromUrl(responseFilter: httpRes => {
        var remaining = httpRes.Headers["X-Api-Remaining"];
    })
    .FromJson<List<GithubRepo>>();
```

### Downloading Raw Content

Use the `GetStringFromUrl` extension to download raw text:

```csharp
string csv = "http://example.org/sales.csv".GetStringFromUrl();
```

and the `GetBytesFromUrl` extension to download raw bytes:

```csharp
byte[] imgBytes = "http://example.org/photo.jpg".GetBytesFromUrl();
```

## POSTing data

Another common HTTP Request is to POST data to REST APIs. The most common way to post data to HTTP APIs is to post `x-www-form-urlencoded` key value pairs which you can do with:

```csharp
var response = "http://example.org/login"
    .PostToUrl("Username=mythz&Password=password");
```

Or using a POCO Type:

```csharp
var response = "http://example.org/login"
    .PostToUrl(new Login { Username="mythz", Password="password" });
```

An Anonymous Type:

```csharp
var response = "http://example.org/login"
    .PostToUrl(new { Username="mythz", Password="password" });
```

Or a string Dictionary:

```csharp
var login = new Dictionary<string,string> { 
    {"Username","mythz"}, {"Password","password"} };
var response = "http://example.org/login".PostToUrl(login);
```

Or a NameValueCollection:

```csharp
var login = new NameValueCollection { 
    {"Username","mythz"}, {"Password","password"} };
var response = "http://example.org/login".PostToUrl(login.ToFormUrlEncoded());
```

### POSTing JSON data

Although POST'ing other Content-Types are also easily supported. An example using JSON:

Either as any serializable JSON object:

```csharp
var response = "http://example.org/login"
    .PostJsonToUrl(new Login { Username="mythz", Password="password" });
```

Or as a raw JSON string:

```csharp
var response = "http://example.org/login"
    .PostJsonToUrl(@"{""Username"":""mythz"",""Password"":""p@ssword""}");
```

And an example of sending any other arbitrary content types:

```csharp
var response = "http://example.org/login"
  .PostStringToUrl("<User>mythz</User><Pass>p@ss</Pass>", contentType:"application/xml");
```

The above API's also apply to **PUT** or **PATCH** data as well by using the `PutToUrl` and `PatchToUrl` extension methods.

The same [HTTP Utils extension methods for Post and Put](/http-utils#posting-data) also have `Patch()` equivalents.

### PATCH Example

We use the new `Patch()` support in Gistlyn's
[GitHubServices.cs](https://github.com/ServiceStack/Gistlyn/blob/master/src/Gistlyn.ServiceInterface/GitHubServices.cs)
to update contents of existing Gists:

```csharp
var GithubApiBaseUrl = "https://api.github.com/";
var updateResponse = GithubApiBaseUrl.CombineWith("gists", gist)
    .PatchJsonToUrl(new UpdateGithubGist {
        description = request.Description,
        files = request.Files,
    }, 
    requestFilter: req => {
        req.UserAgent = "Gistlyn";
        req.Headers["Authorization"] = "token " + github.AccessTokenSecret;
    });
```

### Creating a Proxy using HTTP Utils

As the HTTP Utils offers a flexible API it becomes trivial to create a generic HTTP Proxy which you can implement with the ServiceStack Service below:

```csharp
[Route("/proxy")]
public class Proxy : IRequiresRequestStream, IReturn<string>
{
    public string Url { get; set; }
    public Stream RequestStream { get; set; }
}

public object Any(Proxy request)
{
    if (string.IsNullOrEmpty(request.Url))
        throw new ArgumentNullException("Url");

    var hasRequestBody = base.Request.Verb.HasRequestBody();
    try
    {
        var bytes = request.Url.SendBytesToUrl(
          method: base.Request.Verb,
          requestBody: hasRequestBody ? request.RequestStream.ReadFully() : null,
          contentType: hasRequestBody ? base.Request.ContentType : null,
          accept: ((IHttpRequest)base.Request).Accept,
          requestFilter: req => req.UserAgent = "Gistlyn",
          responseFilter: res => base.Request.ResponseContentType = res.ContentType);

        return bytes;
    }
    catch (WebException webEx)
    {
        var errorResponse = (HttpWebResponse)webEx.Response;
        base.Response.StatusCode = (int)errorResponse.StatusCode;
        base.Response.StatusDescription = errorResponse.StatusDescription;
        var bytes = errorResponse.GetResponseStream().ReadFully();
        return bytes;
    }
}
```

## Async HTTP Utils

Many of HTTP Utils also have async versions allowing them to participate in C#'s `async/await` workflows. The available async APIs include:

```csharp
Task<string> GetStringFromUrlAsync(...)
Task<string> PostStringToUrlAsync(...)
Task<string> PostToUrlAsync(...)
Task<string> PostJsonToUrlAsync(...)
Task<string> PostXmlToUrlAsync(...)
Task<string> PutStringToUrlAsync(...)
Task<string> PutToUrlAsync(...)
Task<string> PutJsonToUrlAsync(...)
Task<string> PutXmlToUrlAsync(...)
Task<string> DeleteFromUrlAsync(...)
Task<string> OptionsFromUrlAsync(...)
Task<string> HeadFromUrlAsync(...)
Task<string> SendStringToUrlAsync(...)
```

## Uploading Files

In the `ServiceStack.ServiceClient.Web` namespace there are more HTTP extensions available including the `UploadFile` extension methods to upload files using multi-part/formdata:

```csharp
var httpRes = "http://example.org/upload"
    .PostFileToUrl(new FileInfo("/path/to/file.xml"), "application/xml");
```

## Upload File from Stream

For finer-grain control you can use the `UploadFile` extension method which allows you to customize the `WebRequest` that's used to send the File Upload HTTP Request, e.g:

```csharp
var uploadFile = new FileInfo("path/to/file.csv");

var webReq = (HttpWebRequest)WebRequest.Create("http://example.org/upload");
webReq.Accept = MimeTypes.Json;
using (var stream = uploadFile.OpenRead())
{
    webReq.UploadFile(stream, uploadFile.Name, MimeTypes.GetMimeType(uploadFile.Name));
}
```

## Exception handling

Exception handling is another area we can DRY up using extension methods. Rather than wrapping them in our own Custom exception classes or repeating the boilerplate required to find the underlying issue on every request, we provide typed APIs over the native WebRequest **Exceptions**, providing typed DRY APIs to handle common HTTP Faults:

```csharp
try 
{
    var response = "http://example.org/fault".GetStringFromUrl();
} 
catch (Exception ex) 
{
    var knownError = ex.IsBadRequest() 
        || ex.IsNotFound() 
        || ex.IsUnauthorized() 
        || ex.IsForbidden() 
        || ex.IsInternalServerError();

    var isAnyClientError = ex.IsAny400();
    var isAnyServerError = ex.IsAny500();

    HttpStatusCode? errorStatus = ex.GetStatus();
    string errorBody = ex.GetResponseBody(); // only available when using .NET HttpWebRequest
}
```

### HTTP Utils are mockable

The one disadvantage of using Extension methods is that by default they can be hard or impossible to mock which is why we've added explicit support for [support for Mocking in OrmLite](https://github.com/ServiceStack/ServiceStack/blob/main/ServiceStack.OrmLite/tests/ServiceStack.OrmLite.Tests/MockAllApiTests.cs) and now the above HTTP Util extension methods, e.g:

```csharp
using (new HttpResultsFilter {
    StringResult = "mocked"
})
{
    //All return "mocked"
    "http://google.com".GetJsonFromUrl();
    "http://google.com".GetXmlFromUrl();
    "http://google.com".GetStringFromUrl(accept: "text/csv");
    "http://google.com".PostJsonToUrl(json: "{\"postdata\":1}");
}
```

See the [HttpUtilsMockTests.cs](https://github.com/ServiceStack/ServiceStack/blob/main/ServiceStack.Text/tests/ServiceStack.Text.Tests/HttpUtilsMockTests.cs) for more examples showing how the HTTP Apis can be mocked.

## HTTP API Reference

The above description should give you a good idea of how to make use of the APIs, although for a more complete reference we'll post the full signatures here.

Most of the APIs are located in the [ServiceStack.Text](https://github.com/ServiceStack/ServiceStack/blob/main/ServiceStack.Text/src/ServiceStack.Text/HttpUtils.cs) namespace:

```csharp
string GetJsonFromUrl(this string url, Action<HttpWebRequest> requestFilter=null,
  Action<HttpWebResponse> responseFilter=null)

string GetXmlFromUrl(this string url, Action<HttpWebRequest> requestFilter=null, 
  Action<HttpWebResponse> responseFilter=null)

string GetStringFromUrl(this string url, string accept = "*/*", 
  Action<HttpWebRequest> requestFilter=null, Action<HttpWebResponse> responseFilter=null)

string PostStringToUrl(this string url, string requestBody = null,
    string contentType = null, string accept = "*/*",
    Action<HttpWebRequest> requestFilter = null, Action<HttpWebResponse> responseFilter = null)

string PostToUrl(this string url, string formData=null, string accept="*/*",
  Action<HttpWebRequest> requestFilter=null, Action<HttpWebResponse> responseFilter=null)

string PostToUrl(this string url, object formData = null, string accept="*/*",
  Action<HttpWebRequest> requestFilter=null, Action<HttpWebResponse> responseFilter=null)

string PostJsonToUrl(this string url, string json,
    Action<HttpWebRequest> requestFilter = null, Action<HttpWebResponse> responseFilter = null)

string PostJsonToUrl(this string url, object data,
    Action<HttpWebRequest> requestFilter = null, Action<HttpWebResponse> responseFilter = null)

string PostXmlToUrl(this string url, string xml,
    Action<HttpWebRequest> requestFilter = null, Action<HttpWebResponse> responseFilter = null)

string PostXmlToUrl(this string url, object data,
    Action<HttpWebRequest> requestFilter = null, Action<HttpWebResponse> responseFilter = null)

string PutStringToUrl(this string url, string requestBody = null,
    string contentType = null, string accept = "*/*",
    Action<HttpWebRequest> requestFilter = null, Action<HttpWebResponse> responseFilter = null)

string PutToUrl(this string url, string formData=null, string accept="*/*",
  Action<HttpWebRequest> requestFilter=null, Action<HttpWebResponse> responseFilter=null)

string PutToUrl(this string url, object formData = null, string accept = "*/*",
  Action<HttpWebRequest> requestFilter=null, Action<HttpWebResponse> responseFilter=null)

string PutJsonToUrl(this string url, string json,
    Action<HttpWebRequest> requestFilter = null, Action<HttpWebResponse> responseFilter = null)

string PutJsonToUrl(this string url, object data,
    Action<HttpWebRequest> requestFilter = null, Action<HttpWebResponse> responseFilter = null)

string PutXmlToUrl(this string url, string xml,
    Action<HttpWebRequest> requestFilter = null, Action<HttpWebResponse> responseFilter = null)

string PutXmlToUrl(this string url, object data,
    Action<HttpWebRequest> requestFilter = null, Action<HttpWebResponse> responseFilter = null)

string DeleteFromUrl(this string url, string accept = "*/*",
    Action<HttpWebRequest> requestFilter=null, Action<HttpWebResponse> responseFilter=null)

string OptionsFromUrl(this string url, string accept = "*/*",
    Action<HttpWebRequest> requestFilter=null, Action<HttpWebResponse> responseFilter=null)

string HeadFromUrl(this string url, string accept = "*/*",
    Action<HttpWebRequest> requestFilter=null, Action<HttpWebResponse> responseFilter=null)

string SendStringToUrl(this string url, string method = null,
    string requestBody = null, string contentType = null, string accept = "*/*",
    Action<HttpWebRequest> requestFilter=null, Action<HttpWebResponse> responseFilter=null)

byte[] GetBytesFromUrl(this string url, string accept = "*/*", 
    Action<HttpWebRequest> requestFilter=null, Action<HttpWebResponse> responseFilter=null)

byte[] PostBytesToUrl(this string url, byte[] requestBody = null, string contentType = null, 
    string accept = "*/*",
    Action<HttpWebRequest> requestFilter=null, Action<HttpWebResponse> responseFilter=null)

byte[] PutBytesToUrl(this string url, byte[] requestBody = null, string contentType = null, 
    string accept = "*/*",
    Action<HttpWebRequest> requestFilter=null, Action<HttpWebResponse> responseFilter=null)

byte[] SendBytesToUrl(this string url, string method = null,
    byte[] requestBody = null, string contentType = null, string accept = "*/*",
    Action<HttpWebRequest> requestFilter=null, Action<HttpWebResponse> responseFilter=null)

bool IsAny300(this Exception ex)
bool IsAny400(this Exception ex)
bool IsAny500(this Exception ex)
bool IsBadRequest(this Exception ex)
bool IsNotFound(this Exception ex)
bool IsUnauthorized(this Exception ex)
bool IsForbidden(this Exception ex)
bool IsInternalServerError(this Exception ex)

HttpStatusCode? GetResponseStatus(this string url)
HttpStatusCode? GetStatus(this Exception ex)
HttpStatusCode? GetStatus(this WebException webEx)
string GetResponseBody(this Exception ex)

bool HasStatus(this WebException webEx, HttpStatusCode statusCode)
```

Whilst some additional HTTP APIs can be found in the [ServiceStack.ServiceClient.Web](https://github.com/ServiceStack/ServiceStack/blob/master/src/ServiceStack.Common/ServiceClient.Web/WebRequestExtensions.cs) namespace:

```csharp
HttpWebResponse GetErrorResponse(this string url)

WebResponse PostFileToUrl(this string url, FileInfo uploadFileInfo, string uploadFileMimeType,
    string accept = null, Action<HttpWebRequest> requestFilter = null)

WebResponse UploadFile(this WebRequest webRequest, FileInfo uploadFileInfo, string uploadFileMimeType)

UploadFile(this WebRequest webRequest, Stream fileStream, string fileName, string mimeType,
    string accept = null, Action<HttpWebRequest> requestFilter = null)

void UploadFile(this WebRequest webRequest, Stream fileStream, string fileName)
```

Which is located in the [ServiceStack.Text NuGet package](https://nuget.org/packages/ServiceStack.Text/)


# Dump Utils
Source: https://docs.servicestack.net/dump-utils

ServiceStack.Text has extension methods which recursively dumps all the public properties of any type into a human readable **pretty formatted** string. The `Dump()` utils are invaluable when explanatory coding or creating tests as you can quickly see what's in an object without having to set breakpoints and navigate nested properties in VS.NET's Watch window.

#### Extension Methods

```csharp
string Dump<T>(this T instance);
string DumpTable<T>(this T instance);

void Print(this string text, params object[] args);
void PrintDump<T>(this T instance);
void PrintDumpTable<T>(this T instance);
```

The convenient `Print()`, `PrintDump()` and `PrintDumpTable()` extension just writes the output to the Console to provide a wrist-friendly API for a common use-case, e.g:

```
var response = client.Send(request);
response.PrintDump(); // Dumps contents to Console in human-friendly format

$"Top Technologies: {response.TopTechnologies.Dump()}".Print();
```

## Example Usage

After importing the **ServiceStack.Text** namespace you can view the values of all fields as seen in [the following example](https://github.com/ServiceStack/ServiceStack/blob/main/ServiceStack.Text/tests/ServiceStack.Text.Tests/Utils/JsvFormatterTests.cs):

```csharp
var model = new TestModel();
model.PrintDump();
```

### Example Output

```csharp
{
    Int: 1,
    String: One,
    DateTime: 2010-04-11,
    Guid: c050437f6fcd46be9b2d0806a0860b3e,
    EmptyIntList: [],
    IntList:
    [
        1,
        2,
        3
    ],
    StringList:
    [
        one,
        two,
        three
    ],
    StringIntMap:
    {
        a: 1,
        b: 2,
        c: 3
    }
}
```

### Dump Table

Whilst to quickly visualize tabular data, e.g. returned from [OrmLite](https://github.com/ServiceStack/ServiceStack.OrmLite) or an API Response
you can use the `PrintDumpTable()` extension method to return the results formatted in an easy to read Markdown table, e.g:

```csharp
public class GithubRepo
{
    public string Name { get; set; }
    public string Language { get; set; }
    public int Watchers { get; set; }
    public int Forks { get; set; }
}

var orgRepos = "https://api.github.com/orgs/dotnet/repos"
    .GetJsonFromUrl(httpReq => httpReq.UserAgent = "ServiceStack")
    .FromJson<GithubRepo[]>()
    .OrderByDescending(x => x.Watchers)
    .Take(10);

orgRepos.PrintDumpTable();
```

Which will output:

```
| #  | Name            | Language | Watchers | Forks |
|----|-----------------|----------|----------|-------|
| 1  | aspnetcore      | C#       | 20376    | 5793  |
| 2  | corefx          |          | 17905    | 5340  |
| 3  | core            | Shell    | 14975    | 3762  |
| 4  | roslyn          | C#       | 13757    | 3186  |
| 5  | coreclr         |          | 12436    | 2852  |
| 6  | efcore          | C#       | 9765     | 2454  |
| 7  | AspNetCore.Docs | C#       | 8268     | 20654 |
| 8  | orleans         | C#       | 7147     | 1622  |
| 9  | BenchmarkDotNet | C#       | 6048     | 639   |
| 10 | reactive        | C#       | 4679     | 587   |
```

### Circular References

The `T.PrintDump()` and `T.Dump()` extension methods can also be used on objects with cyclical references 
where it will display the first-level `ToString()` value of properties that have circular references.

Whilst our Text Serializers don't support serializing DTOs with cyclical dependencies (which are actively discouraged), 
the APIs below can be used instead to partially serialize objects where it uses the `ToString()` on any properties containing Circular references:

 - `T.ToSafeJson()`
 - `T.ToSafeJsv()`
 - `T.ToSafePartialObjectDictionary()`

The API used to detect whether an object has Circular References is also available for your use: 

```csharp
if (obj.HasCircularReferences()) {
}
```

### Inbuilt into ServiceStack JSV web service endpoint

As this feature has come in super useful for debugging, it's also included it as part of the JSV endpoint by simply appending `&debug` anywhere in the request’s query string. 

Even if you don’t use the new JSV endpoint you can still benefit from it by instantly being able to read the data provided by your web service. Here are some live examples showing the same web services called from the XML and JSV endpoint that shows the difference in readability:

#### Northwind

- [GetOrders?debug](https://northwind.netcore.io/jsv/reply/GetOrders?debug)
- [GetAllCustomers?debug](https://northwind.netcore.io/jsv/reply/GetAllCustomers?debug)
- [GetCustomerDetails?Id=ALFKI&debug](https://northwind.netcore.io/jsv/reply/GetCustomerDetails?Id=ALFKI&debug)


# Reflection Utils
Source: https://docs.servicestack.net/reflection-utils

Most of ServiceStack's libraries relies on the high-performance reusable utilities in ServiceStack.Text to power many of its features. 

## Dynamically adding Attributes

Many of ServiceStack features are lit up by decorating Request DTOs or Service Implementations with Attributes, In ServiceStack these attributes can also be dynamically added using the `.AddAttributes()` Extension method which enables an auto dynamic Fluent API for programmatically enabling behavior without needing to learn an alternative API for each feature, e.g. We can use this to add Custom Routes, [Restrict Services](/auth/restricting-services) and add [Filter Attributes](/filter-attributes) dynamically with:

```csharp
public class AppHost : AppHostBase 
{
    public AppHost() {

        typeof(MyRequest)
            .AddAttributes(new RouteAttribute("/myrequest"))
            .AddAttributes(new RouteAttribute("/myrequest/{UniqueId}"))
            .AddAttributes(new RestrictAttribute(RequestAttributes.Json))
            .AddAttributes(new MyRequestFilter());

        typeof(MyPoco)
            .AddAttributes(new DataContractAttribute())
            .GetProperty(nameof(MyPoco.LastName))
            .AddAttributes(new DataMemberAttribute { Name = "Surname" });
    }
}
```

::: info
Most Configuration in ServiceStack should be maintained in `Configure()` but as Services are auto-registered before `AppHost.Configure()` is called, Route attributes need to be added before this happens like in the AppHost Constructor or before `new AppHost().Init()`
:::

### Convert into different Types

Underlying [ServiceStack's AutoMapping support](/auto-mapping) is the `object.ConvertTo<T>` extension method which is able to convert any Type into a different Type, e.g:

```csharp
double two = "2".ConvertTo<double>();
```

It's a highly versatile feature were its able to co-erce into different types as expected, e.g. strings into Value and serialized complex Reference Types, between different number types, between different C# collections, etc.

### Call any method dynamically

One of the features in [#Script](https://sharpscript.net) is being able to call any .NET method dynamically with unknown types at runtime which it does using the `MethodInfo.GetInvoker()` extension method which returns a cached compiled delegate that's able to genericize access to any .NET method by transforming `MethodInfo` into the `MethodInvoker` delegate signature below:

```csharp
public delegate object MethodInvoker(object instance, params object[] args);
```

As an example lets call the simple method below dynamically:

```csharp
class TransformDouble
{
    public double Target { get; }
    public TransformDouble(double target) => Target = target;

    public double Add(double value) => Target + value;
}
```

First use Reflection to resolve the `Add` method then call the `GetInvoker()` extension method to resolve a cached `MethodInvoker` delegate:

```csharp
var method = typeof(TransformDouble).GetMethod("Add");
var add = method.GetInvoker();
```

Now we're able to to call the `add` method on any `TransformDouble` instance, e.g:

```csharp
object instance = new TransformDouble(1.0);

add(instance, 2.0) //= 3.0
```

If the argument types the method signature it calls the method directly, otherwise it calls `ConvertTo<T>` above to transform the parameter into the method argument type. So we can call the same `add` invoker with an `int` or a `string` argument and it will return the same value despite the method only being defined to accept a `double`, e.g:

```csharp
invoker(instance, 2)   //= 3.0
invoker(instance, "2") //= 3.0
```

### Call any constructor dynamically

In a similar way of how we can genericize any method we can also genericize any Constructor in the same way using the `ConstructorInfo.GetActivator()` extension method which returns a cached compiled delegate for any object constructor, e.g:

```csharp
var ctor = typeof(TransformDouble).GetConstructors()[0];
var activator = ctor.GetActivator();
```

Likewise we can use the `activator` to create new instances of `TransformDouble` with different runtime types, e.g:

```csharp
((TransformDouble)acivator(1.0)).Target //= 1.0

((TransformDouble)acivator(1)).Target   //= 1.0
((TransformDouble)acivator("1")).Target //= 1.0
```

### Converting Instances from an Object Dictionary

The `ToObjectDictionary` and `FromObjectDictionary` extension methods lets you convert instances into a loosely-typed Object Dictionary where it can be dynamically accessed and manipulated before being used to create and populate an instance of any type, e.g:

```csharp
var customer = new Customer { FirstName = "John", LastName = "Doe" };
var map = customer.MergeIntoObjectDictionary(new { Initial = "Z" });
map["DisplayName"] = map["FirstName"] + " " + map["Initial"] + " " + map["LastName"];
var employee = map.FromObjectDictionary<Employee>();

employee.DisplayName //= John Z Doe
```

Or use it to populate a late-bound type:

```csharp
Type managerType = typeof(Manager);
var manager = (Employee)map.FromObjectDictionary(managerType);
```

### Dynamically Populate Instances

Alternatively an untyped Object Dictionary can also be used to populate an existing instance with `PopulateInstance()`, e.g:

```csharp
var customer = new Customer { FirstName = "John", LastName = "Doe" };
map.PopulateInstance(customer);
```

Being able to treat Types as Object Dictionaries allows us to easily apply generic behavior to POCOs that would be otherwise be tedious like 
we could create a generic method to ensure that all string properties are trimmed with:

```csharp
T TrimStrings<T>(T instance)
{
    var updateStrings = new Dictionary<string, object>();
    instance.ToObjectDictionary().ForEach((key, value) => {
        if (value is string strValue && strValue?.Length > 0)
        {
            var trimmed = strValue.Trim();
            if (strValue != trimmed) // Only include types that need updating
                updateStrings[key] = trimmed; 
        }
    });
    updateStrings.PopulateInstance(instance);
    return instance;
}

var customer = TrimStrings(new Customer { FirstName = " John ", Initial = "Z", LastName = " Doe " });
```

All Reflection APIs make use of the Fast Reflection APIs below so in addition to convenience they also offer great performance.

## Fast Reflection APIs

The Reflection functionality is consolidated behind a formal API which includes multiple cascading implementations so it's able to use the fastest implementation available in [each supported platform](https://github.com/ServiceStackApps/HelloMobile#portable-class-library-support), i.e. for most .NET platforms we use the Reflection.Emit implementations when possible, when not available it falls back to using Compiled Expression trees, then finally falling back to using a Reflection-based implementation. 
 
This functionality is available using the `CreateGetter()` and `CreateSetter()` extension methods on both `PropertyInfo` or `FieldInfo` which you may find useful if you'd like to get better performance when populating runtime types dynamically.
 
The API examples below showcases the different APIs available:
 
```csharp
var runtimeType = typeof(MyType);
 
object instance = runtimeType.CreateInstance();
PropertyInfo pi = runtimeType.GetProperty("Id");
var idSetter = pi.CreateSetter();
var idGetter = pi.CreateGetter();
 
idSetter(instance, 1);
var idValue = idGetter(instance);
```
 
To squeeze out a bit more performance you can create a generic delegate to avoid some boxing/casting with:
 
```csharp
MyType instance = runtimeType.CreateInstance<MyType>();
var idSetter = pi.CreateSetter<MyType>();
var idGetter = pi.CreateGetter<MyType>();
```
 
All APIs also have field equivalents:
 
```csharp
FieldInfo fi = runtimeType.GetField("Id");
var idSetter = fi.CreateSetter();
var idGetter = fi.CreateGetter();
```
 
The `Create*` APIs above creates the compiled delegates which need to be cached to avoid the compilation penalty on subsequent usages. The `TypeProperties<T>` and `TypeFields<T>` classes offers fast cached access to these setters/getters which compiles all the **public** properties or fields on a per Type basis. 
 
### Runtime Type example

Some examples of using these classes:
 
```csharp
var runtimeType = instance.GetType(); //typeof(MyType)

var typeProps = TypeProperties.Get(runtimeType); //Equivalent to:
//  typeProps = TypeProperties<MyType>.Instance;
 
var propAccessor = typeProps.GetAccessor("Id");
propAccessor.PublicSetter(instance, 1);
var idValue = propAccessor.PublicGetter(instance);
```
 
Alternatively you can access property getters / setters individually:
 
```csharp
typeProps.GetPublicSetter("Id")(instance, 1);
var idValue = typeProps.GetPublicGetter("Id")(instance);
```
 
Whilst `TypeFields<T>` does the same for a Types **public fields** which is also able to work around the copy semantics of ValueTypes (typically lost when boxing) by utilizing the `ref` APIs below where we can use this to populate C# 7's new Value Tuples with:
 
```csharp
var typeFields = TypeFields.Get(typeof((string s, int i)));
 
var oTuple = (object)("foo", 1);
 
var item1Accessor = typeFields.GetAccessor("Item1");
var item2Accessor = typeFields.GetAccessor("Item2");
 
item1Accessor.PublicSetterRef(ref oTuple, "bar");
item2Accessor.PublicSetterRef(ref oTuple, 2);
 
var tuple = ((string s, int i))oTuple;
tuple.s //= bar
tuple.i //= 2
```


# JavaScript Utils
Source: https://docs.servicestack.net/js-utils

The ServiceStack.Text JSON Serializers are only designed for serializing Typed POCOs, but you can still use it to [deserialize dynamic JSON](/json-format#supports-dynamic-json) but you'd need to specify the Type to deserialize into on the call-site otherwise the value would be returned as a string.

A more flexible approach to read any arbitrary JavaScript or JSON data structures is to use the high-performance and memory efficient JSON utils in [#Script](https://sharpscript.net) implementation of JavaScript.

## Install

The `#Script` JSON and JS Utils are available from the [ServiceStack.Common](https://www.nuget.org/packages/ServiceStack.Common) NuGet package:

:::copy
`<PackageReference Include="ServiceStack.Common" Version="8.*" />`
:::

Which will enable access to the JSON API which preserves the Type which can be used to parse JavaScript or JSON literals:

```csharp
JSON.parse("1")       //= int 1 
JSON.parse("1.1")     //= double 1.1
JSON.parse("'a'")     //= string "a"
JSON.parse("{a:1}")   //= new Dictionary<string, object> { {"a", 1 } }
JSON.parse("[{a:1}]") //= new List<object> { new Dictionary<string, object> { { "a", 1 } } }
```

It can be used to parse dynamic JSON and any primitive JavaScript data type. The inverse API of `JSON.stringify()` is also available.

## Use C# Pattern Matching

C# Pattern matching provides a powerful and intuitive approach for introspecting JSON objects by leveraging C#'s native type checking and destructuring capabilities which is ideal when working with dynamic JSON data parsed into generic collections like `Dictionary<string, object>` and `List<object>` where it naturally integrates with C#'s control flow, making it easier to handle complex nested JSON structures while maintaining clean, expressive code that clearly communicates the expected data structure and extraction logic.

### Getting the client_id out of a ComfyUI Output

```csharp
var comfyOutput = JSON.ParseObject(json);
if (prompt.TryGetValue("prompt", out List<object> tuple) && tuple.Count > 3)
{
    if (tuple[3] is Dictionary<string, object?> extraData
        && extraData.TryGetValue("client_id", out string clientId))
    {
        Console.WriteLine(clientId);
    }
}
```

Equivalent implementation using System.Text.Json:

```csharp
using System.Text.Json;

var jsonDocument = JsonDocument.Parse(json);
var root = jsonDocument.RootElement;

// Get the first property value (equivalent to result.Values.First())
var firstProperty = root.EnumerateObject().FirstOrDefault();
if (firstProperty.Value.ValueKind == JsonValueKind.Object)
{
    var prompt = firstProperty.Value;

    if (prompt.TryGetProperty("prompt", out var promptElement)
        && promptElement.ValueKind == JsonValueKind.Array)
    {
        var promptArray = promptElement.EnumerateArray().ToArray();
        if (promptArray.Length > 3)
        {
            var extraDataElement = promptArray[3];
            if (extraDataElement.ValueKind == JsonValueKind.Object
                && extraDataElement.TryGetProperty("client_id", out var clientIdElement)
                && clientIdElement.ValueKind == JsonValueKind.String)
            {
                var clientId = clientIdElement.GetString();
                Console.WriteLine(clientId);
            }
        }
    }
}
```

### Parsing and mutating a Gemini API Request

As JSON Object just stored any JSON into untyped generic collections you can use C# pattern matching to navigate and mutate the JSON Object as done in this example which modifies an Gemini API Request to replace the `inline_data.data` string with its length to make it suitable for logging:

```csharp
var obj = JSON.ParseObject(origJson);
if (obj.TryGetValue("contents", out List<object> contents))
{
    foreach (var content in contents.OfType<Dictionary<string,object>>())
    {
        if (content.TryGetValue("parts", out List<object> parts))
        {
            foreach (var part in parts.OfType<Dictionary<string,object>>())
            {
                if (part.TryGetValue("inline_data", out Dictionary<string,object> inlineData)
                    && inlineData.TryGetValue("data", out string data))
                {
                    inlineData["data"] = $"({data.Length})";
                }
            }
        }
    }
}
Console.WriteLine(JSON.stringify(obj));
```

This would be an equivalent implementation using **System.Text.Json** to parse and navigate the JSON data structure
with `JsonDocument`:

```csharp
using System.Text.Json;

var jsonDocument = JsonDocument.Parse(json);
var root = jsonDocument.RootElement;

if (root.TryGetProperty("contents", out var contentsElement)
    && contentsElement.ValueKind == JsonValueKind.Array)
{
    foreach (var contentElement in contentsElement.EnumerateArray())
    {
        if (contentElement.ValueKind == JsonValueKind.Object
            && contentElement.TryGetProperty("parts", out var partsElement)
            && partsElement.ValueKind == JsonValueKind.Array)
        {
            foreach (var partElement in partsElement.EnumerateArray())
            {
                if (partElement.ValueKind == JsonValueKind.Object
                    && partElement.TryGetProperty("inline_data", out var inlineDataElement)
                    && inlineDataElement.ValueKind == JsonValueKind.Object
                    && inlineDataElement.TryGetProperty("data", out var dataElement)
                    && dataElement.ValueKind == JsonValueKind.String)
                {
                    var data = dataElement.GetString();
                    // Note: System.Text.Json JsonDocument is read-only
                    // To modify, you'd need to reconstruct the JSON or use JsonNode
                    Console.WriteLine($"Data length: {data?.Length}");
                }
            }
        }
    }
}
Console.WriteLine(jsonDocument.RootElement);
```

But as it's a read-only data structure you'd need to reconstruct the JSON to modify it. To create an equivalent modified JSON for logging, you could use `JsonNode` for mutable operations instead:

```csharp
using System.Text.Json;
using System.Text.Json.Nodes;

var jsonNode = JsonNode.Parse(json);

if (jsonNode is JsonObject rootObj
    && rootObj["contents"] is JsonArray contentsArray)
{
    foreach (var contentNode in contentsArray)
    {
        if (contentNode is JsonObject contentObj
            && contentObj["parts"] is JsonArray partsArray)
        {
            foreach (var partNode in partsArray)
            {
                if (partNode is JsonObject partObj
                    && partObj["inline_data"] is JsonObject inlineDataObj
                    && inlineDataObj["data"] is JsonValue dataValue
                    && dataValue.TryGetValue<string>(out var data))
                {
                    // Modify the data for logging
                    inlineDataObj["data"] = $"({data.Length})";
                }
            }
        }
    }
}

// Output the modified JSON for logging
Console.WriteLine(jsonNode.ToJsonString());
```

### Register JS Utils in ServiceStack.Text

JS Utils is already pre-configured in ServiceStack Web Apps to handle serializing & deserializing `object` types. 

You can also configure to use it in **ServiceStack.Text** Typed JSON Serializers **outside of ServiceStack** with:

```csharp
JS.Configure();
```

## Eval

Eval is useful if you want to execute custom JavaScript functions, or if you want to have a text DSL or scripting language for executing custom logic or business rules you want to be able to change without having to compile or redeploy your App. It uses [#Script Sandbox](https://sharpscript.net/docs/sandbox) which lets you evaluate the script within a custom scope that defines what functions and arguments it has access to, e.g:

```csharp
public class CustomMethods : ScriptMethods
{
    public string reverse(string text) => new string(text.Reverse().ToArray());
}

var scope = JS.CreateScope(
         args: new Dictionary<string, object> { { "arg", "value"} }, 
    functions: new CustomMethods());

JS.eval("arg", scope)                                        //= "value"
JS.eval("reverse(arg)", scope)                               //= "eulav"
JS.eval("3.itemsOf(arg.reverse().padRight(8, '_'))", scope) //= ["eulav___", "eulav___", "eulav___"]

//= { a: ["eulav___", "eulav___", "eulav___"] }
JS.eval("{a: 3.itemsOf(arg.reverse().padRight(8, '_')) }", scope)
```

#### Evaluating DSL's within a custom Context

`#Script` is useful for creating a late-bound sandboxed environment pre-configured with all functionality you want to enable access to
without forcing implementation coupling in your project dependencies, e.g. you can enable binary serialization that all your project dependencies can use with:

```csharp
var scope = context.CreateScope(new Dictionary<string, object> {
    ["target"] = person
});
var result = (ReadOnlyMemory<byte>)JS.eval("serialize(target)", scope);
```

Where the `serialize()` method only needs to be registered once in the host project that creates the context that all your DSL's are executed within, 
the implementations of which can later be substituted without any changes to existing scripts or needing to change any package/Assembly references.

## JavaScript Expressions

The JavaScript Expressions support in ServiceStack follows the [syntax tree used by Esprima](https://esprima.readthedocs.io/en/latest/syntax-tree-format.html), JavaScript's leading lexical language parser for JavaScript, but adapted to suit C# conventions using PascalCase properties and each AST Type prefixed 
with `Js*` to avoid naming collisions with C#'s LINQ Expression Types which often has the same name. 

So Esprima's [MemberExpression](https://esprima.readthedocs.io/en/latest/syntax-tree-format.html#member-expression) maps to [JsMemberExpression](https://github.com/ServiceStack/ServiceStack/blob/master/src/ServiceStack.Common/Script/JsMemberExpression.cs) in #Script. 

In addition to adopting Esprima's AST data structures, #Script can also [emit the same serialized Syntax Tree](https://sharpscript.net/docs/expression-viewer#expression=1%20-%202%20%2B%203%20*%204%20%2F%205) that Esprima generates from any AST Expression, e.g:

```csharp
// Create AST from JS Expression
JsToken expr = JS.expression("1 - 2 + 3 * 4 / 5");

// Convert to Object Dictionary in Esprima's Syntax Tree Format
Dictionary<string, object> esprimaAst = expr.ToJsAst();

// Serialize as Indented JSON
esprimaAst.ToJson().IndentJson().Print();
```

Which will display the same output as seen in the new [JS Expression Viewer](https://sharpscript.net/docs/expression-viewer#expression=1%20-%202%20%2B%203%20*%204%20%2F%205):

[![](/img/pages/sharpscript/syntax/expression-viewer.png)](https://sharpscript.net/docs/expression-viewer#expression=1%20-%202%20%2B%203%20*%204%20%2F%205)

From the AST output we can visualize how the different operator precedence is applied to an Expression. 
Expression viewer also lets us explore and evaluate different JavaScript Expressions with custom arguments:

[![](/img/pages/sharpscript/syntax/logical-expression.png)](https://sharpscript.net/docs/expression-viewer#expression=1%20%3C%202%20%26%26%20(t%20%7C%7C%203%20%3E%204)%20%26%26%20f&t=true&f=false)

An [abusage Brendan Eich regrets](https://brendaneich.com/2012/04/the-infernal-semicolon/) that is enforced is limiting
the `||` and `&&` binary operators to boolean expressions, which themselves always evaluate to a boolean value.

Instead to replicate `||` coalescing behavior on falsy values you can use C#'s `??` null coalescing operator as seen in:

[![](/img/pages/sharpscript/syntax/ternary-expression.png)](https://sharpscript.net/docs/expression-viewer#expression=a%20%3E%20(c%20%3F%3F%20b)%20%3F%20a%20%3A%20b&a=1&b=2)

### Lambda Expressions

You can use lambda expressions in all functional filters:

[![](/img/pages/sharpscript/syntax/lambda-expression.png)](https://sharpscript.net/docs/expression-viewer#expression=map(range(1%2Ccount)%2C%20x%20%3D%3E%20x%20*%20x)&count=5)

Using either normal lambda expression syntax:

::: v-pre
```hbs
{{ customers |> zip(x => x.Orders)
   |> let(x => { c: x[0], o: x[1] })
   |> where(_ => o.Total < 500)
   |> map(_ => o)
   |> htmlDump }}
```
:::

Or shorthand syntax for single argument lambda expressions which can instead use `=>` without brackets or named arguments where it will 
be implicitly assigned to the `it` binding:

::: v-pre
```hbs
{{ customers |> zip => it.Orders
   |> let => { c: it[0], o: it[1] }
   |> where => o.Total < 500
   |> map => o
   |> htmlDump }}
```
:::

As it's results in more wrist-friendly and readable code, [most LINQ Examples](https://sharpscript.net/linq/projection-operators#linq15-selectmany---compound-from-2) use the shorthand lambda expression syntax above.

### Shorthand properties

Other language enhancements include support for [JavaScript's shorthand property names](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Object_initializer#Syntax):

::: v-pre
```hbs
{{ {name,age} }}
```

But like C# also lets you use member property names:

```hbs
{{ people |> let => { it.Name, it.Age } |> select: {Name},{Age} }}
```
:::

### Template Literals

Many of ES6/7 features are also implemented like Template Literals:

[![](/img/pages/sharpscript/syntax/template-literals.png)](https://sharpscript.net/docs/expression-viewer#expression=%60Hello%2C%20%24%7Bname%7D!%20%24%7Ba%20%3F%20pow(1%2B2%2Ca)%20%3A%20''%7D%60&name='World'&a=3)

::: info
Backtick quoted strings also adopt the same [escaping behavior of JavaScript strings](https://sharpscript.net/docs/syntax#template-literals) 
whilst all other quoted strings preserve unescaped string values
:::

### Spread Operators

Other advanced ES6/7 features supported include the object spread, array spread and argument spread operators:

[![](/img/pages/sharpscript/syntax/object-spread.png)](https://sharpscript.net/docs/expression-viewer#expression=keys(%7B%20...a%2C%20c%3A3%2C%20...%7Bd%3A%204%7D%20%7D)&a=%7B%20b%3A%202%20%7D)

[![](/img/pages/sharpscript/syntax/array-spread.png)](https://sharpscript.net/docs/expression-viewer#expression=%5B1%2C%20...%5Brange(2%2Cpow(...%5B3%2Ce%5D))%5D%2C%201%5D&e=2)

### Bitwise Operators

All JavaScript Bitwise operators are also supported:

[![](/img/pages/sharpscript/syntax/bitwise-operators.png)](https://sharpscript.net/docs/expression-viewer#expression=%5B3%251%2C%203%261%2C%203%7C1%2C%203%5E1%2C%203%3C%3C1%2C%203%20%3E%3E%201%2C%20~1%5D&e=2)

Essentially #Script supports most JavaScript Expressions, not statements which are covered with 
[Blocks support](https://sharpscript.net/docs/blocks) 
or mutations using Assignment Expressions and Operators. All assignments still need to be explicitly performed through an 
[Assignment Filter](https://sharpscript.net/docs/default-scripts#assignment).

### Evaluating JavaScript Expressions

The built-in JavaScript expressions support is also useful outside of dynamic pages where they can be evaluated with `JS.eval()`:

```csharp
JS.eval("pow(2,2) + pow(4,2)") //= 20
```

The difference over JavaScript's eval being that methods are calling [C# script methods](https://sharpscript.net/docs/filters-reference) in a sandboxed context.

By default expressions are executed in an empty scope, but can also be executed within a custom scope which can be used to define the 
arguments expressions are evaluated with:

```csharp
var scope = JS.CreateScope(args: new Dictionary<string, object> {
    ["a"] = 2,
    ["b"] = 4,
}); 
JS.eval("pow(a,2) + pow(b,2)", scope) //= 20
```

Custom methods can also be introduced into the scope which can override existing filters by using the same name and args count, e.g:

```csharp
class MyMethods : ScriptMethods {
    public double pow(double arg1, double arg2) => arg1 / arg2;
}
var scope = JS.CreateScope(functions: new MyMethods());
JS.eval("pow(2,2) + pow(4,2)", scope); //= 3
```

An alternative to injecting arguments by scope is to wrap the expression in a lambda expression, e.g:

```csharp
var expr = (JsArrowFunctionExpression)JS.expression("(a,b) => pow(a,2) + pow(b,2)");
```

Which can then be invoked with positional arguments by calling `Invoke()`, e.g:

```csharp
expr.Invoke(2,4)        //= 20
expr.Invoke(2,4, scope) //= 3
```

### Parsing JS Expressions

Evaluating JS expressions with `JS.eval()` is a wrapper around parsing the JS expression into an AST tree then evaluating it, e.g:

```csharp
var expr = JS.expression("pow(2,2) + pow(4,2)");
expr.Evaluate(); //= 20
```

When needing to evaluate the same expression multiple times you can cache and execute the AST to save the cost of parsing the expression again.

### DSL example

If implementing a DSL containing multiple expressions as done in many of the [Block argument expressions](https://sharpscript.net/docs/blocks) 
you can instead use the `ParseJsExpression()` extension method to return a literal Span advanced to past the end of the expression with the parsed 
AST token returned in an `out` parameter.

This is what the Each block implementation uses to parse its argument expression which can contain a number of LINQ-like expressions:

```csharp
var literal = "where c.Age == 27 take 1 + 2".AsSpan();
if (literal.StartsWith("where "))
{
    literal = literal.Advance("where ".Length);     // 'c.Age == 27 take 1 + 2'
    literal = literal.ParseJsExpression(out where); // ' take 1 + 2'
}
literal = literal.AdvancePastWhitespace();          // 'take 1 + 2'
if (literal.StartsWith("take "))
{
    literal = literal.Advance("take ".Length);      // '1 + 2'
    literal = literal.ParseJsExpression(out take);  // ''
}
```

Resulting in `where` populated with the [c.Age == 27](https://sharpscript.net/docs/expression-viewer#expression=c.Age%20%3D%3D%2027&c=%7B%20Age%3A27%20%7D) `BinaryExpression` and `take` with the [1 + 2](https://sharpscript.net/docs/expression-viewer#expression=1%20%2B%202)
`BinaryExpression`.

### Immutable and Comparable

Unlike C#'s LINQ Expressions which can't be compared for equality, #Script Expressions are both Immutable and Comparable which can be used 
in caches and compared to determine if 2 Expressions are equivalent, e.g:

```csharp
var expr = new JsLogicalExpression(
    new JsBinaryExpression(new JsIdentifier("a"), JsGreaterThan.Operator, new JsLiteral(1)),
    JsAnd.Operator,
    new JsBinaryExpression(new JsIdentifier("b"), JsLessThan.Operator, new JsLiteral(2))
);

expr.Equals(JS.expression("a > 1 && b < 2"));  //= true

expr.Equals(new JsLogicalExpression(
    JS.expression("a > 1"), JsAnd.Operator, JS.expression("b < 2")
));                                            //= true
```

Showing Expressions whether created programmatically, entirely from strings or any combination of both can be compared for equality and 
evaluated in the same way:

```csharp
var scope = JS.CreateScope(args:new Dictionary<string, object> {
    ["a"] = 2,
    ["b"] = 1
});

expr.Evaluate(scope) //= true
```

## Helper Types

As scripting makes prevalent usage of Object Dictionaries and Key/Value pairs there's a couple of UX Friendly Generic collections to
reduce boilerplate if you're repeatedly using these collections:

```csharp
var objDict = new ObjectDictionary { //inherits Dictionary<string,object>
    ["one"] = 1,
    ["foo"] = "bar"
}

var strDict = new StringDictionary { //inherits Dictionary<string,string>
    ["one"] = "1",
    ["foo"] = "bar"
}

var kvps = new KeyValuePairs {
    KeyValuePairs.Create("one",1),
    KeyValuePairs.Create("foo","bar"),
};

//instead of
var kvps = new List<KeyValuePair<string,object>> {
    new KeyValuePair<string,object>("one",1),
    new KeyValuePair<string,object>("foo","bar"),
}
```


# Adhoc Utils
Source: https://docs.servicestack.net/adhoc-utils

## Image Utils

The `Image.ResizeToPng()` and `Image.CropToPng()` [extension methods](https://github.com/ServiceStack/ServiceStack/blob/master/src/ServiceStack/ImageExtensions.cs) 
can be used to resize and crop `System.Drawing` Images, e.g:

```csharp
[AddHeader(ContentType = "image/png")]
public Stream Get(Resize request)
{
    var imageFile = VirtualFiles.GetFile(request.Path);
    if (imageFile == null)
        throw HttpError.NotFound(request.Path + " was not found");

    using (var stream = imageFile.OpenRead())
    using (var img = Image.FromStream(stream))
    {
        return img.ResizeToPng(request.Width, request.Height);
    }
}

[AddHeader(ContentType = "image/png")]
public Stream Get(Crop request)
{
    var imageFile = VirtualFiles.GetFile(request.Path);
    if (imageFile == null)
        throw HttpError.NotFound(request.Path + " was not found");

    using (var stream = imageFile.OpenRead())
    using (var img = Image.FromStream(stream))
    {
        return img.CropToPng(request.Width, request.Height, request.StartX, request.StartY);
    }
}
```

## Enum Utils

The `EnumUtils.GetValues()`, `IEnumerable<Enum>.ToKeyValuePairs()` and `Enum.ToDescription()` extension methods
makes it easy to create data sources from Enums that can be annotated with `[ApiMember]` and `[Description]` attributes:

```csharp
List<KeyValuePair<string, string>> Titles => EnumUtils.GetValues<Title>()
    .Where(x => x != Title.Unspecified)
    .ToKeyValuePairs();

List<string> FilmGenres => EnumUtils.GetValues<FilmGenres>()
    .Map(x => x.ToDescription());
```


# Simple Container
Source: https://docs.servicestack.net/simple-ioc

[SimpleContainer](https://github.com/ServiceStack/ServiceStack/blob/master/src/ServiceStack.Common/SimpleContainer.cs) is an IOC that implements [IContainer](https://github.com/ServiceStack/ServiceStack/blob/master/src/ServiceStack.Interfaces/IContainer.cs) - a minimal interface for a useful IOC:

```csharp
public interface IContainer
{
    Func<object> CreateFactory(Type type);

    IContainer AddSingleton(Type type, Func<object> factory);
    
    IContainer AddTransient(Type type, Func<object> factory);

    object Resolve(Type type);

    bool Exists(Type type);
}
```

It's late-bound API supports registering dependencies in the 2 most useful Scopes: Singleton and Transient. Leveraging the utility of extension methods, every IOC implementing `IContainer` also gains the same [Typed Generic API](https://github.com/ServiceStack/ServiceStack/blob/710da129005f3df5dc93ea0e51e6d8a8681ec04e/src/ServiceStack.Common/SimpleContainer.cs#L114), e.g: 

```csharp
container.AddTransient<IFoo,Foo>();
container.AddTransient<IFoo>(() => new Foo());
container.AddTransient<IBar>(() => new Bar());
container.AddTransient(() => new FooImpl());
container.AddTransient<FooImpl>();

container.AddSingleton(typeof(Foo));
container.AddSingleton(() => foo);

var foo = container.Resolve<IFoo>();
var bar = container.Resolve(typeof(IBar));

var hasFoo = container.Exists<IFoo>();
```

Both `Funq.Container` and `SimpleContainer` implement the `IContainer` interface which ServiceStack's [SharpPagesFeature](https://sharpscript.net/docs/script-pages) utilizes to replace the TemplateContext's built-in IOC to use Funq where it shares the same IOC instance and is able to resolve ServiceStack's AppHost dependencies.

## Fast, small, minimal dependency IOC

[Funq](/ioc) was originally chosen for ServiceStack because it was the amongst the fastest, smallest and most embeddable IOC's available with a pleasant Typed API, which is integrated into `ServiceStack.dll` where it provides all IOC functionality in ServiceStack.

`SimpleContainer` is even smaller and faster than Funq and only requires a dependency to `ServiceStack.Common.dll`. It supports AutoWiring, constructor and public property injection but not Funq's other less used features like Child Containers, named dependencies and Request Scoped dependencies.


# Caching Providers
Source: https://docs.servicestack.net/caching

As caching is an essential technology in the development of high-performance web services, ServiceStack has a number of different caching options available that each share the same
[common client interface (ICacheClient)](https://github.com/ServiceStack/ServiceStack/blob/master/src/ServiceStack.Interfaces/Caching/ICacheClient.cs)
for the following cache providers:

* [Memory Cache](https://github.com/ServiceStack/ServiceStack/blob/master/src/ServiceStack/Caching/MemoryCacheClient.cs) - Useful for single host web services without needing any infrastructure dependencies.
* [Redis](https://github.com/ServiceStack/ServiceStack.Redis) - A fast key-value store with non-volatile persistent storage and support for rich comp-sci data structures.
* [OrmLiteCacheClient](https://www.nuget.org/packages/ServiceStack.Server) - Supports all [OrmLite's RDBMS providers](https://github.com/ServiceStack/ServiceStack.OrmLite/#download) for using an existing RDBMS as a distributed cache.
* [Memcached](https://nuget.org/packages/ServiceStack.Caching.Memcached) - The original, tried and tested distributed memory caching provider.
* [Aws DynamoDB](https://www.nuget.org/packages/ServiceStack.Aws/) - Uses Amazon's Dynamo DB backend hosted on Amazon Web Services
* [Azure Table Storage](/azure#virtual-filesystem-backed-by-azure-blob-storage) - Uses Azure Table Storage for when your application is hosted on Azure.

### Async Cache Clients

All remote Caching Providers also implement the [ICacheClientAsync](https://github.com/ServiceStack/ServiceStack/blob/master/src/ServiceStack.Interfaces/Caching/ICacheClientAsync.cs) async APIs whilst any other `ICacheClient` only providers like the local in-memory `MemoryCacheClient` are still able to use the `ICacheClientAsync` interface as they'll return an [Async Wrapper](https://github.com/ServiceStack/ServiceStack/blob/master/src/ServiceStack/Caching/CacheClientAsyncWrapper.cs) over the underlying sync APIs. 

So even if you're currently only using `MemoryCacheClient` or your own `ICacheClient` sync implementation, you can still use the async Caching Provider API now and easily switch to an async caching provider in future without code changes.

The Async Caching Provider APIs are accessible via the `CacheAsync` property in ServiceStack `Service` or `ServiceStackController` classes, e.g:

```csharp
public async Task<object> Any(MyRequest request)
{
    var item = await CacheAsync.GetAsync<Item>("key");
    //....
}

public class HomeController : ServiceStackController
{
    public async Task<ActionResult> Index()
    {
        var item = await CacheAsync.GetAsync<Item>("key");
    }
}
```

Whilst outside of ServiceStack you can `AppHost.GetCacheClientAsync()`, e.g:

```csharp
var cache = HostContext.AppHost.GetCacheClientAsync();
var item = await cache.GetAsync<Item>("key");
```

### Configure Caching Providers

To configure which cache should be used, the particular client has to be registered in the IoC container against the `ICacheClient` interface:

### Memory cache:

By default ServiceStack registers an MemoryCacheClient by default when no `ICacheClient` is registered so no registration is necessary.

```csharp
//services.AddSingleton<ICacheClient>(new MemoryCacheClient());
```

Even if you have an alternative `ICacheClient` registered you can still access the in memory cache via the `LocalCache` property in your Services
and ServiceStack MVC Controllers or anywhere else via the `HostContext.AppHost.GetMemoryCacheClient()` singleton as well as
`[CacheResponse(UseLocalCache=true)]` when using the [Cache Response Attribute](/cacheresponse-attribute).

### Redis

```csharp
services.AddSingleton<IRedisClientsManager>(c => 
    new RedisManagerPool("localhost:6379"));

services.AddSingleton(c => c.GetRequiredService<IRedisClientsManager>().GetCacheClient());
```

##### NuGet Package: [ServiceStack.Redis](http://www.nuget.org/packages/ServiceStack.Redis)

### OrmLite

```csharp
//Register OrmLite Db Factory if not already
services.AddSingleton<IDbConnectionFactory>(c => 
    new OrmLiteConnectionFactory(connString, SqlServerDialect.Provider));

services.AddSingleton<ICacheClient, OrmLiteCacheClient>();

//Create 'CacheEntry' RDBMS table if it doesn't exist already
appHost.Resolve<ICacheClient>().InitSchema(); 
```

#### SQL Server Memory Optimized Cache

SQL Server's Memory Optimized support can be used to improve the performance of `OrmLiteCacheClient` 
by configuring it to use the above In Memory Table Schema instead, e.g:

```csharp
services.AddSingleton<ICacheClient>(c => 
    new OrmLiteCacheClient<SqlServerMemoryOptimizedCacheEntry>());
```

##### NuGet Package: [ServiceStack.Server](http://www.nuget.org/packages/ServiceStack.Server)

### Memcached

```csharp
services.AddSingleton<ICacheClient>(
    new MemcachedClientCache(new[] { "127.0.0.0" }); //Add Memcached hosts
```

##### NuGet Package: [ServiceStack.Caching.Memcached](http://www.nuget.org/packages/ServiceStack.Caching.Memcached)

### AWS DynamoDB

```csharp
var awsDb = new AmazonDynamoDBClient(
    AWS_ACCESS_KEY, AWS_SECRET_KEY, RegionEndpoint.USEast1);

services.AddSingleton<IPocoDynamo>(new PocoDynamo(awsDb));
services.AddSingleton<ICacheClient>(c => 
    new DynamoDbCacheClient(c.GetRequiredService<IPocoDynamo>()));

var cache = appHost.Resolve<ICacheClient>();
cache.InitSchema();
```

##### NuGet Package: [ServiceStack.Aws](http://www.nuget.org/packages/ServiceStack.Aws)

### Azure:

```csharp
services.AddSingleton<ICacheClient>(new AzureTableCacheClient(cacheConnStr));
```

##### NuGet Package: [ServiceStack.Azure](http://www.nuget.org/packages/ServiceStack.Azure)

### Multi CacheClient

The `MultiCacheClient` can be used to utilize a write-through multi-tiered cache client where all "writes" are made to all
registered cache providers whilst "reads" are only accessed until a value exists. E.g. you can register a local memory
and redis server backed Cache Client with:

```csharp
services.AddSingleton<ICacheClient>(c => new MultiCacheClient(
    new MemoryCacheClient(),
    c.GetRequiredService<IRedisClientsManager>().GetCacheClient()));
```

## Cache a response of a service

To cache a response you simply have to call `ToOptimizedResultUsingCache` which is an extension method existing in `ServiceStack.ServiceHost`.

In your service:

```csharp
public class OrdersService : Service
{
    public object Get(CachedOrders request)
    {
        var cacheKey = "unique_key_for_this_request";
        return base.Request.ToOptimizedResultUsingCache(base.Cache,cacheKey,()=> 
            {
                //Delegate is executed if item doesn't exist in cache 
                //Any response DTO returned here will be cached automatically
            });
    }
}
```

::: info Tip
There exists a class named [UrnId](https://github.com/ServiceStack/ServiceStack/blob/master/src/ServiceStack.Common/UrnId.cs) which provides helper methods to create unique keys for an object
:::

`ToOptimizedResultUsingCache` also has an overload which provides a parameter to set the timespan when the cache should be deleted (marked as expired). If now a client calls the same service method a second time and the cache expired, the provided delegate, which returns the response DTO, will be executed a second time.

```csharp
var cacheKey = "some_unique_key";
//Cache should be deleted in 1h
var expireInTimeSpan = new TimeSpan(1, 0, 0);
return base.Request.ToOptimizedResultUsingCache(
    base.Cache, cacheKey, expireInTimeSpan, ...)
```

## Delete cached responses

If now for example an order gets updated and the order was cached before the update, the webservice will still return the same result, because the cache doesn't know that the order has been updated.

So there are two options:

* Use **time based** caching (and expire cache earlier)
* Cache on **validity**

::: info
When the cache is based on **validity** the caches are invalidated manually (e.g. when a user modified his profile, > clear his cache) which means you always get the latest version and you never need to hit the database again to rehydrate the cache if it hasn't changed, which will save resources
:::

So if the order gets updated, you should delete the cache manually:

```csharp
public class CachedOrdersService : Service
{
    public async Task Put(CachedOrders request)
    {
        //The order gets updated...
        var cacheKey = "some_unique_key_for_order";
        await CacheAsync.ClearCachesAsync(cacheKey);
    }
}
```

If now the client calls the web service to request the order, he'll get the latest version.

### LocalCache

As it sometimes beneficial to have access to a local in-memory Cache in addition to your registered `ICacheClient`
[Caching Provider](/caching) we also pre-register a `MemoryCacheClient` that all your Services now have access to from the `LocalCache`
property, i.e:

```csharp
MemoryCacheClient LocalCache { get; }
```

This doesn't affect any existing functionality that utilizes a cache like Sessions which continue to use
your registered `ICacheClient`, but it does let you change which cache you want different responses to use, e.g: 

```csharp
var cacheKey = "unique_key_for_this_request";
return base.Request.ToOptimizedResultUsingCache(LocalCache, cacheKey, () => {
    //Delegate is executed if item doesn't exist in cache 
});
```

Or if you're using the [CacheResponse](/cacheresponse-attribute) attribute you can specify to cache responses in the local cache with:

```csharp
[CacheResponse(LocalCache = true)]
public object Any(MyRequest request) { ... }
```

::: info
If you don't register a `ICacheClient` ServiceStack automatically registers a `MemoryCacheClient` for you 
which will also refer to the same instance registered for `LocalCache`
:::

## [ICacheClientExtended](https://github.com/ServiceStack/ServiceStack/blob/master/src/ServiceStack.Interfaces/Caching/ICacheClientExtended.cs)

The [ICacheClientExtended](https://github.com/ServiceStack/ServiceStack/blob/master/src/ServiceStack.Interfaces/Caching/ICacheClientExtended.cs)
API is used to to provide additional non-core functionality to our most popular 
[Caching providers](/caching):

* Redis
* OrmLite RDBMS
* In Memory
* AWS
* Azure

The new API's are added as Extension methods on `ICacheClient` so they're easily accessible without casting, the new API's available include:
  
* GetKeysByPattern(pattern) - return keys matching a wildcard pattern
* GetAllKeys() - return all keys in the caching provider
* GetKeysStartingWith() - Streaming API to return all keys Starting with a prefix

With these new API's you can now easily get all active User Sessions using any of the supported Caching providers above with:

```csharp
var sessionPattern = IdUtils.CreateUrn<IAuthSession>(""); //= urn:iauthsession:
var sessionKeys = Cache.GetKeysStartingWith(sessionPattern).ToList();

var allSessions = Cache.GetAll<IAuthSession>(sessionKeys);
```

### CacheClient with Prefix

The `CacheClientWithPrefix` class lets you decorate any `ICacheClient` to prefix all cache keys using the `.WithPrefix()` extension method. This could be used to easily enable multi-tenant usage of a single redis instance, e.g:

```csharp
services.AddSingleton(c => 
    c.GetRequiredService<IRedisClientsManager>().GetCacheClient().WithPrefix("site1"));
```

## Live Example and code

A live demo of the ICacheClient is available in [The ServiceStack.Northwind's example project](https://northwind.netcore.io/). Here are some requests to cached services:

* [/customers](https://northwind.netcore.io/cached/customers)
* [/customers/ALFKI](https://northwind.netcore.io/cached/customers/ALFKI)
* [/customers/ALFKI/orders](https://northwind.netcore.io/cached/customers/ALFKI/orders)

Which are simply existing web services wrapped using **ICacheClient** that are contained in [CachedServices.cs](https://github.com/ServiceStack/ServiceStack.Examples/blob/master/src/ServiceStack.Northwind/ServiceStack.Northwind.ServiceInterface/CachedServices.cs)


# HTTP Caching
Source: https://docs.servicestack.net/http-caching

ServiceStack's HTTP Caching support transparently improves the behavior of existing `ToOptimized` Cached 
Responses, provides a typed API to opt-in to **HTTP Client** features, introduces a simpler declarative API 
for enabling both **Server and Client Caching** of Services and also includes Cache-aware clients that are 
able to improve the performance and robustness of all existing .NET Service Clients - functionality that's 
especially valuable to bandwidth-constrained Xamarin.iOS / Xamarin.Android clients offering improved 
performance and greater resilience.

The new caching functionality is encapsulated in the new `HttpCacheFeature` plugin that's pre-registered 
by default and can be removed to disable the new HTTP Caching behavior with:

```csharp
Plugins.RemoveAll(x => x is HttpCacheFeature);
```

Caching options in ServiceStack include using the existing `ToOptimizedResult*` API's to create **Server Caches** within your Services as well as returning a customized `HttpResult` to take advantage of **HTTP Caching** Client features. 

## [CacheResponse Attribute](/cacheresponse-attribute)

The new declarative `[CacheResponse]` [Request Filter attribute](/filter-attributes) provides the best of both worlds supporting both Server and HTTP Client features which is both non-invasive and simple to enhance, as a result we expect it to be the most popular option for adding caching to your Services in future.

## [Cache-Aware Clients](/cache-aware-clients)

The **Server Caching** and **HTTP Caching** features in ServiceStack will automatically benefit Websites as browsers have excellent support for HTTP Caching. But .NET Desktop Apps or Xamarin.iOS and Xamarin.Android mobile clients wont see any of these benefits since none of the existing Service Clients have support for **HTTP Caching**. To complete the story we've also developed cache-aware Service Clients that can be used to enhance all existing .NET Service Clients which manages its own local cache as instructed by the HTTP Caching directives.

### Server Caching

To explain the new HTTP Caching features we'll revisit the ServiceStack's previous caching support which
enables what we refer to as **Server Caching** where the response of a Service is cached in the registered
[Caching Provider](/caching)
by calling the `ToOptimizedResult*` API's which lets you programmatically construct the Cache Key and/or
how long the cache should be persisted for, e.g:

```csharp
public class OrdersService : Service
{
    public object Any(GetCustomers request)
    {
        //Good candidates: request.ToGetUrl() or base.Request.RawUrl
        var cacheKey = "unique_key_for_this_request";
        var expireCacheIn = TimeSpan.FromHours(1);

        return Request.ToOptimizedResultUsingCache(Cache, cacheKey, expireCacheIn, 
            () => {
                //Delegate executed only if item doesn't already exist in cache 
                //Any response DTO returned is cached on subsequent requests
            });
    }
}
```

As the name indicates this stores the most optimal representation of the Service Response in the registered 
`ICacheClient`, so for example if a client called the above API with `Accept: application/json` and 
`Accept-Encoding: deflate, gzip` HTTP Request Headers ServiceStack would store the deflated serialized JSON 
bytes in the Cache and on subsequent requests resulting in the same cache key would write the compressed 
deflated bytes directly to the Response OutputStream - saving both CPU and bandwidth.

#### More Optimal OptimizedResults

But there's an even more optimal result we could return instead: **Nothing** :) and save even more CPU and
bandwidth! Which is precisely what the
[HTTP Caching](https://www.w3.org/Protocols/rfc2616/rfc2616-sec13.html) directives built into the HTTP spec
allow for. To enable it you'd need to return additional HTTP Headers to the client containing the necessary 
metadata they can use to determine when their locally cached responses are valid. Typically this is the 
[Last-Modified](https://www.w3.org/Protocols/rfc2616/rfc2616-sec13.html#sec13.3.1) 
date of when the Response/Resource was last modified or an 
[Entity Tag](https://www.w3.org/Protocols/rfc2616/rfc2616-sec13.html#sec13.3.2) containing an opaque string
the Server can use to determine whether the client has the most up-to-date response.

The most optimal cache validator we can use for existing `ToOptimizedResult*` API's is the **Last Modified**
date which is now being cached along with the response. An additional instruction we need to return to the 
client is the 
[Cache-Control](https://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.9) HTTP Response Header
which instructs the client what caching behavior to apply to the server response. As we want the new behavior 
to work transparently without introducing caching issues to existing Services, we've opted for a conservative:

```ini
Cache-Control: max-age=0
```
    
Which tells the client to treat the server response as immediately stale and that it should send another
request to the Server for identical requests, but this time the client will append a 
[If-Modified-Since](https://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.25) HTTP Request Header
which ServiceStack now automatically looks up to determine if the cache the client has is valid. 
If no newer cache for this request has been created since, ServiceStack returns a **304 NotModified** 
Response with an empty Request Body which tells the client it's safe to use their local cache instead.

#### Modify Cache-Control for OptimizedResults

You can change the `Cache-Control` Header returned for existing `ToOptimizedResult` responses by modifying
the pre-registered `HttpCacheFeature`, e.g:

```csharp
var cacheFeature = this.GetPlugin<HttpCacheFeature>();
cacheFeature.CacheControlForOptimizedResults = "max-age=3600, must-revalidate";
```

This tells the client that they can treat their locally cached server responses as **valid for 1hr**  
but **after 1hr** they must check back with the Server to determine if their cache is still valid.

### HTTP Client Caching

The Caching features above revolve around enhancing existing **Server Cached** responses with **HTTP Caching** 
features to further reduce latency and save CPU and bandwidth resources. In addition to **Server Caching** 
pure stand-alone **HTTP Caching** features (i.e. that don't cache server responses) are now available as 
first-class properties on `HttpResult`:

```csharp
// Only one Cache Validator below needs to be specified:
string ETag            // opaque string representing integrity of response
DateTime? LastModified // the last time the response was Modified

// Specify Client/Middleware Cache Behavior
TimeSpan? MaxAge          // How long cached response is considered valid
CacheControl CacheControl // More options to specify Cache-Control behavior:
enum CacheControl {
    None,
    Public,
    Private,
    MustRevalidate,
    NoCache,
    NoStore,
    NoTransform,
    ProxyRevalidate,
}

// Available, but rarely used
TimeSpan? Age      // Used by proxies to indicate how old cache is
DateTime? Expires  // Less preferred alternative to MaxAge
```

We'll walk through a couple of real-world examples to show how we can make use of these new properties
and explain the HTTP Caching behavior they enable. 

#### Using ETags

The minimum properties required for HTTP Caching is to specify either an `ETag` or `LastModified` 
Caching Validator. You can use any opaque string for the `ETag` that uniquely represents a version of the 
response that you can use to determine what version the client has, which could be an MD5 or SHA Hash of
the response but can also be a unique version string. E.g. Adding a `RowVersion` property to your OrmLite 
POCO Data Models turns on 
[OrmLite's Optimistic Concurrency](/ormlite/optimistic-concurrency)
feature where each time a record is modified it's automatically populated with a new version, these 
characteristics makes it ideal for use as an ETag which we can just return as a string:

```csharp
public object Any(GetCustomer request)
{
    var response = Db.SingleById<Customer>(request.Id);    
    return new HttpResult(response) {
        ETag = response.RowVersion.ToString(), 
    };
}
```

Whilst this is the minimum info required in your Services, the client also needs to know how long the 
cache is valid for as typically indicated by the `MaxAge` property. If it's omitted ServiceStack falls back 
to use the `HttpCacheFeature.DefaultMaxAge` of **10 minutes** which can be changed in your `AppHost` with:

```csharp
this.GetPlugin<HttpCacheFeature>().DefaultMaxAge = TimeSpan.FromHours(1);
```

So the HTTP Response Headers the client receives when calling this Service for the first time is something similar to:

```ini
ETag: "42"
Cache-Control: max-age=600
```

Which tells the client that they can use their local cache for identical requests issued within the next
10 minutes. After 10 minutes the cache is considered stale and the client will issue a new request to the 
server but this time it will include the **ETag** it has associated with the Response, i.e:

```ini
If-None-Match: "42"
```

When this happens the Service is still executed as normal and if the Customer hasn't changed, the 
`HttpCacheFeature` will compare the `HttpResult.ETag` response with the clients **ETag** above and if they 
match ServiceStack will instead return a **304 NotModified** with an Empty Response Body to indicate to the 
client that it can continue to use their locally cached response.

So whilst using a `HttpResult` **doesn't cache** the response **on the Server** and save further resources 
used in executing the Service, it still benefits from allowing the client to use their local cache for 
**10 minutes** - eliminating server requests and yielding instant response times. Then after **10 minutes** 
the **304 NotModified** Response Status and **Empty Body** improves latency and saves the Server CPU and 
bandwidth resources it didn't have to use for serializing and writing the executed Services response it 
would have need to do if no Caching was enabled.

#### Using LastModified 

The alternative to using an `ETag` is to use the `Last-Modified` Caching Validator. When you're constructing 
a complex response you'll want to use the **most recent** Last Modified Date from all sources so that you
can determine that the cache is no longer valid when any of the sources have been updated.

If you also want to customize the clients **Cache-Control** behavior you can use the additional `HttpResult` 
properties, below is an example of doing both:

```csharp
public object Any(GetCustomerOrders request)
{
    var response = new GetCustomerOrdersResponse {
        Customer = Db.SingleById<Customer>(request.Id),
        Orders = Db.Select<Order>(x => x.CustomerId == request.Id),
    };

    var allDates = new List<DateTime>(response.Orders.Select(x => x.ModifiedDate)) {
        response.Customer.ModifiedDate,
    };

    return new HttpResult(response)
    {
        LastModified = allDates.OrderByDescending(x => x).First(),
        MaxAge = TimeSpan.FromSeconds(60),
        CacheControl = CacheControl.Public | CacheControl.MustRevalidate,
    };
}
```

Which returns the Last Modified Date of the `Customer` record or any of their `Orders` as well as the 
customized **Cache-Control** Header which together returns Response Headers similar to:

```ini
Last-Modified: Fri, 19 April 2016 05:00:00 GMT
Cache-Control: max-age=60, public, must-revalidate
```

Then after **60 seconds** have elapsed the client will re-issue a request but instead of sending a 
`If-None-Match` Request Header and **ETag**, instead sends `If-Modified-Since` and the **Last-Modified** date:

```ini
If-Modified-Since: Fri, 19 April 2016 05:00:00 GMT
```

The resulting behavior is identical to that of the **ETag** above but instead compares the LastModified dates
instead of ETag strings for validity.

### Short-circuiting HTTP Cache Validation

A further optimization that can be added to the HTTP Cache workflow is using `IRequest.HasValidCache()`
to short-circuit the execution of a Service after you've processed enough information to determine either 
the `ETag` or `LastModified` for the response. 

For example if you had a Service that transcodes video on-the-fly, you can use `Request.HasValidCache()` to 
check whether the client already has the latest version of the video, if it does we can return a 
**304 NotModified** result directly, short-circuiting the Service and saving any resources in executing the 
remainder of the implementation, which in this case would **bypass reading and transcoding** the .mp4 video:

```csharp
public object Any(GetOggVideo request)
{
    var mp4Video = VirtualFileSources.GetFile($"/videos/{request.Id}.mp4");   
    if (mp4Video == null)
        throw HttpError.NotFound($"Video #{request.Id} does not exist");
    
    if (Request.HasValidCache(mp4Video.LastModified))
        return HttpResult.NotModified();
    
    var encodedOggBytes = EncodeToOggVideo(file.ReadAllBytes());
    return new HttpResult(encodedOggBytes, "video/ogg") 
    {
        LastModified = mp4Video.LastModified,
        MaxAge = TimeSpan.FromDays(1),
    };
}
```

## Http Caching of Static Files

Returning a static [Virtual File](/virtual-file-system) or `FileInfo` in a `HttpResult` also sets the **Last-Modified** HTTP Response Header whose behavior instructs the pre-configured `HttpCacheFeature` to generate the necessary HTTP Headers so HTTP Clients are able to validate subsequent requests using the [If-Modified-Since](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/If-Modified-Since) HTTP Request Header, allowing them to skip redownloading files they've already cached locally.
 
This feature is leveraged in all Single Page App templates in its `[FallbackRoute]` implementation that's used to enable full page reloads by returning the Home **index.html** page for any unknown Requests, allowing routing to be handled on the client:
 
```csharp
[FallbackRoute("/{PathInfo*}")]
public class FallbackForClientRoutes
{
    public string PathInfo { get; set; }
}
 
public class MyServices : Service
{
    //Return default.html for unmatched requests so routing is handled on client
    public object Any(FallbackForClientRoutes request) => 
        new HttpResult(VirtualFileSources.GetFile("index.html"));
}
```


# CacheResponse Attribute
Source: https://docs.servicestack.net/cacheresponse-attribute

The `[CacheResponse]` is a normal [Request Filter Attribute](/filter-attributes)
which can be added at the top-level of your Service class in which case it will cache the response of 
**All** Service implementations for **60 seconds**, e.g:

```csharp
[CacheResponse(Duration = 60)]
public class CachedServices : Service 
{ 
    public object Any(GetCustomer request) { ... }
    
    public object Any(GetCustomerOrders request) { ... }
}
```

It can also be applied individually on a single Service implementation:

```csharp
[CacheResponse(Duration = 60)]
public object Any(GetCustomer request)
{
    return Db.SingleById<Customer>(request.Id);
}
```

## Caching AutoQuery Services

Request Filter attributes can also be applied on Request DTO's, as we seen with [AutoQuery DynamoDB's QueryRockstarAlbums](/autoquery/dynamodb#caching-autoquery-services) Request DTO:

```csharp
[CacheResponse(Duration = 60)]
public class QueryRockstarAlbums : QueryData<RockstarAlbum> { ... }
```

However adding Request Filter Attributes **on Request DTO's** goes against our recommendation for keeping 
your DTO's in a separate implementation and dependency-free **ServiceModel.dll** as it would require a 
dependency on the non-PCL **ServiceStack.dll** which would prohibit being able to reuse your existing 
DTO .dll in PCL libraries, limiting their potential re-use.

You can still take advantage of the `[CacheResponse]` attribute on AutoQuery Services by defining
a custom implementation, at which point adding the `[CacheResponse]` attribute behaves as normal and 
applies caching to your Service implementations. E.g. you can enable caching for multiple AutoQuery 
Services with:

```csharp
[CacheResponse(Duration = 60)]
public class MyCachedAutoQueryServices : Service 
{
    public IAutoQueryData AutoQuery { get; set; }

    public object Any(QueryRockstars query) =>
        AutoQuery.Execute(query, AutoQuery.CreateQuery(query, Request), Request);
    
    public object Any(QueryRockstarAlbums query) =>
        AutoQuery.Execute(query, AutoQuery.CreateQuery(query, Request), Request);
}
```

### Server Cached and [HTTP Caching](/http-caching) enabled responses

When only specifying a `Duration=60` ServiceStack only **caches the Server Response** so it behaves similar
to using the existing `ToOptimizedResult()` API, e.g:

```csharp
public object Any(GetCustomer request)
{
    return Request.ToOptimizedResultUsingCache(Cache, 
        Request.RawUrl, TimeSpan.FromSeconds(60), 
        () => Db.SingleById<Customer>(request.Id));
}
```

To also enable [HTTP Caching](/http-caching) features you'll need to opt-in by specifying an additional HTTP Caching directive. 
E.g. including a `MaxAge` instructs ServiceStack to apply **HTTP Caching** logic and return the appropriate headers:

```csharp
[CacheResponse(Duration=60, MaxAge=30)]
public object Any(GetCustomer request) => Db.SingleById<Customer>(request.Id);
```

Where subsequent identical requests from a **cache-aware client** will return their locally cached version 
within the first **30 seconds**, between **30-60 seconds** the client will re-validate the request with the 
Server who will return a **304 NotModified** Response with an **Empty Body**, after **60 seconds** the cache 
expires and the next request will **re-execute the Service** and populate the cache with a new response.

#### CacheResponse Properties

The Caching behavior of the `[CacheResponse]` attribute can be further customized using any of the 
additional properties below:

```csharp        
int Duration              // Cache expiry in seconds
int MaxAge                // MaxAge in seconds
CacheControl CacheControl // Customize Cache-Control HTTP Headers
bool VaryByUser           // Vary cache per user
string[] VaryByRoles      // Vary cache for users in these roles
bool LocalCache           // Use In Memory HostContext.LocalCache or HostContext.Cache
```

Using any of the other HTTP Cache properties will also trigger the HTTP Caching features. 
When a `MaxAge` isn't specified, i.e:

```csharp
[CacheResponse(Duration = 10, VaryByUser = true)]
public object Any(GetUserActivity request) { ... }
```

ServiceStack falls back to use the `HttpCacheFeature.DefaultMaxAge` which defaults to **10 minutes**, 
in addition to the `VaryByUser` flag will construct a unique cache key for each user and return an additional 
`Vary: Cookie` HTTP Response Header.

## Advanced CacheInfo Customization

One limitation of using a .NET Attribute to specify caching behavior is that we're limited to using 
.NET constant primitives prohibiting the use of allowing custom lambda's to capture custom behavior. 
This is also the reason why we need to use `int` for `Duration` and `MaxAge` instead of a more appropriate 
`TimeSpan`.

But we can still intercept the way the `[CacheResponse]` attribute works behind-the-scenes and programmatically 
enhance it with custom logic. 
[CacheResponseAttribute](https://github.com/ServiceStack/ServiceStack/blob/master/src/ServiceStack/CacheResponseAttribute.cs)
is just a wrapper around initializing a populated 
[CacheInfo](https://github.com/ServiceStack/ServiceStack/blob/master/src/ServiceStack/CacheInfo.cs) POCO
that it drops into the `IRequest.Items` dictionary where it's visible to your Service and any remaining Filters 
in ServiceStack's [Request Pipeline](/order-of-operations). 
Essentially it's just doing this:

```csharp
req.Items[Keywords.CacheInfo] = new CacheInfo { ... };
```

The actual validation logic for processing the `CacheInfo` is encapsulated within the `HttpCacheFeature` 
Response Filter. This gives our Service a chance to modify it's behavior, e.g. in order to generically
handle all Service responses the `[CacheResponse]` attribute uses the `IRequest.RawUrl` 
(the URL minus the domain) for the base CacheKey. Whilst using a RawUrl is suitable in uniquely identifying 
most requests, if QueryString params were sent in a different case or in a different order it would generate 
a different url and multiple caches for essentially the same request. We can remedy this behavior by changing 
the base CacheKey used which is just a matter retrieving the populated the `CacheInfo` and change the 
`KeyBase` to use the predictable [Reverse Routing](/routing#reverse-routing)
`ToGetUrl()` API instead, e.g:

```csharp
[CacheResponse(Duration = 60)]
public async Task<object> Get(MyRequest request)
{
    var cacheInfo = (CacheInfo)base.Request.GetItem(Keywords.CacheInfo);
    cacheInfo.KeyBase = request.ToGetUrl(); //custom cache key
    if (await Request.HandleValidCache(cacheInfo))
        return null;
    ...

    return response;
}
```

Or generically for all cached Services by using a [Global Request Filter](/request-and-response-filters):

```csharp
this.GlobalRequestFiltersAsync.Add(async (req, res, requestDto) =>
{
    var cacheInfo = req.GetItem(Keywords.CacheInfo) as CacheInfo;
    if (cacheInfo?.KeyBase != null)
    {
        cacheInfo.KeyBase = request.ToGetUrl(); //custom cache key
        await req.HandleValidCache(cacheInfo);
    }
});
```

When using a Global Request Filter to customize caching behavior as above, your `[CacheResponse]` should have a priority `<0` in order for it to be executed before any Global Request Filters, e.g:

```csharp
[CacheResponse(Priority = -1, Duration = 10 * 60)]
public class MyCachedServices : Service { ... }
```

`HandleValidCache()` is used to re-validate the client's request with the new Cache Key and if it's determined
the Client has a valid cache, will short-circuit the Service and return a **304 NotModified** Response.


# Cache Aware Service Clients
Source: https://docs.servicestack.net/cache-aware-clients

To implement a complete end-to-end HTTP Caching story you can use the cache-aware `CachedServiceClient` to enhance all existing `HttpWebRequest` based Service Clients which manages its own local cache as instructed by the Server HTTP Caching directives, whilst the `CachedHttpClient` does the same for the HttpClient-based `JsonHttpClient`.

Both Cache-Aware clients implement the full 
[IServiceClient](https://github.com/ServiceStack/ServiceStack/blob/master/docs/pages/IServiceClient.md)
interface so they should be an easy drop-in enhancement for existing applications:

```csharp
IServiceClient client = new JsonServiceClient(baseUrl).WithCache(); 

//equivalent to:
IServiceClient client = new CachedServiceClient(new JsonServiceClient(baseUrl));
```

Likewise for `JsonHttpClient`:

```csharp
IServiceClient client = new JsonHttpClient(baseUrl).WithCache(); 

//equivalent to:
IServiceClient client = new CachedHttpClient(new JsonHttpClient(baseUrl));
```

As seen above both are decorators over existing .NET Service Clients where they'll append the appropriate HTTP Request Headers and inspect the HTTP Responses of **GET** Requests that contain HTTP Caching directives. All other HTTP Methods are just delegated through to the underlying Service Client.

The Service Clients maintain cached responses in an internal dictionary which can also be injected and shared if your app uses multiple Service Clients. For example they could use the fast binary 
[MsgPack client](/messagepack-format) 
for performance-sensitive queries or Services returning binary data and use a JSON client for everything else:

```csharp
var sharedCache = new ConcurrentDictionary<string, HttpCacheEntry>();

IServiceClient msgPackClient = new MsgPackServiceClient(baseUrl).WithCache(sharedCache);

IServiceClient jsonClient = new JsonHttpClient(baseUrl).WithCache(sharedCache);
```

## Improved Performance and Reliability

When caching is enabled on Services, the Cache-aware Service Clients can dramatically improve performance by eliminating server requests entirely as well as reducing bandwidth for re-validated requests. They also  offer an additional layer of resiliency as re-validated requests that result in Errors will transparently fallback to using pre-existing locally cached responses. For bandwidth-constrained environments like Mobile Apps they can dramatically improve the User Experience and as they're available in all supported PCL client platforms - we recommend their use where HTTP Caching is enabled on the Server.  

## Community Resources

- [Caching Anyone](http://www.mindkin.co.nz/blog/2016/1/5/caching-anyone) by [@JezzSantos](https://twitter.com/JezzSantos)


# Compression
Source: https://docs.servicestack.net/compression

## Client/Server Request Compression

In addition to [optimized cached Server Responses](/http-caching#server-caching) you can also elect to compress HTTP Requests in any C#/.NET Service Clients by specifying the Compression Type you wish to use, e.g:

```csharp
var client = new JsonServiceClient(baseUrl) {
    RequestCompressionType = CompressionTypes.GZip,
};

var client = new JsonHttpClient(baseUrl) {
    RequestCompressionType = CompressionTypes.Deflate,
};

var response = client.Post(new Request { ... });
```

Where sending any HTTP Request containing a Request Body (e.g. POST/PUT) will send a compressed Request body
to the Server where it's now able to be transparently decompressed and deserialized into your Request DTO.

## `[CompressResponse]` Attribute

You can now selectively choose which Services should be compressed with the new `[CompressResponse]` attribute to 
compress responses for clients which support compression, which can be applied to most Response Types, e.g:

```csharp
[CompressResponse]
public class CompressedServices : Service
{
    public object Any(CompressDto request) => new CompressExamplesResponse(); 
    public object Any(CompressString request) => "foo"; 
    public object Any(CompressBytes request) => "foo".ToUtf8Bytes(); 
    public object Any(CompressStream request) => new MemoryStream("foo".ToUtf8Bytes()); 
    public object Any(CompressFile request) => new HttpResult(VirtualFileSources.GetFile("/foo"));

    public object Any(CompressAnyHttpResult request)
    {
        return new HttpResult(new CompressExamplesResponse());    // DTO
        return new HttpResult("foo", "text/plain");               // string
        return new HttpResult("foo".ToUtf8Bytes(), "text/plain"); // bytes
        //etc
    }
}
```

::: info
using `[CompressResponse]` is unnecessary when returning [cached responses](/http-caching) as ServiceStack 
automatically caches and returns the most optimal Response - typically compressed bytes for clients that 
supports compression
:::

## Static File Compression

ServiceStack can also be configured to compress static files with specific file extensions that are larger than 
specific size with the new opt-in Config options below:

```csharp
SetConfig(new HostConfig {
    CompressFilesWithExtensions = { "js", "css" },
    // (optional), only compress .js or .css files > 10k
    CompressFilesLargerThanBytes = 10 * 1024 
});
```

When more fine-grained logic is needed you can override `ShouldCompressFile()` in your AppHost to choose which
static files you want to compress on a per-file basis, e.g:

```csharp
public override bool ShouldCompressFile(IVirtualFile file)
{
    return base.ShouldCompressFile(file) || file.Name == "large.csv";
}
```

#### When to enable Static File Compression

It's more optimal to configure static file compression on the native Web Server that's hosting your ServiceStack 
App than in managed code. You can use [Fiddler](http://www.telerik.com/fiddler) to check if your Web Server (e.g. IIS) 
is already compressing static files in which case you won't want to configure ServiceStack to do it.

No compression is added when running ServiceStack in a self-host, which will benefit from enabling Static File Compression.


## Brotli Compression

**.NET 6** Apps have access to is .NET Core's `BrotliStream` which is fully supported throughout ServiceStack, e.g. in Cached & Compressed Responses as well as sending compressed Request payloads in Service Clients.

The Brotli implementation is encapsulated within ServiceStack's compression abstractions whose implementations are contained within:

 - **BrotliCompressor** - Brotli (br)
 - **DeflateCompressor** - Deflate (deflate)
 - **GZipCompressor** - GZIP (gzip)

Which all implement the same substitutable interface:

```csharp
public interface IStreamCompressor
{
    string Encoding { get; }
    
    byte[] Compress(string text, Encoding? encoding = null);
    byte[] Compress(byte[] bytes);
    Stream Compress(Stream outputStream, bool leaveOpen=false);

    string Decompress(byte[] zipBuffer, Encoding? encoding = null);
        
    Stream Decompress(Stream zipBuffer, bool leaveOpen=false);

    byte[] DecompressBytes(byte[] zipBuffer);
}
```

That are managed with `StreamCompressors` in the **ServiceStack.Client** package:

```csharp
public static class StreamCompressors
{
    // Is there a compressor registered with this encoding?   
    public static bool SupportsEncoding(string? encoding);

    // return the registered IStreamCompressor implementation for for this
    public static IStreamCompressor? Get(string? encoding);
    
    // Assert there exists a IStreamCompressor for this encoding
    public static IStreamCompressor GetRequired(string encoding);

    // Register a new compressor for a specific encoding (defaults: gzip, deflate, br*) .NET6+
    public static void Set(string encoding, IStreamCompressor compressor);

    // Remove compression support for this encoding
    public static bool Remove(string encoding);
}
```

Containing pre-registered implementations of all popular Brotli, Deflate & gzip HTTP Compression algorithms so there's typically no need to add any yourself.

The preferred compression implementation for a request can be retrieved with `IRequest.GetCompressor()` which determines the implementation to use based on the overridable `GetCompressionType(IRequest request)` method in your AppHost.

### Brotli disabled for Firefox

Brotli is currently not returned for Firefox browsers (by **UserAgent** detection in `AppHost.GetCompressionType()`) which for a yet to be determined reason is the only modern browser that doesn't support .NET's `BrotliStream` output. We'll continue to investigate and remove the restriction when resolved.


# Plugins
Source: https://docs.servicestack.net/plugins

ServiceStack Plugin API provides a declarative way to enable modular functionality in ServiceStack:

## Plugin API

```csharp
public interface IPlugin
{
    void Register(IAppHost appHost);
}
```

#### Custom Logic before Plugins are loaded

If your plugin also implements `IPreInitPlugin` it will get run before any plugins are registered:

```csharp
public interface IPreInitPlugin
{
    void BeforePluginsLoaded(IAppHost appHost);
}
```

#### Custom Logic after Plugins are loaded

If your plugin implements `IPostInitPlugin` it will get run after all plugins are registered:

```csharp
public interface IPostInitPlugin
{
    void AfterPluginsLoaded(IAppHost appHost);
}
```

#### Custom Logic after AppHost is initialized

If your plugin implements `IAfterInitAppHost` it will get run after the AppHost has finished initializing:

```csharp
public interface IAfterInitAppHost
{
    void AfterInit(IAppHost appHost);
}
```

#### Disabling Plugins via Feature Enum Flags

All built-in Plugins are Registered and available via **base.Plugins** before your **Configure()** script is run so you have a chance to modify the behaviour or remove un-used plugins which is exactly what the short-hand:

```csharp
SetConfig(new HostConfig { 
    EnableFeatures = Feature.All.Remove(Feature.Csv)
});
```

Which under the covers just does:


```csharp
if ((Feature.Csv & config.EnableFeatures) != Feature.Csv)
    Plugins.RemoveAll(x => x is CsvFormat);
```

Which you now also have an opportunity to also do in your AppHost Configure() start-up script yourself - if you want to remove or customize any pre-loaded plugins.

### Configuring Plugins

The `ConfigurePlugin` API lets us avoid time-coupling between plugin registrations by letting us configure plugins before they've been added by registering a lazy callback invoked just before a plugin is registered. 

As it's resilient against ordering, it's the recommended way to **configure any plugin** it doesn't register, here's some usage examples:

```csharp
// App's can use to change logo API Explorer uses
appHost.ConfigurePlugin<UiFeature>(feature => {
    feature.Info.BrandIcon.Uri = "https://example.org/logo.svg";
});

// OpenApiFeature uses to add the /swagger-ui link to /metadata page
appHost.ConfigurePlugin<MetadataFeature>(
    feature => feature.AddPluginLink(swaggerUrl, "Swagger UI"));

// GrpcFeature uses to add a link to gRPC .proto APIs on /metadata page
appHost.ConfigurePlugin<MetadataFeature>(
    feature => feature.AddPluginLink("types/proto", "gRPC .proto APIs"));
```

`ConfigurePlugin` is invoked just before a plugin is registered, there's also `PostConfigurePlugin` to configure a plugin just after it's registered and `AfterPluginLoaded` invoked after any of its `IPostInitPlugin` callbacks have completed.

### Resolving Plugins

You can easily use LINQ to fetch any specific plugin:

```csharp
var htmlFormat = base.Plugins.First(x => x is HtmlFormat) as HtmlFormat;
```

Which is also what the `this.GetPlugin<T>()` convenience extension method does:

```csharp
var htmlFormat = base.GetPlugin<HtmlFormat>();
```

To resolve a required plugin it's recommended to use `AssertPlugin` instead which will throw if a required plugin was not registered:

```csharp
var htmlFormat = base.AssertPlugin<HtmlFormat>();
```

# List of Plugins added by Default

A list of all of the plugins available on ServiceStack and how to add them:

## Auto-registered plugins
These plugins below **are already added by default**, you can remove or customize them using the methods described above.

### Metadata Feature
Provides ServiceStack's [auto-generated metadata pages](/metadata-page).  

```csharp
var feature = Plugins.FirstOrDefault(x => x is MetadataFeature); 
Plugins.RemoveAll(x => x is MetadataFeature); 
```

### Predefined Routes
Provides ServiceStack's [pre-defined routes](/routing#pre-defined-routes) used in the built-in [C# Service Clients](/csharp-client).  

```csharp
var feature = Plugins.FirstOrDefault(x => x is PredefinedRoutesFeature); 
Plugins.RemoveAll(x => x is PredefinedRoutesFeature); 
```

### Native Types
Enables ServiceStack's [Add ServiceStack Reference](/add-servicestack-reference) support allowing API Consumers to download API DTOs generated in their preferred programming language.

```csharp
var feature = Plugins.FirstOrDefault(x => x is NativeTypesFeature); 
Plugins.RemoveAll(x => x is NativeTypesFeature); 
```

### Request Info
Provides ServiceStack's Request Info feature useful for debugging requests. Just add **?debug=requestinfo** in your `/pathinfo` and ServiceStack will return a dump of all the HTTP Request parameters to help with with debugging interoperability issues. The RequestInfoFeature is only enabled for **Debug** builds.

```csharp
var feature = Plugins.FirstOrDefault(x => x is RequestInfoFeature); 
Plugins.RemoveAll(x => x is RequestInfoFeature); 
```

### SVG

Enabling ServiceStack's [SVG Support](/svg). 

```csharp
var feature = Plugins.FirstOrDefault(x => x is SvgFeature); 
Plugins.RemoveAll(x => x is SvgFeature); 
```

### CSV Format

Registers the CSV Serializers to enable ServiceStack's [CSV Format](/csv-format).

```csharp
var feature = Plugins.FirstOrDefault(x => x is CsvFormat); 
Plugins.RemoveAll(x => x is CsvFormat); 
```

::: info
By default the CSV Format tries serialize the Response object directly into CSV which is only ideal if your responses return `List<Poco>`. If however you mark your Response DTO with the **[Csv(CsvBehavior.FirstEnumerable)]** attribute the CSV Format instead will only serialize the first `IEnumerable<T>` it finds on your Response DTO e.g. if you had a `List<Poco> Results` property it will only serialize this list in the tabular CSV Format which is typically the behaviour you want.
:::

### JSON Lines Format

Registers the `JsonlSerializer` to enable ServiceStack's [JSON Lines Format](/jsonl-format).

```csharp
var feature = Plugins.FirstOrDefault(x => x is JsonlFormat); 
Plugins.RemoveAll(x => x is JsonlFormat); 
```

::: info
The JSON Lines format follows CSV Format's behavior for serializing `IEnumerable` POCOs.
:::

### Html Format

Providing ServiceStack's [Html Format](/html5reportformat). 

```csharp
var feature = Plugins.FirstOrDefault(x => x is HtmlFormat); 
Plugins.RemoveAll(x => x is HtmlFormat); 
```

### Validation

Enables the validation feature to enable ServiceStack's [Fluent Validation](/validation) and [Declarative validators](/declarative-validation) support. 

```csharp
var feature = Plugins.FirstOrDefault(x => x is ValidationFeature); 
Plugins.RemoveAll(x => x is ValidationFeature); 
```

### HTTP Caching

Enables [HTTP Caching](/http-caching) support

```csharp
var feature = Plugins.FirstOrDefault(x => x is HttpCacheFeature); 
Plugins.RemoveAll(x => x is HttpCacheFeature); 
```

## Available Plugins

The rest of ServiceStack's plugins are not enabled by default by can easily be added on adhoc basis, as and when needed.

### [Auto Query](/autoquery/)

AutoQuery enables instant querying support on RDBMS tables behind clean self-describing APIs by enhancing the ideal API the developer would naturally write and completing their implementation for them! This is essentially the philosophy behind AutoQuery which utilizes conventions to automate creation of intent-based self-descriptive APIs that are able to specify configurable conventions and leverage extensibility options to maximize the utility of AutoQuery services.

```csharp
Plugins.Add(new AutoQueryFeature { MaxLimit = 100 });
```

::: info
Requires ServiceStack.Server
:::

## [Server Events](https://github.com/ServiceStackApps/Chat#server-sent-events)

Server Events enables server push notifications to create real-time responsive web apps with its support for [Server Sent Events](http://www.html5rocks.com/en/tutorials/eventsource/basics/). It offers a number of different API's for sending notifications to select users at different levels of granularity, letting you interact and modify live-running web apps. 

```csharp
Plugins.Add(new ServerEventsFeature());
```

## [Postman](/postman)

The [Postman Rest Client](http://www.getpostman.com/) is a very popular and easy to use HTTP Request composer that makes it easy to call web services, similar to [Fiddler's Composer](https://www.blackbaud.com/files/support/guides/infinitydevguide/Subsystems/inwebapi-developer-help/Content/InfinityWebAPI/coUsingFiddlerCreateHTTPRequest.htm). It also provides as an alternative for auto-generating API documentation to [ServiceStack's Open API support](/openapi) that makes it easier to call existing services but does require users to install the [Postman Rest Client](http://www.getpostman.com/).

```csharp
Plugins.Add(new PostmanFeature());
Plugins.Add(new CorsFeature());
```

### [Open API support](/openapi)

Swagger support an optional add-on available in the [ServiceStack.Api.OpenApi](https://nuget.org/packages/ServiceStack.Api.OpenApi/) NuGet package.

After installing the NuGet package enable the Swagger with:

```csharp
Plugins.Add(new OpenApiFeature());
```

Now you can enjoy your shiny new Swagger UI at: `http://yoursite/swagger-ui/index.html`

#### Annotating your services

You can further document your services in the Swagger UI with the new `[Api]` and `[ApiMember]` annotation attributes, e,g: Here's an example of a fully documented service:

```csharp
[Api("Service Description")]
[Route("/swagger/{Name}", "GET", Summary = @"GET Summary", Notes = "GET Notes")]
[Route("/swagger/{Name}", "POST", Summary = @"POST Summary", Notes = "POST Notes")]
public class MyRequestDto
{
    [ApiMember(Name="Name", Description = "Name Description", 
               ParameterType = "path", DataType = "string", IsRequired = true)]
    public string Name { get; set; }
}
```

### [Razor Format](https://razor.netcore.io/)
Provides ServiceStack's primary HTML story with support for the MVC Razor view engine.

```csharp
Plugins.Add(new RazorFormat()); 
```

It's an optional .NET 4.0 plugin that is available in the [ServiceStack.Razor](https://nuget.org/packages/ServiceStack.Razor) NuGet package.


### [Authentication](/auth/authentication-and-authorization)
The Authentication Feature enables the [Authentication and Authorization](/auth/authentication-and-authorization) support in ServiceStack. It makes available the AuthService at the default route at `/auth/{provider}`, registers **AssignRoles** and **UnAssignRoles** services (at `/assignroles` and `/unassignroles` default routes) and auto-enables Session support if it's not added already.

An example AuthFeature registration (taken from the [SocialBootstrapApi](https://github.com/ServiceStackApps/SocialBootstrapApi/blob/master/src/SocialBootstrapApi/AppHost.cs#L154) project):

```csharp
Plugins.Add(new AuthFeature(
    () => new CustomUserSession(), //Use your own typed Custom UserSession type
    new IAuthProvider[] {
        new CredentialsAuthProvider(),         //HTML Form post of UserName/Password
        new TwitterAuthProvider(appSettings),  //Sign-in with Twitter
        new FacebookAuthProvider(appSettings), //Sign-in with Facebook
        new BasicAuthProvider(),               //Sign-in with Basic Auth
    }));
```

This registers and provides your ServiceStack host a myriad of different Authentication options as described above.

### [Session support](/auth/sessions)

If you're **not** using the AuthFeature above and you still want Session support you need to enable it explicitly with:

```csharp
Plugins.Add(new SessionFeature());
```

This will add a [Request Filter](/request-and-response-filters) to instruct any HTTP client calling a ServiceStack web service to create a Temporary (ss-id) and Permanent (ss-pid) cookie if not already done so.

### Registration

Related to Authentication is Registration which enables the Registration Service at the default route `/register` which lets new Users to be registered and validated with the Credentials and Basic AuthProviders.

```csharp
Plugins.Add(new RegistrationFeature());
```

See the [SocialBootstrapApi](https://github.com/ServiceStack/SocialBootstrapApi) project for a working example of Registration and Authentication.

### [MessagePack format](/messagepack-format)
To add fast binary [MessagePack support](/messagepack-format) to ServiceStack install the **[ServiceStack.MsgPack](https://nuget.org/packages/ServiceStack.MsgPack)** NuGet package and register the plugin with:

```csharp
Plugins.Add(new MsgPackFormat());
```

### [ProtoBuf format](/protobuf-format)
To enable [ProtoBuf support](/protobuf-format) install the **[ServiceStack.ProtoBuf](https://nuget.org/packages/ServiceStack.ProtoBuf)** NuGet package and register the plugin with:

```csharp
Plugins.Add(new ProtoBufFormat());
```

### [Proxy Feature](/proxy-feature)

The `ProxyFeature` plugin is an application-level proxy that can be used to transparently proxy HTTP Requests through to
downstream servers whose behavior can be customized with custom C# hooks to control how requests are proxied.

```csharp
Plugins.Add(new ProxyFeature(
    matchingRequests: req => req.PathInfo.StartsWith("/sales"),
    resolveUrl:req => "http://sales.domain.com" + req.RawUrl.Replace("/sales", "/")))
```

### [Request Logger](/request-logger)

Add an In-Memory `IRequestLogger` and service with the default route at `/requestlogs` which maintains a live log of the most recent requests (and their responses). Supports multiple config options incl. Rolling-size capacity, error and session tracking, hidden request bodies for sensitive services, etc.

```csharp
Plugins.Add(new RequestLogsFeature());
```

The `IRequestLogger` is a great way to introspect and analyze your service requests in real-time, e.g:

![Live Screenshot](/img/pages/plugins/request-logs-01.png)

It supports multiple queryString filters and switches so you filter out related requests for better analysis and debuggability:

![Request Logs Usage](/img/pages/plugins/request-logs-02.png)

The [RequestLogsService](https://github.com/ServiceStack/ServiceStack/blob/master/src/ServiceStack/Admin/RequestLogsService.cs) is just a simple C# service under-the-hood but is a good example of how a little bit of code can provide a lot of value in ServiceStack's by leveraging its generic, built-in features.

## [Encrypted Messaging](/auth/encrypted-messaging)

The Encrypted Messaging feature enables a secure channel for all Services to offer protection to clients who can now easily send and receive encrypted messages over unsecured HTTP by registering the EncryptedMessagesFeature plugin:

```csharp
Plugins.Add(new EncryptedMessagesFeature {
    PrivateKeyXml = ServerRsaPrivateKeyXml
});
```

Where `PrivateKeyXml` is the Servers RSA Private Key Serialized as XML. See the [Encrypted Messaging docs](/auth/encrypted-messaging) for more info.


### [Razor Markdown Format](/markdown-razor)

This provides ServiceStack's [Razor Markdown Format](/markdown-razor) and also enables ServiceStack to serve static **.md** or **.markdown** files in either plain text, rendered as HTML (partial), or rendered in HTML inside a static **_Layout.shtml** HTML template. 

```csharp
Plugins.Add(new MarkdownFormat()); 
```
  - [Introduction to Markdown Razor](/markdown-razor)
  - [Markdown Razor Features](/markdown-razor)


## [Cancellable Requests](/cancellable-requests)

The Cancellable Requests Feature makes it easy to design long-running Services that are cancellable with an external Web Service Request. To enable this feature, register the CancellableRequestsFeature plugin:

```csharp
Plugins.Add(new CancellableRequestsFeature());
```

### Web Sudo

A common UX in some websites is to add an extra layer of protection for **super protected** functionality by getting users to re-confirm their password verifying it's still them using the website, common in places like confirming a financial transaction. 

**WebSudo** is a new feature similar in spirit requiring users to re-authenticate when accessing Services annotated with the `[WebSudoRequired]` attribute. To make use of WebSudo, first register the plugin:

```csharp
Plugins.Add(new WebSudoFeature());
```

Your Custom AuthUserSession would need to either inherit `WebSudoAuthUserSession` or implement `IWebSudoAuthSession`, e.g:

```csharp
public class CustomUserSession : WebSudoAuthUserSession {}
```

Then tell ServiceStack to use your CustomUserSession by registering it with the `AuthFeature`, e.g:

```csharp
Plugins.Add(new AuthFeature(() => new CustomUserSession(), ...);
```

You can then apply WebSudo behavior to existing services by annotating them with `[WebSudoRequired]`:

```csharp
[WebSudoRequired]
public class RequiresWebSudoService : Service
{
    public object Any(RequiresWebSudo request)
    {
        return request;
    }
}
```

Once enabled this will throw a **402 Web Sudo Required** HTTP Error the first time the service is called:

```csharp
var requiresWebSudo = new RequiresWebSudo { Name = "test" };
try
{
    client.Send<RequiresWebSudoResponse>(requiresWebSudo); //throws
}
catch (WebServiceException)
{
    client.Send(authRequest); //re-authenticate
    var response = client.Send(requiresWebSudo); //success!
}
```

Re-authenticating afterwards will allow access to the WebSudo service.

## Community Plugins

### [ServiceStack.Webhooks](https://github.com/jezzsantos/ServiceStack.Webhooks)

If you need to implement a Webhooks solution for your Services check out [ServiceStack.Webhooks](https://github.com/jezzsantos/ServiceStack.Webhooks). ServiceStack.Webhooks is a [well documented](https://github.com/jezzsantos/ServiceStack.Webhooks/wiki) solution for raising and managing application-level "events" raised by your services:

![](https://raw.githubusercontent.com/jezzsantos/ServiceStack.Webhooks/master/docs/img/pages/Webhooks.Architecture.PNG)

The ServiceStack.Webhooks plugin is versatile and supports persisting event subscriptions in [multiple back-end data stores](https://github.com/jezzsantos/ServiceStack.Webhooks/wiki/Plugins) including: Memory, Cache Clients, Azure Table Storage as well as every major [RDBMS that supported by OrmLite](/ormlite/installation).

#### Getting Started

Install [ServiceStack.Webhooks](https://www.nuget.org/packages/ServiceStack.Webhooks) from NuGet:

:::copy
`<PackageReference Include="ServiceStack.Webhooks" Version="8.*" />`
:::

Register the `WebhookFeature` plugin in your AppHost:

```csharp
public override void Configure(Container container)
{
    // Add ValidationFeature and AuthFeature plugins first
    Plugins.Add(new WebhookFeature());
}
```

Then [configure the plugin](https://github.com/jezzsantos/ServiceStack.Webhooks/wiki/Getting-Started) to suit your needs.

# Community Resources

  - [Extending ServiceStack](http://morganskinner.blogspot.com/2013/04/extending-servicestack.html) by [morganskinner](http://morganskinner.blogspot.com/)


# Open API v3
Source: https://docs.servicestack.net/openapi

![](/img/pages/openapi/v3/openapiv3-logo.png)

::: info
For documentation on using `OpenApiFeature` refer to [Open API v2](/openapi-v2) instead
:::

Utilizing the same ASP.NET Core [Endpoint Routing](/endpoint-routing) that the rest of the ASP.NET Core App uses enables 
your ServiceStack APIs to integrate with your wider ASP.NET Core application, opening up more opportunities for greater reuse.

This opens up the ability to use common third party tooling to implement application-wide features like OpenAPI v3 specification 
generation support for your endpoints offered by the `Swashbuckle.AspNetCore` package.

<lite-youtube class="w-full mx-4 my-4" width="560" height="315" videoid="zAq9hp7ojn4" style="background-image: url('https://img.youtube.com/vi/zAq9hp7ojn4/maxresdefault.jpg')"></lite-youtube>

To make this integration as easy as possible we're maintaining the `ServiceStack.AspNetCore.OpenApi` package to incorporate additional 
information from your ServiceStack APIs into Swagger metadata.

![](/img/pages/openapi/v3/openapi-v3-swagger-ui.png)

In this guide we will look at how you can take advantage of the new OpenAPI v3 Swagger support using mapped Endpoints, 
customizing the generated specification, as well as touch on other related changes when using [Endpoint Routing](/endpoint-routing).

## AppHost Initialization

To use Swashbuckle your ServiceStack App needs to be configured to use [Endpoint Routing](/endpoint-routing) and
[ASP.NET Core IOC](/net-ioc) where registration of your ServiceStack Services and App's Dependencies & Plugins need to be setup
before your `WebApplication` is built, e.g:

#### Program.cs
```csharp
// Register ServiceStack APIs, Dependencies and Plugins:
services.AddServiceStack(typeof(MyServices).Assembly);

var app = builder.Build();
//...

// Register ServiceStack AppHost
app.UseServiceStack(new AppHost(), options => {
    options.MapEndpoints();
});

app.Run();
```

Once configured to use Endpoint Routing we can then use the [mix](https://docs.servicestack.net/mix-tool) tool to apply the 
[openapi3](https://gist.github.com/gistlyn/dac47b68e77796902cde0f0b7b9c6ac2) Startup Configuration with:

:::sh
x mix openapi3
:::

### Manually Configure OpenAPI v3 and Swagger UI 

This will install the required ASP.NET Core Microsoft, Swashbuckle and ServiceStack Open API NuGet packages:

```xml
<PackageReference Include="Microsoft.AspNetCore.OpenApi" Version="8.*" />
<PackageReference Include="Swashbuckle.AspNetCore" Version="7.*" />
<PackageReference Include="ServiceStack.AspNetCore.OpenApi" Version="8.*" />
```

Then add the `Configure.OpenApi.cs` [Modular Startup](https://docs.servicestack.net/modular-startup) class to your project:

```csharp
[assembly: HostingStartup(typeof(MyApp.ConfigureOpenApi))]

namespace MyApp;

public class ConfigureOpenApi : IHostingStartup
{
    public void Configure(IWebHostBuilder builder) => builder
        .ConfigureServices((context, services) =>
        {
            if (context.HostingEnvironment.IsDevelopment())
            {
                services.AddEndpointsApiExplorer();
                services.AddSwaggerGen(); // Swashbuckle

                services.AddServiceStackSwagger();
                services.AddBasicAuth<ApplicationUser>(); // Enable HTTP Basic Auth
                //services.AddJwtAuth(); // Enable & Use JWT Auth

                services.AddTransient<IStartupFilter, StartupFilter>();
            }
        });

    public class StartupFilter : IStartupFilter
    {
        public Action<IApplicationBuilder> Configure(Action<IApplicationBuilder> next)
            => app => {
                // Provided by Swashbuckle library
                app.UseSwagger();
                app.UseSwaggerUI();
                next(app);
            };
    }
}
```

All this setup is done for you in our updated [Identity Auth .NET 8 Templates](https://servicestack.net/start).

## Open API Attributes

Each route could have a separate summary and description. You can set it with `Route` attribute:

```csharp
[Route("/hello", Summary = @"Default hello service.", 
    Notes = "Longer description for hello service.")]
```

You can set specific description for each HTTP method like shown below:

```csharp
[Route("/hello/{Name}", "GET", Summary="Says 'Hello' to provided Name", 
    Notes = "Longer description of the GET method which says 'Hello'")]
[Route("/hello/{Name}", "POST", Summary="Says 'Hello' to provided Name", 
    Notes = "Longer description of the POST method which says 'Hello'")]
```

You can also document your services in the OpenAPI with the new `[Api]` and `[ApiMember]` annotation attributes, e,g: Here's an example of a fully documented service:

```csharp
[Api("Service Description")]
[Tag("Core Requests")]
[ApiResponse(HttpStatusCode.BadRequest, "Your request was not understood")]
[ApiResponse(HttpStatusCode.InternalServerError, "Oops, something broke")]
[Route("/swagger/{Name}", "GET", Summary = "GET Summary", Notes = "Notes")]
[Route("/swagger/{Name}", "POST", Summary = "POST Summary", Notes="Notes")]
public class MyRequestDto
{
    [ApiMember(Name="Name", Description = "Name Description",
        ParameterType = "path", DataType = "string", IsRequired = true)]
    [ApiAllowableValues("Name", typeof(Color))] //Enum
    public string Name { get; set; }
}
```

Please note, that if you used `ApiMember.DataType` for annotating `OpenApiFeature` then you need to change the types to OpenAPI type when migrating to `OpenApiFeature`. For example, annotation of 
```csharp
[ApiMember(DataType="int")]
```
need to be changed to 
```csharp
[ApiMember(DataType="integer", Format="int32")]
```

Here is the table for type migration

:::{.table}
| Swagger Type (DataType) | OpenAPI Type (DataType) | OpenAPI Format (Format)     |
|-------------------------|-------------------------|-----------------------------|
| Array                   | array                   |                             |
| boolean                 | boolean                 |                             |
| byte                    | integer                 | int                         |
| Date                    | string                  | date                        |
|                         | string                  | date-time                   |
| double                  | number                  | double                      |
| float                   | number                  | float                       |
| int                     | integer                 | int32                       |
| long                    | integer                 | int64                       |
| string                  | string                  |                             |
:::

You can use `[ApiAllowableValues]` lets you anotate enum properties as well as a restriction for values in array, e.g:

```csharp
[ApiAllowableValues("Includes", Values = new string[] { "Genres", "Releases", "Contributors" })]
public string[] Includes { get; set; }
```

::: info
The use of `ApiMember` turns your DTO properties as **opt-in only** for OpenApi metadata.
Meaning that only properties annotated with `[ApiMember]` will be included in the OpenApi metadata for classes
that use `[ApiMember]` on any of its properties.
:::

### Group APIs with Tags

You can tag the DTO with `[Tag]` attribute. Attributes are annotated by the same tag are grouped by the tag name in Swagger UI. DTOs can have multiple tags, e.g:

```csharp
[Tag("Core Features")]
[Tag("Scheduler")]
public class MyRequest { ... }
```

You can Exclude **properties** from being listed in OpenAPI with:

```csharp
[IgnoreDataMember]
```

Exclude **properties** from being listed in OpenAPI Schema Body with:

```csharp
[ApiMember(ExcludeInSchema=true)]
```
### Exclude Services from Metadata Pages

To exclude entire Services from showing up in OpenAPI or any other Metadata Services (i.e. Metadata Pages, Postman, NativeTypes, etc), annotate **Request DTO's** with:

```csharp
[ExcludeMetadata]
public class MyRequestDto { ... }
```

## More Control

One point of friction with our previous `OpenApiFeature` plugin was the missing customization ability to the OpenAPI spec to somewhat disconnect from the defined ServiceStack service, and related C# Request and Response DTOs since it used Request DTOs property attributes making the *structure* of the OpenAPI schema mapping quite ridged, preventing the ability for certain customizations.

For example, if we have an `UpdateTodo` Request DTO that looks like the following class:

```csharp
[Route("/todos/{Id}", "PUT")]
public class UpdateTodo : IPut, IReturn<Todo>
{
    public long Id { get; set; }
    [ValidateNotEmpty]
    public string Text { get; set; }
    public bool IsFinished { get; set; }
}
```

Previously, we would get a default Swagger UI that enabled all the properties as `Paramters` to populate:

![](/img/pages/openapi/v3/openapi-v2-defaults.png)

While this correctly describes the Request DTO structure, sometimes as developers we get requirements for how we want to present our APIs to our users from within the Swagger UI. 

With the updated SwaggerUI, and the use of the `Swashbuckle` library, we get the following UI by default:

![](/img/pages/openapi/v3/openapi-v3-defaults-application-json.png)

These are essentially the same, we have a CRUD Todo API that takes a `UpdateTodo` Request DTO, and returns a `Todo` Response DTO. ServiceStack needs to have uniquely named Request DTOs, so we can't have a `Todo` schema as the Request DTO despite the fact that it is the same structure as our `Todo` model. 
This is a good thing, as it allows us to have a clean API contract, and separation of concerns between our Request DTOs and our models. 
However, it might not be desired to present this to our users, since it can be convenient to think about CRUD services as taking the same resource type as the response.

To achieve this, we use the Swashbuckle library to customize the OpenAPI spec generation. Depending on what you want to customize, you can use the `SchemaFilter` or `OperationFilter` options. In this case, we want to customize the matching operation to reference the `Todo` schema for the Request Body.

First, we create a new class that implements the `IOperationFilter` interface.

```csharp
public class OperationRenameFilter : IOperationFilter
{
    public void Apply(OpenApiOperation operation, OperationFilterContext context)
    {
        if (context.ApiDescription.HttpMethod == "PUT" &&
            context.ApiDescription.RelativePath == "todos/{Id}")
        {
            operation.RequestBody.Content["application/json"].Schema.Reference = 
                new OpenApiReference {
                    Type = ReferenceType.Schema,
                    Id = "Todo"
                };
        }
    }
}
```

The above matches some information about the `UpdateTodo` request we want to customize, and then sets the `Reference` property of the `RequestBody` to the `Todo` schema.
We can then add this to the `AddSwaggerGen` options in the `Program.cs` file.

```csharp
builder.Services.AddSwaggerGen(o =>
{
    o.OperationFilter<OperationRenameFilter>();
});
```

The result is the following Swagger UI:

![](/img/pages/openapi/v3/openapi-v3-customized-application-json.png)

This is just one simple example of how you can customize the OpenAPI spec generation, and `Swashbuckle` has some great documentation on the different ways you can customize the generated spec.
And these customizations impact any of your ASP.NET Core Endpoints, not just your ServiceStack APIs.

Now that ServiceStack APIs can be mapped to standard ASP.NET Core Endpoints, it opens up a lot of possibilities for integrating your 
ServiceStack APIs into the larger ASP.NET Core ecosystem.


# Open API
Source: https://docs.servicestack.net/openapi-v2

::: info
When using ASP.NET Core **Endpoint Routing** refer to [ASP.NET Core Swashbuckle Open API v3](/openapi) instead
:::

![](/img/pages/openapi/openapi-banner.png)

[Open API](https://www.openapis.org/) is a specification and complete framework implementation for describing, producing, consuming, and visualizing RESTful web services. ServiceStack implements the 
[OpenAPI Spec](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md) back-end and embeds the Swagger UI front-end in a separate plugin which is available under [OpenAPI NuGet package](http://nuget.org/packages/ServiceStack.Api.OpenApi/):

:::copy
`<PackageReference Include="ServiceStack.Api.OpenApi" Version="8.*" />`
:::

## Installation

You can enable Open API by registering the `OpenApiFeature` plugin in AppHost with:

```csharp
public override void Configure(Container container)
{
    ...
    Plugins.Add(new OpenApiFeature());

    // Uncomment CORS feature if it needs to be accessible from external sites 
    // Plugins.Add(new CorsFeature()); 
    ...
}
```

Then you will be able to view the Swagger UI from `/swagger-ui/`. A link to **Swagger UI** will also be available from your `/metadata` [Metadata Page](/metadata-page).

## Open API Attributes

Each route could have a separate summary and description. You can set it with `Route` attribute:

```csharp
[Route("/hello", Summary = @"Default hello service.", 
    Notes = "Longer description for hello service.")]
```

You can set specific description for each HTTP method like shown below:

```csharp
[Route("/hello/{Name}", "GET", Summary="Says 'Hello' to provided Name", 
    Notes = "Longer description of the GET method which says 'Hello'")]
[Route("/hello/{Name}", "POST", Summary="Says 'Hello' to provided Name", 
    Notes = "Longer description of the POST method which says 'Hello'")]
```

You can also document your services in the OpenAPI with the new `[Api]` and `[ApiMember]` annotation attributes, e,g: Here's an example of a fully documented service:

```csharp
[Api("Service Description")]
[Tag("Core Requests")]
[ApiResponse(HttpStatusCode.BadRequest, "Your request was not understood")]
[ApiResponse(HttpStatusCode.InternalServerError, "Oops, something broke")]
[Route("/swagger/{Name}", "GET", Summary = "GET Summary", Notes = "Notes")]
[Route("/swagger/{Name}", "POST", Summary = "POST Summary", Notes="Notes")]
public class MyRequestDto
{
    [ApiMember(Name="Name", Description = "Name Description",
        ParameterType = "path", DataType = "string", IsRequired = true)]
    [ApiAllowableValues("Name", typeof(Color))] //Enum
    public string Name { get; set; }
}
```

Please note, that if you used `ApiMember.DataType` for annotating `OpenApiFeature` then you need to change the types to OpenAPI type when migrating to `OpenApiFeature`. For example, annotation of 
```csharp
[ApiMember(DataType="int")]
```
need to be changed to 
```csharp
[ApiMember(DataType="integer", Format="int32")]
```

Here is the table for type migration

| Swagger Type (DataType) | OpenAPI Type (DataType) | OpenAPI Format (Format)     |
|-------------------------|-------------------------|-----------------------------|
| Array                   | array                   |                             |
| boolean                 | boolean                 |                             |
| byte                    | integer                 | int                         |
| Date                    | string                  | date                        |
|                         | string                  | date-time                   |
| double                  | number                  | double                      |
| float                   | number                  | float                       |
| int                     | integer                 | int32                       |
| long                    | integer                 | int64                       |
| string                  | string                  |                             |

You can use `[ApiAllowableValues]` lets you anotate enum properties as well as a restriction for values in array, e.g:

```csharp
[ApiAllowableValues("Includes", Values = new string[] { "Genres", "Releases", "Contributors" })]
public string[] Includes { get; set; }
```

::: info
The use of `ApiMember` turns your DTO properties as **opt-in only** for OpenApi metadata.
Meaning that only properties annotated with `[ApiMember]` will be included in the OpenApi metadata for classes
that use `[ApiMember]` on any of its properties.
:::

### Group APIs with Tags

You can tag the DTO with `[Tag]` attribute. Attributes are annotated by the same tag are grouped by the tag name in Swagger UI. DTOs can have multiple tags, e.g:

```csharp
[Tag("Core Features")]
[Tag("Scheduler")]
public class MyRequest { ... }
```

You can Exclude **properties** from being listed in OpenAPI with:

```csharp
[IgnoreDataMember]
```

Exclude **properties** from being listed in OpenAPI Schema Body with:

```csharp
[ApiMember(ExcludeInSchema=true)]
```
### Exclude Services from Metadata Pages

To exclude entire Services from showing up in OpenAPI or any other Metadata Services (i.e. Metadata Pages, Postman, NativeTypes, etc), annotate **Request DTO's** with:

```csharp
[ExcludeMetadata]
public class MyRequestDto { ... }
```

### Operation filters

You can override operation or parameter definitions by specifying the appropriate filter in plugin configuration:

```csharp
Plugins.Add(new OpenApiFeature
{
    OperationFilter = (verb, operation) => operation.Tags.Add("all operations")
});
```

Available configuration options:

- `ApiDeclarationFilter` - allows to modify final result of returned OpenAPI json
- `OperationFilter` - allows to modify operations
- `SchemaFilter` - allows to modify OpenAPI schema for user types
- `SchemaPropertyFilter` - allows to modify propery declarations in OpenAPI schema

### Properties naming conventions

You can control naming conventions of generated properties by following configuration options:

- `UseCamelCaseSchemaPropertyNames` - generate camel case property names
- `UseLowercaseUnderscoreSchemaPropertyNames` - generate underscored lower cased property names (to enable this feature `UseCamelCaseModelPropertyNames` must also be set) 

Example:

```csharp
Plugins.Add(new OpenApiFeature
{
    UseCamelCaseSchemaPropertyNames = true,
    UseLowercaseUnderscoreSchemaPropertyNames = true
});
```

### Change default Verbs

If left unspecified, the `[Route]` attribute allows Services to be called from any HTTP Verb which by default 
are listed in the Open API specification under the most popular HTTP Verbs, namely `GET`, `POST`, `PUT` and `DELETE`.

This can be modified with `AnyRouteVerbs` which will let you specify which Verbs should be generated 
for **ANY** Routes with unspecified verbs, e.g. we can restrict it to only emit routes for `GET` and `POST` Verbs with:

```csharp
Plugins.Add(new OpenApiFeature
{
    AnyRouteVerbs =  new List<string> { HttpMethods.Get, HttpMethods.Post }
});
```

### Miscellaneous configuration options

- `DisableAutoDtoInBodyParam` - disables adding `body` parameter for Request DTO to operations
- `LogoUrl` - url of the logo image for Swagger UI

Example:

```csharp
Plugins.Add(new OpenApiFeature
{
    DisableAutoDtoInBodyParam = true
});
```

## Virtual File System

The docs on the Virtual File System shows how to override embedded resources:

### Overriding OpenAPI Embedded Resources

ServiceStack's [Virtual File System](/virtual-file-system) supports multiple file source locations where you can override OpenAPI's embedded files by including your own custom files in the same location as the existing embedded files. This lets you replace built-in ServiceStack embedded resources with your own by simply copying the [/swagger-ui](https://github.com/ServiceStack/ServiceStack/tree/master/src/ServiceStack.Api.OpenApi/swagger-ui) files you want to customize and placing them in your Website Directory at:

```
/swagger-ui
    /css
    /fonts
    /images
    /lang
    /lib
    index.html
    swagger-ui.js
```

#### Injecting custom JavaScript

As part of the customization you can add custom `patch.js` and `patch-preload.js`:

```
/swagger-ui
    patch.js
    patch-preload.js
```

which will be injected in the `/swagger-ui` index page, `patch-preload.js` is embedded before `swaggerUi.load()` is called:

```js
// contents of patch-preload.js

window.swaggerUi.load();
```

So you can use it to customize the `swaggerUi` configuration object before it's loaded, whilst `patch.js` is embedded just before the end of the `</body>` tag, e.g:

```html
<script type='text/javascript'>
// contents of patch.js
</script>
</body>
```

### Swagger UI Security

There are 2 custom security methods supported **Bearer** and **Basic Auth**. 

You can specify to use Swagger's support for API Key Authentication with:

```csharp
Plugins.Add(new OpenApiFeature
{
    UseBearerSecurity = true,
});
```

This will instruct Swagger to use their API Key Authentication when clicking the **Authorize** button which will be sent in API requests to your Authenticated Services. As the **value** field is for the entire Authorization HTTP Header you'd need to add your JWT Token or API Key prefixed with `Bearer `:

![](./img/pages/openapi/bearer-auth.png)

Which you can use to use to Authenticate with "Bearer token" Auth Providers like [API Key](/auth/api-key-authprovider) and [JWT Auth Providers](/auth/jwt-authprovider).

### Basic Auth in OpenAPI

You can instruct Swagger to use HTTP Basic Auth with:

```csharp
Plugins.Add(new OpenApiFeature
{
    UseBasicSecurity = true,
});
```

This lets Users call protected Services using the Username and Password fields in Swagger UI. 
Swagger UI sends these credentials with every API request using HTTP Basic Auth, which can be enabled in your AppHost with:

```csharp
Plugins.Add(new AuthFeature(...,
    new IAuthProvider[] { 
        new BasicAuthProvider(), //Allow Sign-ins with HTTP Basic Auth
    }));
```

To login, you need to click "Authorize" button.

![](./img/pages/openapi/1-swaggerui-authorize.png)

And then enter username and password.

![](./img/pages/openapi/2-swaggerui-password.png)

Also you can click "Try it out" button on services, which requires authentication and browser will prompt a window with user/password field for entering basic auth credentials.

Alternatively you can authenticate outside Swagger (e.g. via an OAuth Provider) which will also let you
call protected Services in `/swagger-ui`.

## Generating AutoRest client

You can use OpenAPI plugin to automatically generate client using [Autorest](https://github.com/Azure/Autorest). 
To use AutoRest first install it from npm:

:::sh
npm install -g autorest
:::

Then you need to download the Open API specification for your Services using a tool like curl:

:::sh
curl http://your.domain/openapi > openapi.json
:::

Or using `iwr` if you have PowerShell installed:

:::sh
iwr http://your.domain/openapi -o openapi.json
:::

You can then use the `openapi.json` with autorest to generate a client for your API in your preferred language, e.g:

:::sh
autorest --latest-release -Input openapi.json -CodeGenerator CSharp -OutputDirectory AutoRestClient -Namespace AutoRestClient
:::

This will generate directory containing your model types and REST operations that you can use with the 
generated client, e.g:

```csharp
using (var client = new SampleProjectAutoRestClient("http://localhost:20000"))
{
    var dto = new SampleDto { /* .... */ }; 
    var result = client.SampleOperation.Post(body: dto);

    // process result
}
```

AutoRest clients will allow usage of tooling that have adopted AutoRest and is a good stop gap solution for generating
native clients for languages that [Add ServiceStack Reference](/add-servicestack-reference) doesn't support yet like
Python and Ruby.

### AutoRest Generated Clients vs Add ServiceStack Reference

However AutoRest generated clients are similar to WCF Service Reference generated clients where it generates RPC-style Clients that emits both implementation logic and models for sending each request that's coupled to external HttpClient 
and JSON.NET dependencies. This approach generates significantly more code generation that populates a directory containing
[multiple implementation and Model classes](https://github.com/ServiceStack/ServiceStack/tree/master/tests/ServiceStack.OpenApi.Tests/GeneratedClient)
generated for each Service.

In contrast [Add ServiceStack Reference](/add-servicestack-reference) adopts the 
venerable [Data Transfer Object](https://martinfowler.com/eaaCatalog/dataTransferObject.html), 
[Gateway](https://martinfowler.com/eaaCatalog/gateway.html) and 
[Remote Facade](https://martinfowler.com/eaaCatalog/remoteFacade.html) Service patterns where it only needs to generate
clean, implementation-free DTO models that it captures in **a single source file** for all supported languages. 

The generated DTOs are cleaner and more reusable where it isn't coupled to any Serialization implementation and
can be reused in any of ServiceStack's message-based 
[Service Clients and Serialization Formats](/csharp-client#httpwebrequest-service-clients)
or different [Service Gateway](/service-gateway) implementations.
The models are also richer where it's able to include additional metadata attributes and marker interfaces 
that isn't possible when tunneling through a generic API specification. 

The use of intelligent generic Service Clients will always be able to provide a richer more productive development 
experience that can enable higher-level, value-added functionality like 
[Structured Error Handling](/error-handling), [Smart HTTP Caching](/cache-aware-clients), 
[Auto Batching](/auto-batched-requests), [Encrypted Messaging](/auth/encrypted-messaging#encrypted-service-client), 
[AutoQuery Streaming](/autoquery/rdbms#service-clients-support), 
[Request Compression](/csharp-client#client--server-request-compression), integrated authentication and lots more.

### Known issues

Autorest generated clients do not support `application/octet-stream` MIME type, which is used when service returns `byte[]` array. You can track [this issue on Github](https://github.com/Azure/autorest/issues/1932).

## Publish Azure Management API

Login to [Azure Portal](https://portal.azure.com) and search for `API management service`.

![](./img/pages/azure-api-management/1-search.png)

Choose `API management service`. In opened window click `Add` button.

![](./img/pages/azure-api-management/2-add.png)

Fill the creation form. Put your own values in `Name`, `Resource Group`, `Organization name` and `Administrator email`. When creation form will be ready, click `Create` button.

![](./img/pages/azure-api-management/3-create.png)

Wait while Management API will be activated. It can take more than forty minutes. When it ready click on created API management resource.

![](./img/pages/azure-api-management/4-activating.png)

In opened window click `APIs - PREVIEW` menu item on the left pane.

![](./img/pages/azure-api-management/5-publisher-portal.png)

Choose `OpenAPI specification` in `Add API` section.

![](./img/pages/azure-api-management/6-add-api.png)

Fill the url with location of you services, ended with `/openapi` or just click `Upload` button and upload OpenAPI json definition, which is available at `/openapi` path of your services.

![](./img/pages/azure-api-management/7-create-api.png)

After successfull import you should see list of available operations for your services

![](./img/pages/azure-api-management/8-created.png)


# CORS Feature
Source: https://docs.servicestack.net/corsfeature

### Enable CORS in ASP .NET Core Apps

Optionally .NET Apps can utilize the built-in [ASP.NET CORS Support](https://learn.microsoft.com/en-us/aspnet/core/security/cors) with the mix in:

:::sh
x mix cors
:::

This will add the `Configure.Cors.cs` [Modular Startup](/modular-startup) to your Host project which
can be further customized to support your use-case:

```csharp
[assembly: HostingStartup(typeof(MyApp.ConfigureCors))]

namespace MyApp;

public class ConfigureCors : IHostingStartup
{
    public void Configure(IWebHostBuilder builder) => builder
        .ConfigureServices(services =>
        {
            services.AddCors(options => {
                options.AddDefaultPolicy(policy => {
                    policy.WithOrigins([
                        "http://localhost:5000", "https://localhost:5001", "http://localhost:8080",
                        "https://localhost:5173", "http://localhost:5173",
                    ])
                    .AllowCredentials()
                    .WithHeaders(["Content-Type", "Allow", "Authorization"])
                    .SetPreflightMaxAge(TimeSpan.FromHours(1));
                });
            });
            services.AddTransient<IStartupFilter, StartupFilter>();
        });

    public class StartupFilter : IStartupFilter
    {
        public Action<IApplicationBuilder> Configure(Action<IApplicationBuilder> next) => app =>
        {
            app.UseCors();
            next(app);
        };
    }        
}
```

### CORS Feature Plugin

The **CorsFeature** plugin supports all ServiceStack Hosts which wraps CORS headers into an encapsulated [Plugin][1] to make it much easier to add CORS support to your ServiceStack services. 

Commonly this is now all that's needed:

```csharp
Plugins.Add(new CorsFeature());
```

Which uses the default values:

```csharp
CorsFeature(allowedOrigins:"*", 
    allowedMethods:"GET, POST, PUT, DELETE, OPTIONS", 
    allowedHeaders:"Content-Type", 
    allowCredentials:false);
```

You can leave out any of the values matching the default. E.g. if you just wanted to restrict the allowed methods to just GET and POST requests, you can just do:

```csharp
Plugins.Add(CorsFeature(allowedMethods:"GET, POST"));
```

### Allow specific origins

Use `allowOriginWhitelist` when you want to only allow CORS access by specific sites:

```csharp
Plugins.Add(new CorsFeature(
    allowOriginWhitelist: new[] { "http://localhost","http://localhost:5000","http://run.plnkr.co" },
    allowCredentials: true,
    allowedHeaders: "Content-Type, Allow, Authorization, X-Args"));
```

### Enabling CORS per-service support

Instead of using the plugin above, ServiceStack also allows you to enable CORS on a per-service basis by using **[EnableCors]** [Response Filter attribute][2] which has the same defaults as above. E.g. You can enable just GET, POST as above with:

```csharp
[EnableCors(allowedMethods:"GET,POST")]
public class MyService : Service { ... }
```

## Manually enabling CORS

The beauty of [ServiceStack][3] is that it's built on a highly flexible and simple core. We don't believe in building strong-typed APIs over everything, as it's impossible to predict what new HTTP Headers / StatusCodes will exist in the future. So whilst we provide convenient behavior to accomplish common tasks, we also provide a flexible API that lets you configure any desired HTTP Output. 

### Setting Global HTTP Headers

This is how to globally enable Cross Origin Sharing in you AppHost config:

```csharp
public override void Configure(Container container)
{
    //Permit modern browsers (e.g. Firefox) to allow sending of any HTTP Method
    SetConfig(new HostConfig 
    {
        GlobalResponseHeaders = {
          { "Access-Control-Allow-Origin", "*" },
          { "Access-Control-Allow-Methods", "GET, POST, PUT, DELETE, OPTIONS" },
          { "Access-Control-Allow-Headers", "Content-Type" },
        },
    });
}
```

### Returning Custom HTTP Headers in a service

These headers will get sent on every request, alternatively you can also enable it for specific web services, i.e. take the [Hello World Web Service][4] for example:

```csharp
public class Hello {
    public string Name { get; set; }
}

public class HelloResponse {
    public string Result { get; set; }
}

public class HelloService : IService 
{
    public object Any(Hello request)
    {
        var dto = new HelloResponse { Result = "Hello, " + request.Name };
        return new HttpResult(dto) {
            Headers = {
              { "Access-Control-Allow-Origin", "*" },
              { "Access-Control-Allow-Methods", "GET, POST, PUT, DELETE" } 
              { "Access-Control-Allow-Headers", "Content-Type" }, 
            }
        };
    }
}
```

The above is all the C# code you need to develop a web service which is then automatically wired up for you on all HTTP Verbs (GET, POST, etc) and built-in endpoints, i.e. JSON, XML, JSV, HTML, CSV, SOAP 1.1/1.2 - for free, without any config or friction required. Checkout  [the live example of the above web service][5].

## JSONP

In addition to the above endpoints each service is available to be called by [JSONP](https://en.wikipedia.org/wiki/JSONP) (another popular way to enable cross-domain service calls in Ajax apps) where each service can be called via JSONP by simply adding the **?callback=cb** parameter to the querystring, e.g:

[techstacks.io/technology/servicestack?callback=cb](https://techstacks.io/technology/servicestack?callback=cb):

```js
//Response:
cb({ 
    ... 
})
```

  [1]: /plugins
  [2]: /filter-attributes
  [3]: http://www.servicestack.net
  [4]: http://www.servicestack.net/ServiceStack.Hello/
  [5]: http://www.servicestack.net/ServiceStack.Hello/
  [6]: http://stackoverflow.com/questions/6245616/does-servicestack-support-binary-responses
  [7]: http://www.servicestack.net/benchmarks/


# Proxy Feature
Source: https://docs.servicestack.net/proxy-feature

The `ProxyFeature` plugin is an application-level proxy that can be used to transparently proxy HTTP Requests through to
downstream servers whose behavior can be customized with custom C# hooks to control how requests are proxied.
 
`ProxyFeature` registers an async/non-blocking `RawHttpHandler` which bypasses ServiceStack's Request Pipeline that in ASP.NET is executed as an ASP.NET `IHttpAsyncHandler` so it should be flexible and performant enough to handle many demanding workloads.

## Usage

The example configuration below registers multiple proxies which proxies all requests to `/techstacks`, `/marketing` or `/finance` endpoints to their configured downstream servers:
 
```csharp
Plugins.Add(new ProxyFeature(
    matchingRequests: req => req.PathInfo.StartsWith("/techstacks"),
    resolveUrl:req => $"http://{resolve(req)}.techstacks.io" + req.RawUrl.Replace("/techstacks","/")))
 
Plugins.Add(new ProxyFeature(
    matchingRequests: req => req.PathInfo.StartsWith("/marketing"),
    resolveUrl:req => "http://marketing.domain.com" + req.RawUrl.Replace("/marketing", "/")))
 
Plugins.Add(new ProxyFeature(
    matchingRequests: req => req.PathInfo.StartsWith("/finance"),
    resolveUrl:req => "http://finance.domain.com" + req.RawUrl.Replace("/finance", "/")))
```
 
Just like a normal HTTP Proxy, `ProxyFeature` forwards all the HTTP Request Headers and returns all the HTTP Response Headers and body of the downstream server inc. HTTP Error Responses. This works especially well with ServiceStack's message-based design as the proxied endpoint e.g `/techstacks` can be treated as if it were the **BaseUrl** for the downstream server which allows external clients to treat it like they're communicating with the downstream server directly despite every request being transparently proxied behind a central external ServiceStack instance.

## Use Cases
 
One potential use-case is to enable smart load balancing which lets you use C# to dynamically control which external downstream server requests are proxied to. 

Thanks to ServiceStack's clean Service Gateway design you can use the clean POCO DTOs from any server instance, which you can get using the 
[x dotnet tool](/dotnet-tool) or [npm servicestack-cli](https://github.com/ServiceStack/servicestack-cli) utils from either the public url or proxy endpoint url, e.g:
 
```bash
x csharp https://techstacks.io
x csharp https://external.domain.com/techstacks
```
 
The resulting DTOs can be used with any [.NET Service Client](/csharp-client#built-in-clients), configured with the proxy endpoint as the **BaseUrl**:
 
```csharp
var client = new JsonApiClient("https://external.domain.com/techstacks");
 
var request = new GetTechnology { Slug = "ServiceStack" };
var response = client.Get(request);
response.PrintDump();
```
 
Another potential use-case is to have the proxy act like a facade to access multiple internal microservices that can be made available behind a single external URL, e.g:
 
```csharp
var authRequest = new Authenticate { ... };
 
var marketingClient = new JsonApiClient("https://external.domain.com/marketing");
var authResponse = marketingClient.Post(authRequest);
 
var financeClient = new JsonHttpClient("https://external.domain.com/finance");
var authResponse = await financeClient.PostAsync(authRequest);
```
 
When needed, there's a number of customization options available which enables complete control in how the request is proxied and ultimately what response is returned to clients:
 
```csharp
class ProxyFeature
{
    // Required filters to specify which requests to proxy and which url to use
    ProxyFeature(
        Func<IHttpRequest, bool> matchingRequests, // Which requests should be proxied
        Func<IHttpRequest, string> resolveUrl);    // Which downstream url to use 
 
    // Customize the HTTP Request Headers that are sent to downstream server
    Action<IHttpRequest, HttpWebRequest> ProxyRequestFilter
 
    // Customize the downstream HTTP Response Headers that are returned to client
    Action<IHttpResponse, HttpWebResponse> ProxyResponseFilter
 
    // Inspect or Transform the HTTP Request Body that's sent downstream
    Func<IHttpRequest, Stream, Task<Stream>> TransformRequest
 
    // Inspect or Transform the downstream HTTP Response Body that's returned
    Func<IHttpResponse, Stream, Task<Stream>> TransformResponse
}
```
 
So you could use the `TransformResponse` delegate for instance to rewrite any internal urls to use external urls with something like:
 
```csharp
Plugins.Add(new ProxyFeature(
    matchingRequests: req => req.PathInfo.StartsWith("/techstacks"),
    resolveUrl: req => $"http://{resolve(req)}.techstacks.io" + req.RawUrl.Replace("/techstacks","/"))
    {
        TransformResponse = async (res, responseStream) => 
        {
            using var reader = new StreamReader(responseStream, Encoding.UTF8);
            var responseBody = await reader.ReadToEndAsync();
            var replacedBody = responseBody.Replace(
                "https://techstacks.io",
                "https://external.domain.com/techstacks");
            return MemoryStreamFactory.GetStream(replacedBody.ToUtf8Bytes());
        }
    });
```


# Request Loggers
Source: https://docs.servicestack.net/request-logger

Add an In-Memory `IRequestLogger` and service with the default route at `/requestlogs` which maintains a live log of the most recent requests (and their responses). Supports multiple config options incl. Rolling-size capacity, error and session tracking, hidden request bodies for sensitive services, etc.

```cs
Plugins.Add(new RequestLogsFeature());
```

### CSV Request Logger

One of the areas where ServiceStack's [CSV Support](/csv-format) shines is being able to store daily Request Logs in a plain-text structured format, that way they could be immediately inspectable with a text editor or for even better inspection, opened in a spreadsheet and benefit from its filterable, movable, resizable and sortable columns.

To enable CSV Request Logging you just need to register the `RequestLogsFeature` and configure it to use the
[CsvRequestLogger](https://github.com/ServiceStack/ServiceStack/blob/master/src/ServiceStack/CsvRequestLogger.cs):

```csharp
Plugins.Add(new RequestLogsFeature {
    RequestLogger = new CsvRequestLogger(),
});
```

This will register the CSV Request logger with the following overridable defaults:

```csharp
Plugins.Add(new RequestLogsFeature {
    RequestLogger = new CsvRequestLogger(
        files: new FileSystemVirtualFiles(HostContext.Config.WebHostPhysicalPath),
        requestLogsPattern: "requestlogs/{year}-{month}/{year}-{month}-{day}.csv",
        errorLogsPattern: "requestlogs/{year}-{month}/{year}-{month}-{day}-errors.csv",
        appendEvery: TimeSpan.FromSeconds(1)
    ),
});
```

Where Request Logs are flushed every **1 second** using a background Timer to a daily log maintained in
the logical date format structure above. As it would be useful to be able to inspect any errors in isolation, 
errors are also written to a separate `YYYY-MM-DD-errors.csv` format, in addition to the main Request logs.

### [Custom CSV AutoQuery Data implementation](/autoquery/service#custom-autoquery-data-implementation)

The AutoQuery Service example shows you can quickly create an AutoQuery Data Service that lets you inspect your CSV Request and Error Logs with AutoQuery, which in addition to the rich querying benefits also gives you access to an instant UI in [AutoQuery Viewer](https://github.com/ServiceStack/Admin) to be able to [View your Request Logs](/autoquery/service#view-request-logs-in-autoquery-viewerhttpsgithubcomservicestackadmin).

## Rollbar Request Logger

The [iayos.ServiceStack.RollbarPlugin](https://github.com/daleholborow/iayos.ServiceStack.RollbarPlugin) integrates with [Rollbar](https://rollbar.com) real-time error monitoring solution which has a free tier to log up to 5,000 requests per month.

### Install

To use `RollbarLoggerPlugin` install the [iayos.ServiceStack.RollbarPlugin](https://www.nuget.org/packages/iayos.ServiceStack.RollbarPlugin) NuGet package:

:::copy
`<PackageReference Include="iayos.ServiceStack.RollbarPlugin" Version="0.0.1" />`
:::

Sign Up for a new account on [Rollbar](https://rollbar.com). Then register `RollbarLoggerPlugin` with the your API Key:

```csharp
Plugins.Add(new RollbarLoggerPlugin
{
    ApiKey = rollbarApiKey,
    //..
}
```

Please see the [iayos.ServiceStack.RollbarPlugin](https://github.com/daleholborow/iayos.ServiceStack.RollbarPlugin) project for additional customization options.

## Redis Request Logger

The HTTP Request logs can also be configured to persist to a distributed [Redis](https://redis.io) data store instead by configuring the `RequestLogsFeature` plugin to use the `RedisRequestLogger`. Persisting logs in redis will allow them to survive and be view-able across App Domain restarts.

### Install

To use `RedisRequestLogger` first install the **ServiceStack.Server** NuGet package:

:::copy
`<PackageReference Include="ServiceStack.Server" Version="8.*" />`
:::

Then configure `RequestLogsFeature` to use the `RedisRequestLogger` which can make use of your existing `IRedisClientsManager` registered IOC dependency, e.g:

```csharp
Plugins.Add(new RequestLogsFeature {
    RequestLogger = new RedisRequestLogger(
	    container.Resolve<IRedisClientsManager>(), capacity:1000)
});
```

::: info Tip
The optional `capacity` configures Redis Request Logger as a rolling log where it will only keep the most recent 1000 entries
:::

### Configuration

Like other ServiceStack [Plugins](/plugins) the `RequestLogsFeature` has a number of configuration options that can be specified at registration to customize Request Logging:


```csharp
class RequestLogsFeature 
{
    // Limit API access to users in role
    string AccessRole = RoleNames.Admin;

    // RequestLogs service Route, default is /requestlogs
    string AtRestPath = "/requestlogs";

    // Size of memory logger circular buffer
    int? Capacity;

    // Turn On/Off Session Tracking
    bool EnableSessionTracking;

    // Turn On/Off Logging of Raw Request Body, default is Off
    bool EnableRequestBodyTracking;

    // Turn On/Off Raw Request Body Tracking per-request
    Func<IRequest, bool> RequestBodyTrackingFilter;

    // Turn On/Off Tracking of Responses
    bool EnableResponseTracking = false;

    // Turn On/Off Tracking of Responses per-request
    Func<IRequest, bool> ResponseTrackingFilter;
    
    // Turn On/Off Tracking of Exceptions
    bool EnableErrorTracking = true;

    // Don't log matching requests
    Func<IRequest, bool> SkipLogging;

    // Change the RequestLogger provider. Default is InMemoryRollingRequestLogger
    IRequestLogger RequestLogger;

    // Don't log requests of these types. By default RequestLog's are excluded
    Type[] ExcludeRequestDtoTypes;

    // Don't log request body's for services with sensitive information.
    // By default Auth and Registration requests are hidden.
    Type[] HideRequestBodyForRequestDtoTypes;
    
    // Don't log Response DTO Types
    Type[] ExcludeResponseTypes;

    // Limit logging to only Service Requests
    bool LimitToServiceRequests = true;
    
    // Customize Request Log Entry
    Action<IRequest, RequestLogEntry> RequestLogFilter;

    // Ignore logging and serializing these Request DTOs
    List<Type> IgnoreTypes; = new();
    
    // Use custom Ignore Request DTO predicate
    Func<object,bool> IgnoreFilter = DefaultIgnoreFilter;

    // Default take, if none is specified
    int DefaultLimit = 100;

    // Change what DateTime to use for the current Date (defaults to UtcNow)
    Func<DateTime> CurrentDateFn = () => DateTime.UtcNow;
}
```

### Usage

The `IRequestLogger` is a great way to introspect and analyze your service requests in real-time, e.g:

![Live Screenshot](/img/pages/plugins/request-logs-01.png)

It supports multiple queryString filters and switches so you filter out related requests for better analysis and debuggability:

![Request Logs Usage](/img/pages/plugins/request-logs-02.png)

The [RequestLogsService](https://github.com/ServiceStack/ServiceStack/blob/master/src/ServiceStack/Admin/RequestLogsService.cs) is just a simple C# service under-the-hood but is a good example of how a little bit of code can provide a lot of value in ServiceStack's by leveraging its generic, built-in features.


# SQLite Request Logs
Source: https://docs.servicestack.net/sqlite-request-logs

Up until this release all of ServiceStack's database features like [AutoQuery](https://servicestack.net/autoquery)
have been database agnostic courtesy of OrmLite's [support for popular RDBMS's](/ormlite/installation)
so that they integrate into an App's existing configured database.

[Background Jobs](/background-jobs) is our first foray into a SQLite-only backend, as it's the only 
RDBMS that enables us to provide encapsulated black-box functionality without requiring any infrastructure 
dependencies. It's low latency, high-performance and ability to create lightweight databases on the fly make 
it ideal for self-managing isolated appliance backends like Background Jobs and Request Logging which don't 
benefit from integrating with your existing RDBMS.

The new [ServiceStack.Jobs](https://nuget.org/packages/ServiceStack.Jobs) NuGet package allows us
to deliver plug and play SQLite backed features into .NET 8 Apps that are configured with any RDBMS
or without one. The next feature added is a SQLite backed provider for [Request Logs](/request-logger) 
with the new `SqliteRequestLogger` which can be added to existing .NET 8 Apps with the
[mix tool](/mix-tool):

:::sh
x mix sqlitelogs
:::

Which adds a reference to **ServiceStack.Jobs** and the [Modular Startup](/modular-startup) config below:

```csharp
using ServiceStack.Jobs;
using ServiceStack.Web;

[assembly: HostingStartup(typeof(MyApp.ConfigureRequestLogs))]

namespace MyApp;

public class ConfigureRequestLogs : IHostingStartup
{
    public void Configure(IWebHostBuilder builder) => builder
        .ConfigureServices((context, services) => {
            
            services.AddPlugin(new RequestLogsFeature {
                RequestLogger = new SqliteRequestLogger(),
                EnableResponseTracking = true,
                EnableRequestBodyTracking = true,
                EnableErrorTracking = true
            });
            services.AddHostedService<RequestLogsHostedService>();
        });
}

public class RequestLogsHostedService(ILogger<RequestLogsHostedService> log, IRequestLogger requestLogger) : BackgroundService
{
    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
    {
        var dbRequestLogger = (SqliteRequestLogger)requestLogger;
        using var timer = new PeriodicTimer(TimeSpan.FromSeconds(3));
        while (!stoppingToken.IsCancellationRequested && await timer.WaitForNextTickAsync(stoppingToken))
        {
            dbRequestLogger.Tick(log);
        }
    }
}
```

This will use a Hosted Background Service to flush Request Logs to the requests SQLite database 
every **3** seconds (configurable in the PeriodicTimer).

If your App is already using `RequestLogsFeature` configured (e.g. with Profiling) you'll want to
remove it:

```csharp
public class ConfigureProfiling : IHostingStartup
{
    public void Configure(IWebHostBuilder builder) => builder
        .ConfigureServices((context, services) => {
            // services.AddPlugin(new RequestLogsFeature());
            services.AddPlugin(new ProfilingFeature
            {
                IncludeStackTrace = true,
            });
        });
}
```

## Rolling SQLite Databases

The benefit of using SQLite is that databases can be created on-the-fly where Requests will be persisted
into isolated **requests** Monthly databases which can be easily archived into managed file storage instead 
of a singular growing database, visible in the [Database Admin UI](/admin-ui-database):

![](/img/pages/sqlite/sqlite-databases.webp)

SQLite logs will also make it easier to generate monthly aggregate reports to provide key insights
into the usage of your App.

## AutoQuery Grid Admin Logging UI

As SQLite Requests Logs also makes it efficiently possible to sort and filter through logs, the
Logging UI will switch to using a fully queryable `AutoQueryGrid` when using `SqliteRequestLogger`:

![](/img/pages/sqlite/sqlite-request-logs.webp)

## Export to CSV

When needed you can export your Request Logs to CSV for easy import into external systems using SQLite's
`sqlite3` utility, e.g:

:::sh
`sqlite3 -header -csv requests_<YYYY>-<MM>.db  "SELECT * FROM RequestLog" > output.csv`
:::

### Custom Exports

For more complex queries, you can also use the `.mode csv` and `.output` commands within the SQLite shell:

:::sh
`sqlite3 requests_<YYYY>-<MM>.db`
:::

Then set export parameters before running the query and exiting:

```sql
.headers on
.mode csv
.output output.csv
SELECT * FROM RequestLog;
.quit
```


# Lisp TCP REPL Server
Source: https://docs.servicestack.net/lisp-tcp-repl-server

In addition to launching a [Lisp REPL in the web and app dotnet tools](/dotnet-tool#lisp-repl) you can also open a Lisp REPL into any 
ServiceStack App configured with the `LispReplTcpServer` ServiceStack plugin. This effectively opens a **"programmable gateway"** into any 
ServiceStack App where it's able to perform live queries, access IOC dependencies, invoke internal Server functions and query
the state of a running Server which like the [Debug Inspector](/debugging#debug-inspector) 
can provide invaluable insight when diagnosing issues on a remote server.

To see it in action we'll enable it one of our production Apps [techstacks.io](https://techstacks.io) which as it's a 
Vuetify SPA App is only configured with an empty `SharpPagesFeature` as it doesn't use any server-side scripting features.

We'll enable it in `DebugMode` where we can enable by setting `DebugMode` in our App's `appsettings.Production.json` 
which will launch a TCP Socket Server which by default is configured to listen to the **loopback** IP on port `5005`.

```csharp
if (Config.DebugMode)
{
    Plugins.Add(new LispReplTcpServer {
        ScriptMethods = {
            new DbScripts()
        },
        ScriptNamespaces = {
            nameof(TechStacks),
            $"{nameof(TechStacks)}.{nameof(ServiceInterface)}",
            $"{nameof(TechStacks)}.{nameof(ServiceModel)}",
        },
    });
}
```

::: info
[ScriptNamespaces](https://sharpscript.net/docs/script-net#type-resolution) behaves like C#'s `using Namespace;` statement letting you reference Types by `Name` instead of its fully-qualified Namespace
:::

Whilst you can now connect to it with basic `telnet`, it's a much nicer experience to use it with the [rlwrap](https://linux.die.net/man/1/rlwrap)
readline wrap utility which provides an enhanced experience with line editing, persistent history and completion.

:::sh
sudo apt-get install rlwrap
:::

Then you can open a TCP Connection to connect to a new Lisp REPL with:

:::sh
rlwrap telnet localhost 5005
:::

Where you now have full scriptability of the running server as allowed by [#Script Pages](https://sharpscript.net/docs/script-pages) `SharpPagesFeature` which
allows [scripting of all .NET Types](https://sharpscript.net/docs/script-net#allowscriptingofalltypes) by default. 

## TechStacks TCP Lisp REPL Demo

In this demo we'll explore some of the possibilities of scripting the live [techstacks.io](https://techstacks.io) Server where we can 
`resolve` IOC dependencies to send out tweets using its registered `ITwitterUpdates` dependency, view the source and load a remote 
[parse-rss](https://gist.github.com/gistlyn/3624b0373904cfb2fc7bb3c2cb9dc1a3) lisp function into the new Lisp interpreter attached to the TCP connection, 
use it to parse [Hacker News RSS Feed](https://news.ycombinator.com/rss) into a .NET Collection where it can be more easily queried using its built-in functions
which is used to construct an email body with **HN's current Top 5 links**. 

It then uses [DB Scripts](https://sharpscript.net/docs/db-scripts) to explore its configured AWS RDS PostgreSQL RDBMS, listing its DB tables and viewing its 
column names and definitions before retrieving the Email addresses of all **Admin** users, sending them each an email with HN's Top 5 Links by 
publishing **5x** `SendEmail` Request DTOs using the [publishMessage](https://sharpscript.net/docs/servicestack-scripts#publishmessage) ServiceStack Script to where 
they're processed in the background by its configured [MQ Server](/messaging) that uses it to execute the 
`SendEmail` ServiceStack Service where it uses its configured AWS SES SMTP Server to finally send out the Emails:

[![](/img/pages/sharpscript/lisp-tcp-repl.gif)](https://youtu.be/HO523cFkDfk)

::: info YouTube
[youtu.be/HO523cFkDfk](https://youtu.be/HO523cFkDfk)
:::

## Password Protection 

Since TCP Server effectively opens your remote Server up to being scripted you'll want to ensure the TCP Server is only accessible
within a trusted network, effectively treating it the same as [Redis Security Model](https://redis.io/topics/security).

A secure approach would be to leave the default of only binding to `IPAddress.Loopback` so only trusted users with SSH access will 
be able to access it, which they'll still be able to access remotely via `Local PC > ssh > telnet 127.0.0.1 5005`.

Just like [Redis AUTH](https://redis.io/commands/auth) you can also add password protection for an additional layer of Security:

```csharp
Plugins.Add(new LispReplTcpServer {
    RequireAuthSecret = true,
    ...
});
```

Which will only allow access to users with the [configured AuthSecret](/debugging#authsecret):

```csharp
SetConfig(new HostConfig { 
    AdminAuthSecret = "secretz" 
});
```

## Annotated Lisp TCP REPL Transcript

```lisp
; resolve `ITwitterUpdates` IOC dependency and assign it to `twitter`
(def twitter (resolve "ITwitterUpdates"))

; view its concrete Type Name
(typeName twitter)

; view its method names 
(joinln (methods twitter))

; view its method signatures 
(joinln (methodTypes twitter))

; use it to send tweet from its @webstacks account
(.Tweet twitter "Who's using #Script Lisp? https://sharpscript.net/lisp")

; view all available scripts in #Script Lisp Library Index gist.github.com/3624b0373904cfb2fc7bb3c2cb9dc1a3
(gistindex)

; view the source code of the `parse-rss` library
(load-src "index:parse-rss")

; assign the XML contents of HN's RSS feed to `xml`
(def xml (urlContents "https://news.ycombinator.com/rss"))

; preview its first 1000 chars
(subString xml 0 1000)

; use `parse-rss` to parse the RSS feed into a .NET Collection and assign it to `rss`
(def rss (parse-rss xml))

; view the `title`, `description` and the first `item` in the RSS feed:
(:title rss)
(:description rss)
(:0 (:items rss))

; view the links of all RSS feed items
(joinln (map :link (:items rss)))

; view the links and titles of the top 5 news items
(joinln (map :link (take 5 (:items rss))))
(joinln (map :title (take 5 (:items rss))))

; construct a plain-text numbered list of the top 5 HN Links and assign it to `body`
(joinln (map-index #(str %2 (:title %1)) (take 5 (:items rss))))
(joinln (map-index #(str (padLeft (1+ %2) 2) ". " (:title %1)) (take 5 (:items rss))))
(def body (joinln 
    (map-index #(str (padLeft (1+ %2) 2) ". " (:title %1) "\n" (:link %1) "\n") (take 5 (:items rss)))))

; view all TechStacks PostgreSQL AWS RDS tables
(dbTableNames)
(joinln dbTableNames)

; view the column names and definitions of the `technology` table
(joinln (dbColumnNames "technology"))
(joinln (dbColumns "technology"))

; search for all `user` tables
(globln "*user*" (dbTableNames))

; view how many Admin Users with Emails there are
(dbScalar "select count(email) from custom_user_auth where roles like '%Admin%'")

; assign the Admin Users email to the `emails` list
(def emails (map :email (dbSelect "select email from custom_user_auth where roles like '%Admin%'")))

; search for all `operation` script methods
(globln "*operation*" scriptMethods)

; search for all `email` Request DTOs
(globln "*email*" metaAllOperationNames)

; view the properties available on the `SendEmail` Request DTO
(props (SendEmail.))

; search for all `publish` script methods that can publish messages
(globln "publish*" scriptMethods)

; create and publish 5x `SendEmail` Request DTOs for processing by TechStacks configured MQ Server
(doseq (to emails) (publishMessage "SendEmail" { :To to :Subject "Top 5 HN Links" :Body body }))
```


# Postman
Source: https://docs.servicestack.net/postman

The [Postman Rest Client](http://www.getpostman.com/) is a very popular and easy to use HTTP Request composer that makes it easy to call web services, similar to [Fiddler's Composer](https://www.blackbaud.com/files/support/guides/infinitydevguide/Subsystems/inwebapi-developer-help/Content/InfinityWebAPI/coUsingFiddlerCreateHTTPRequest.htm). It also provides as an alternative for autogenerating API documentation to [ServiceStack's Open API support](/openapi) that makes it easier to call existing services but does require users to install the [Postman Rest Client](http://www.getpostman.com/).

Support for Postman is built into ServiceStack and can be enabled by registering the Plugins below:

```csharp
Plugins.Add(new PostmanFeature());
Plugins.Add(new CorsFeature());
```

::: info
As Postman makes cross-site requests, is also requires CORS support. 
:::

Once enabled, a link with appear in your metadata page:

![Postman Metadata link](https://raw.githubusercontent.com/ServiceStack/Assets/master/img/release-notes/postman-metadata.png)

### Importing the Postman Collection

By default the link to the Postman JSON metadata collection is at `/postman`, this url can be imported into postman by clicking on **import collections**:

![Postman Import Icon](https://raw.githubusercontent.com/ServiceStack/Assets/master/img/wikis/postman-import-link.png)

This will open up the import dialog, where you can paste the metadata url and click **Import**:

![Postman Import Dialog](https://raw.githubusercontent.com/ServiceStack/Assets/master/img/wikis/postman-import.png)

### Available Routes 

Once imported it will populate a list of available operations that can be selected and easily called from within the Postman UI. Just like the [Open API Support](/openapi) the list of operations returned respects the [Restriction Attributes](/auth/restricting-services) and only shows the operations each user is allowed to see. The operations returned also favour custom user-defined routes, when none exists it will fallback to use the [pre-defined routes](/routing#pre-defined-routes).

### Label Customization

The label for each operation can be further customized using the `?label` query string param whose preferred style which can vary depending on the granularity and naming of your Request DTO's, and whether they have custom routes defined on them. 

![Postman Label Styles](https://raw.githubusercontent.com/ServiceStack/Assets/master/img/wikis/postman-labels.png)

The screenshot above shows an example of importing the same service with the different label styles below: 

 - [/postman?label=route](https://benchmarks.servicestack.net/postman?label=route)
 - [/postman?label=type](https://benchmarks.servicestack.net/postman?label=type)

The `label` param accepts a collection of string tokens that controls how the label is formatted.The `type` and `route` are special tokens that get replaced by the **Request DTO name** and **Route** respectively. Everything else are just added string literals including the `+` character which is just a url-encoded version of the ` ` space character.

Here are some examples using the example definition below:

```csharp
[Route("/contacts/{Id}")]
public class GetContact { ... }
```

<table class="table">
<tr>
    <td><b>/postman?label=type</b></td>
    <td>GetContact</td>
</tr>
<tr>
    <td><b>/postman?label=route</b></td>
    <td>/contacts/{Id}</td>
</tr>
<tr>
    <td><b>/postman?label=type:english</b></td>
    <td>Get contact</td>
</tr>
<tr>
    <td><b>/postman?label=type:english,+(,route,)</b></td>
    <td>Get contact (/contacts/{Id})</td>
</tr>
</table>

#### Specifying the Default Label Format

The default label format can also be configured when registering the Postman plugin, e.g:

```csharp
Plugins.Add(new PostmanFeature { 
    DefaultLabelFmt = new List<string> { "type:english", " ", "route" }
});
```

## Calling Services

Calling Services is as easy as selecting the service you want to call, filling in the parameters you want to call it with then clicking **Send**. At a mimimum you want to specify values for all the path variables in the `/pathInfo` which are prefixed with a colon followed by its name, e.g: `:VariableName`

![Call Service in Postman](https://raw.githubusercontent.com/ServiceStack/Assets/master/img/wikis/postman-call-searchtestresults.png)

The Path Info variables appear first in the list of available **URL params** for each service, as seen with **TestPlanId** above. By default each variable is seeded with its type. Any variables defined on the /pathinfo are sent on the pathinfo whilst other variables in a `GET` request are sent on the Query String. `POST` requests also allow sending parameters as **form-data**.

### Support for authenticated requests

Calling authentication-only services can be done with the `/postman?exportSession=true` parameter which will redirect to a url that captures your session cookies into a deep-linkable url like `/postman?ssopt=temp&ssid={key}&sspid={key}` that can be copied into Postman.

This lets you replace your session cookies with the session ids on the url, effectively allowing you to take over someone elses session, in this case telling Postman to make requests on your behalf using your authenticated session cookies. 

As this functionality is potentially dangerous it's only enabled by default in **DebugMode** but can be overridden with:

```csharp
Plugins.Add(new PostmanFeature { 
    EnableSessionExport = true
});
```

## Other PostmanFeature options

Like other [ServiceStack plugins](/plugins) the available options for each Feature can be configured on the Plugin itself at registration:

#### Registering at a custom path

Use `AtRestPath` to host the postman metadata route on an alternate:

```csharp
Plugins.Add(new PostmanFeature { 
    AtRestPath = "/alt-postman-link"  //default /postman
});
```

#### Sending Custom HTTP Headers

Use `Headers` to get Postman to send custom HTTP Headers on each request, e.g:

```csharp
Plugins.Add(new PostmanFeature { 
    Headers = "Accept: application/json\nX-Custom-Header: Value",
});
```

The default is `Accept: application/json` to ensure each request returns its response as JSON. Multiple headers can be separated with the `\n` new-line character.

#### Friendly Type Aliases

The names of the type for Request DTO Property Types displayed can also be customized by adding them to the `FriendlyTypeNames` Dictionary. E.g. we can show `DateTime` types as `Date` in Postmans UI with:

```csharp
Plugins.Add(new PostmanFeature { 
    FriendlyTypeNames = { {"DateTime", "Date"} },
});
```


# Sitemaps
Source: https://docs.servicestack.net/sitemaps

A good SEO technique for helping Search Engines index your website is to tell them where the can find all your content using [Sitemaps](https://support.google.com/webmasters/answer/156184?hl=en). Sitemaps are basic xml documents but they can be tedious to maintain manually, more so for database-driven dynamic websites. 

The `SitemapFeature` reduces the effort required by letting you add Site Urls to a .NET collection of `SitemapUrl` POCO's. 
In its most basic usage you can populate a single Sitemap with urls of your Website Routes, e.g:

```csharp
Plugins.Add(new SitemapFeature
{
    UrlSet = db.Select<TechnologyStack>()
    .ConvertAll(x => new SitemapUrl {
        Location = new ClientTechnologyStack { Slug = x.Slug }.ToAbsoluteUri(),
        LastModified = x.LastModified,
        ChangeFrequency = SitemapFrequency.Weekly,
    })
});
```

The above example uses [OrmLite](https://github.com/ServiceStack/ServiceStack.OrmLite) to generate a collection of `SitemapUrl` entries containing Absolute Urls for all [techstacks.io Technology Pages](https://techstacks.io/tech). This is another good showcase for the [Reverse Routing available on Request DTO's](/routing#reverse-routing) which provides a Typed API for generating Urls without any additional effort.

Once populated your sitemap will be available at `/sitemap.xml` which looks like:

```xml
<?xml version="1.0" encoding="UTF-8"?>
<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
<url>
  <loc>https://techstacks.io/the-guardian</loc>
  <lastmod>2015-01-14</lastmod>
  <changefreq>weekly</changefreq>
</url>
...
</urlset>
```

Which you can checkout in this [live Sitemap example](https://techstacks.io/sitemap-techstacks.xml).

## Multiple Sitemap Indexes

For larger websites, Sitemaps also support multiple [Sitemap indexes](https://support.google.com/webmasters/answer/75712?hl=en) which lets you split sitemap urls across multiple files. To take advantage of this in `SitemapFeature` you would instead populate the `SitemapIndex` collection with multiple `Sitemap` entries. An example of this is in the full [Sitemap used by techstacks.io](https://github.com/ServiceStackApps/TechStacks/blob/a114348e905b4334e93a5408c2fb76c5fb589501/src/TechStacks/TechStacks/AppHost.cs#L90-L128):

```csharp
Plugins.Add(new SitemapFeature {
SitemapIndex = {
    new Sitemap {
        AtPath = "/sitemap-techstacks.xml",
        LastModified = DateTime.UtcNow,
        UrlSet = db.Select<TechnologyStack>()
        .Map(x => new SitemapUrl {
            Location = new ClientTechnologyStack {Slug=x.Slug}.ToAbsoluteUri(),
            LastModified = x.LastModified,
            ChangeFrequency = SitemapFrequency.Weekly,
        }),
    },
    new Sitemap {
        AtPath = "/sitemap-technologies.xml",
        LastModified = DateTime.UtcNow,
        UrlSet = db.Select<Technology>()
        .Map(x => new SitemapUrl {
            Location = new ClientTechnology {Slug = x.Slug}.ToAbsoluteUri(),
            LastModified = x.LastModified,
            ChangeFrequency = SitemapFrequency.Weekly,
        })
    },
    new Sitemap
    {
        AtPath = "/sitemap-users.xml",
        LastModified = DateTime.UtcNow,
        UrlSet = db.Select<CustomUserAuth>()
        .Map(x => new SitemapUrl {
            Location = new ClientUser {UserName = x.UserName}.ToAbsoluteUri(),
            LastModified = x.ModifiedDate,
            ChangeFrequency = SitemapFrequency.Weekly,
        })
    }
}});
```

Which now generates the following `<sitemapindex/>` at [/sitemap.xml](https://techstacks.io/sitemap.xml):

```xml
<?xml version="1.0" encoding="UTF-8"?>
<sitemapindex xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
<sitemap>
  <loc>https://techstacks.io/sitemap-techstacks.xml</loc>
  <lastmod>2015-01-15</lastmod>
</sitemap>
<sitemap>
  <loc>https://techstacks.io/sitemap-technologies.xml</loc>
  <lastmod>2015-01-15</lastmod>
</sitemap>
<sitemap>
  <loc>https://techstacks.io/sitemap-users.xml</loc>
  <lastmod>2015-01-15</lastmod>
</sitemap>
</sitemapindex>
```

With each entry linking to the urlset for each Sitemap:

 - [techstacks.io/sitemap-techstacks.xml](https://techstacks.io/sitemap-techstacks.xml)
 - [techstacks.io/sitemap-technologies.xml](https://techstacks.io/sitemap-technologies.xml)
 - [techstacks.io/sitemap-users.xml](https://techstacks.io/sitemap-users.xml)


# Cancellable Requests
Source: https://docs.servicestack.net/cancellable-requests

The Cancellable Requests Feature makes it easy to design long-running Services that are cancellable with an external Web Service Request. To enable this feature, register the `CancellableRequestsFeature` plugin:

```csharp
Plugins.Add(new CancellableRequestsFeature());
```

## Designing a Cancellable Service

Then in your Service you can wrap your implementation within a disposable `ICancellableRequest` block which encapsulates a Cancellation Token that you can watch to determine if the Request has been cancelled, e.g: 

```csharp
public object Any(TestCancelRequest req)
{
    using (var cancellableRequest = base.Request.CreateCancellableRequest())
    {
        //Simulate long-running request
        while (true)
        {
            cancellableRequest.Token.ThrowIfCancellationRequested();
            Thread.Sleep(100);
        }
    }
}
```

## Cancelling a remote Service

To be able to cancel a Server request on the client, the client must first **Tag** the request which it does by assigning the `X-Tag` HTTP Header with a user-defined string in a Request Filter before calling a cancellable Service, e.g:

```csharp
var tag = Guid.NewGuid().ToString();
var client = new JsonServiceClient(baseUri) {
    RequestFilter = req => req.Headers[HttpHeaders.XTag] = tag
};

var responseTask = client.PostAsync(new TestCancelRequest());
```

Then at anytime whilst the Service is still executing the remote request can be cancelled by calling the `CancelRequest` Service with the specified **Tag**, e.g: 

```csharp
var cancelResponse = client.Post(new CancelRequest { Tag = tag });
```

If it was successfully cancelled it will return a `CancelRequestResponse` DTO with the elapsed time of how long the Service ran for. Otherwise if the remote Service had completed or never existed it will throw **404 Not Found** in a `WebServiceException`.


# Web Hooks
Source: https://docs.servicestack.net/webhooks

Add Webhooks to your ServiceStack services, and allow other services to integrate with yours across the web.

## [ServiceStack.Webhooks](https://github.com/jezzsantos/servicestack.webhooks)

The [WebHookFeature](https://github.com/jezzsantos/servicestack.webhooks) plugin 
by [Jezz Santos](https://github.com/jezzsantos) makes it very easy to expose webhook notifications from your ServiceStack services, 
and helps you manage your user's subscriptions to those webhooks.:

:::copy
`<PackageReference Include="ServiceStack.Webhooks" Version="3.*" />`
:::

By adding the `WebhookFeature` to the `AppHost` of your service, 
you automatically get all the pieces you need to raise and manage the events raised by your services.

```csharp
public override void Configure(Container container)
{
    // Add ValidationFeature and AuthFeature plugins first

    Plugins.Add(new WebhookFeature());
}
```

![](https://raw.githubusercontent.com/jezzsantos/ServiceStack.Webhooks/master/docs/img/pages/Webhooks.Architecture.PNG)

See [Getting Started](https://github.com/jezzsantos/ServiceStack.Webhooks/wiki/Getting-Started) for more details.

## Raising Events

To raise events from your own services:

1. Add the `IWebhooks` dependency to your service
2. Call: `IWebhooks.Publish<TDto>(string eventName, TDto data)`

As simple as this:

```
internal class HelloService : Service
{
    public IWebhooks Webhooks { get; set; }

    public HelloResponse Any(Hello request)
    {
        Webhooks.Publish("hello", new HelloEvent{ Text = "I said hello" });
    }
}
```

## Subscribing to Events

Subscribers to events raised by your services need to create a webhook subscription to those events.

They do this by POSTing something like the following, to your service:

```
POST /webhooks/subscriptions
{
    "name": "My Webhook",
    "events": ["hello", "goodbye"],
    "config": {
        "url": "http://myserver/api/incoming",
    }
}
```

## Consuming Events

To consume events, a subscriber needs to provide a public HTTP POST endpoint on the internet that would receive the POSTed webhook event. 

The URL to that endpoint is defined in the `config.url` of the subscription (above).

In the case of the "hello" event (raised above), the POSTed event sent to the subscriber's endpoint might look something like this:

```
POST http://myserver/hello HTTP/1.1
Accept: application/json
User-Agent: ServiceStack .NET Client 4.56
Accept-Encoding: gzip,deflate
X-Webhook-Delivery: 7a6224aad9c8400fb0a70b8a71262400
X-Webhook-Event: hello
Content-Type: application/json
Host: myserver
Content-Length: 26
Expect: 100-continue
Proxy-Connection: Keep-Alive

{
    "Text": "I said hello"
}
```

To consume this event with a ServiceStack service, the subscriber would standup a public API like the one below, that could receive the 'Hello' event. That might have been raised from another service with a call to `Webhooks.Publish("hello", new HelloEvent{ Text = "I said hello" })`:

```
internal class MyService : Service
{
    public void Post(HelloDto request)
    {
        // They said hello!
        var message = request.Text;

       
        // The event name, messaging metadata are included in the headers
        var eventName = Request.Headers["X-Webhook-Event"];
        var deliveryId = Request.Headers["X-Webhook-Delivery"];
        var signature = Request.Headers["X-Hub-Signature"];
    }
}

[Route("/hello", "POST")]
public class HelloDto
{
    public string Text { get; set; }
}
```

Note: Webhook events can be delivered securely to subscribers using signatures, that proves the authenticity of the sender only. Delivered events are never encrypted, and only signed. See [Subscriber Security](https://github.com/jezzsantos/ServiceStack.Webhooks/wiki/Subscriber-Security) for more details.

# [Documentation](https://github.com/jezzsantos/ServiceStack.Webhooks/wiki)

More documentation about how the `WebhookFeature` works, and how to customize it are available in [here](https://github.com/jezzsantos/ServiceStack.Webhooks/wiki)

# Plugins

  - [Custom sinks and stores](https://github.com/jezzsantos/ServiceStack.Webhooks/wiki/Plugins)


# Smart MVC Razor Pages
Source: https://docs.servicestack.net/netcore-razor

Driven by our preference for [API-first style of Web Development](/api-first-development)
we've developed our own [ServiceStack Razor Pages](http://razor.netcore.io) which lets you develop dynamic
Web Pages using Razor to generate the HTML view of your existing Services - saving you from maintaining a 
parallel Controller implementation that's limited to just Web Pages. The benefits of an API-first
approach is that you'll naturally get a well-defined servicified interface which can be consumed by all 
consumers including Web, Native Mobile and Desktop Apps whilst also enabling simplified B2B Integrations, 
Automation, Integration testing, etc.

### RazorFormat Usage

You can find .NET Core Razor features documented in [razor.netcore.io](http://razor.netcore.io) which 
is maintained in our MVC NuGet package that can be installed with: 

:::copy
`<PackageReference Include="ServiceStack.Mvc" Version="8.*" />`
:::


Then to enable, register the `RazorFormat` plugin:

```csharp
public override void Configure(Container container)
{
    Plugins.Add(new RazorFormat());
}
```

#### [No Ceremony Dynamic Pages without Controllers](http://razor.netcore.io/#no-ceremony)

In a lot of cases where you're not developing Web Forms accepting User Input (e.g. generating a dynamic 
page using simple page-specific db queries) you won't need a Controller or Service at all. 
For this scenario we developed [Controller-less Razor Pages](http://razor.netcore.io/#smart-views), 
where if you specify a Typed `@model`, ServiceStack automatically populates it from the HTTP Request Params 
and when no `@model` exists ServiceStack instead populates the Request params in a `ViewDataDictionary` - 
in both cases letting you access any Request Params using **@Model.Name** notation.

Razor Pages also lets you layout your Razor Views in whatever structure you want under `/wwwroot` 
which it will let you call using [Pretty URLs by default](http://razor.netcore.io/#no-ceremony) so you're 
not led into following the MVC-specific `{Controller}/{Action}` pattern or made to define Custom Routes.

.NET Core Razor Pages implementation also lets you structure your Razor Pages under `/Views/Pages` as an 
alternative to maintaining them under `/wwwroot`.

### MVC Razor Pages

Unfortunately in .NET Core we weren't able to reuse any of our existing **ServiceStack.Razor** implementation,
but as we found the development model and end-user experience of Razor without MVC Controllers and Actions 
much more productive we investigated how it could best be implemented in .NET Core. Unfortunately 
.NET Core's Razor support is tightly coupled to MVC's implementation, but fortunately for us MVC also 
provided the necessary APIs where we could re-implement ServiceStack.Razor's user-facing features using 
just MVC Razor Views. 

In many ways this turned out to be a blessing in disguise as by using MVC's implementation we also get 
access to new MVC .NET Core features and its surrounding ecosystem like Tag Helpers. MVC also takes care 
of live-reloading Razor Views behind-the-scenes so we're also able to get the same iterative development 
experience we're used to. By using MVC Views we also naturally get good tooling support which 
[can be a dark art in .NET 4.5](/razor-notes.html)
which was tightly coupled to **Web.config** configuration and therefore poorly supported in Self-Hosting 
Console Apps. 

::: info
Currently ReSharper's tooling has issues with Razor Views inheriting Custom base classes - 
which can be resolved by installing the latest EAP or disabling its **ASP.NET Razor** support
:::

Overall we're ecstatic with the end-result, we retain our Controller-free development model whilst Razor under 
.NET Core executes noticeably quicker than ASP.NET and significantly faster on Linux vs using Mono.

## Page Based Routing

Another value-added feature of ServiceStack.Razor is support for Page Based Routing in [ASP.NET Core Razor](/netcore-razor) 
which lets you use a `_` prefix to declare a variable placeholder for dynamic routes defined solely by directory and file names.

With this feature we can use a `_id` directory name to declare an `id` variable place holder:

 - [/contacts/_id/edit.cshtml](https://github.com/NetCoreApps/Validation/blob/master/world/wwwroot/server-razor/contacts/_id/edit.cshtml)

This will let you navigate to the `edit.cshtml` page directly to edit a contact using the ideal "pretty url" we want:

 - [/contacts/1/edit](http://validation.web-app.io/server-razor/contacts/1/edit)

Placeholders can be on both directory or file names, e.g:

 - `/contacts/edit/_id.cshtml` -> **/contacts/edit/1**

Inside your Razor page you can fetch any populated placeholders from the `ViewBag`:

```csharp
var id = int.Parse(ViewBag.id);
var contact = Html.Exec(() => Gateway.Send(new GetContact { Id = id }).Result, out var error);
```

Which [/_id/edit.cshtml](https://github.com/NetCoreApps/Validation/blob/master/world/wwwroot/server-razor/contacts/_id/edit.cshtml) 
uses to call the `GetContact` Service using the [Service Gateway](/service-gateway).

::: info
`Html.Exec()` is a UX-friendly alternative to using `try/catch` boilerplate in Razor
:::

## Stand-alone Razor Views

Rendering stand-alone HTML Views from Razor Pages can use the `GetViewPage()` API for retrieving View Pages 
(e.g. under `~/Views`) and the `GetContentPage()` API for retrieving Content Pages (e.g. under `/wwwroot`). 

You can then use `RenderToHtmlAsync()` API to render the HTML output in a UTF-8 `ReadOnlyMemory<char>` which your Services can return directly 
for optimal efficiency, or if needed the rendered output can be converted to a `string` with `.ToString()`:

```csharp
public async Task<object> Any(MyRequest request)
{
    var razor = GetPlugin<RazorFormat>();
    var view = razor.GetViewPage("MyView");
    if (view == null)
        throw HttpError.NotFound("Razor view not found: " + "MyView");

    var ret = await razor.RenderToHtmlAsync(view, new MyModel { Name = "World" },
        layout:"_MyLayout"); //if Layout specified in `.cshtml` page it uses that
    return ret;
}
```

For even better efficiency the Razor View can render to the Response `OutputStream` directly with `WriteHtmlAsync()` to write the rendered UTF-8 bytes 
directly to the `OutputStream` instead of above where it converts it into a UTF-8 string before converting it back to UTF-8 bytes when ServiceStack
writes it to the response:

```csharp
public async Task Any(MyRequest request)
{
    var razor = GetPlugin<RazorFormat>();
    var view = razor.GetViewPage("MyView");
    if (view == null)
        throw HttpError.NotFound("Razor view not found: " + "MyView");

    await razor.WriteHtmlAsync(Response.OutputStream, view, 
        new MyModel { Name = "World" }, 
        layout:"_MyLayout"); //if Layout specified in `.cshtml` page it uses that
}
```

If needed you can also render the view with an anonymous Model Type, e.g:

```csharp
await razor.RenderToHtmlAsync(view, new { Name = "World" });
```

Where the Razor View would need to specify it's using a `dynamic` model with:

```html
@model dynamic
```

#### Limitation

One drawback of page based routing is that MVC is unable to resolve Page Based Routes when pre-compiled and will need to disabled with:

#### .NET Core 3+

```xml
<RazorCompileOnPublish>false</RazorCompileOnPublish>
```

#### .NET Core 2.x

```xml
<MvcRazorCompileOnPublish>false</MvcRazorCompileOnPublish>
```


# Razor UI Controls
Source: https://docs.servicestack.net/razor-ui-controls

The Razor UI Controls are utilized in new [Razor project templates](/templates/websites) and
the [World Validation](/world-validation#server-rendered-html-uis) Application.

### UI Component List

Currently the component libraries include common Bootstrap UI Form Controls and Navigation Components:

| Control                 | Description                                                                       |
|-------------------------|-----------------------------------------------------------------------------------|
| @Html.ValidationSummary | Show validation summary error message unless there's an error in specified fields |
| @Html.ValidationSuccess | Display a "Success Alert Box"                                                     |
| @Html.FormInput         | Display a `<input type="text"/>` UI Control                                       |
| @Html.FormTextarea      | Display a `<textarea/>` UI Control                                                |
| @Html.FormSelect        | Display a `<select/>` UI Control                                                  |
| @Html.FormInput         | Display a `<input type="checkbox"/>` UI Control                                   |
| @Html.HiddenInputs      | Emit HTML `<input type="hidden"/>` field for each specified Key/Value pair entry  |
| @Html.SvgImage          | Return `<svg/>` markup for the named image                                        |
| @Html.Nav               | Display a list of NavItem's                                                       |
| @Html.Navbar            | Display the `navbar` main menu                                                    |
| @Html.NavLink           | Display a `nav-link` nav-item                                                     |
| @Html.NavButtonGroup    | Display a list of NavItem's `btn-group`                                           |

### Bootstrap UI Form Controls

The Bootstrap UI form controls include built-in support for validation where they can render validation errors from ServiceStack's
`ResponseStatus` object, e.g the [Login Page](/world-validation#login-page) in World Validation:

```cs
<form action="/auth/credentials" method="post" class="col-lg-4">
    <div class="form-group">
        @Html.ValidationSummary(new[]{ "userName","password" }, 
            new { @class = "alert alert-warning" })
        
        @Html.HiddenInputs(new { 
            @continue = Html.Query("continue") ?? "/server-razor/",
            errorView = "/server-razor/login"
        })
    </div>
    <div class="form-group">
        @Html.FormInput(new { id = "userName" }, new InputOptions {
            Label = "Email",
            Help  = "Email you signed up with",
            Size  = "lg",
        })
    </div>
    <div class="form-group">
        @Html.FormInput(new { id = "password", type = "password" }, new InputOptions {
            Label = "Password",
            Help  = "6 characters or more",
            Size  = "lg",
            PreserveValue = false,
        })
    </div>
    <div class="form-group">
        @Html.FormInput(new { 
            id   = "rememberMe", 
            type = "checkbox",
            @checked = true,
        },
        new InputOptions { Label = "Remember Me" })
    </div>
    <div class="form-group">
        <button type="submit" class="btn btn-lg btn-primary">Login</button>
    </div>
    <div class="form-group">
        <a class="lnk" href="/server-razor/register">Register New User</a>
    </div>
</form>
```

## Login Page UI

The Login Page contains a standard Bootstrap Username/Password form with labels, placeholders and help text, which initially looks like:

![](https://raw.githubusercontent.com/ServiceStack/Assets/master/img/apps/Validation/login-validation.png)

What it looks like after submitting an empty form with Server Exception Errors rendered against their respective fields:

![](https://raw.githubusercontent.com/ServiceStack/Assets/master/img/apps/Validation/login-validation-failed.png)


### Form Control Properties

The **Razor** controls uses anonymous objects and camelCase properties for its unbounded HTML Element Attribute List 
for attributes you want to add to the underlying HTML `<input/>` Element and a Typed `InputOptions` Class to specify the controls other 
high-level features, typically like:

```cs
@Html.ControlName(new { /*htmlAttrs*/ }, new InputOptions { ... })
```

The typed `InputOptions` class supports the following features:

```csharp
/// High-level Input options for rendering HTML Input controls
public class InputOptions
{
    /// Display the Control inline 
    public bool Inline { get; set; }
    
    /// Label for the control
    public string Label { get; set; }
    
    /// Class for Label
    public string LabelClass { get; set; }
    
    /// Override the class on the error message (default: invalid-feedback)
    public string ErrorClass { get; set; }

    /// Small Help Text displayed with the control
    public string Help { get; set; }
    
    /// Bootstrap Size of the Control: sm, lg
    public string Size { get; set; }
    
    /// Multiple Value Data Source for Checkboxes, Radio boxes and Select Controls 
    public object Values { get; set; }

    /// Typed setter of Multi Input Values
    public IEnumerable<KeyValuePair<string, string>> InputValues
    {
        set => Values = value;
    }

    /// Whether to preserve value state after post back
    public bool PreserveValue { get; set; } = true;

    /// Whether to show Error Message associated with this control
    public bool ShowErrors { get; set; } = true;
}
```

### Contacts Page

The [Contacts Page](/world-validation#contacts-page) shows a more complete example with a number of different UI Controls. 

```cs
<form action="/contacts" method="post" class="col-lg-4">
    <div class="form-group">
        @Html.ValidationSummary(new[]{ "title","name","color","age","filmGenres","agree" })
        @Html.HiddenInputs(new { @continue = Continue, errorView = Continue })
    </div>
    <div class="form-group">
        @Html.FormInput(new { 
            id = "title", 
            type = "radio",
        }, new InputOptions { 
            Values = Html.ContactTitles(),
            Inline = true,
        })
    </div>
    <div class="form-group">
        @Html.FormInput(new { 
            id = "name", 
            placeholder = "Name", 
        }, new InputOptions {
            Label = "Full Name",
            Help  = "Your first and last name",
        })
    </div>
    <div class="form-group">
        @Html.FormSelect(new { 
            id = "color", 
            @class = "col-4", 
        }, new InputOptions {
            Label  = "Favorite color",
            Values = new StringDictionary { {"",""} }.Merge(Html.ContactColors()),
        })
    </div>
    <div class="form-group">
        @Html.FormInput(new { 
            id = "filmGenres", 
            type = "checkbox",
        }, new InputOptions { 
            Label  = "Favorite Film Genres",
            Help   = "choose one or more",
            Values = Html.ContactGenres()
        })
    </div>
    <div class="form-group">
        @Html.FormInput(new { 
            id = "age", 
            type = "number",
            min = 13,
            placeholder = "Age",
            @class = "col-3",
        })
    </div>
    <div class="form-group">
        @Html.FormInput(new {
            id   = "agree",
            type = "checkbox",
        },
        new InputOptions { Label = "Agree to terms and conditions" })
    </div>
    <div class="form-group">
        <button class="btn btn-primary" type="submit">Add Contact</button>
        <a href="/server-razor/contacts/">reset</a>
    </div>
</form>
```

Both Server UI Controls provide auto Validation Form Binding for any validation rules specified on the `CreateContact` Validator:

```csharp
public class CreateContactValidator : AbstractValidator<CreateContact>
{
    public CreateContactValidator()
    {
        RuleFor(r => r.Title).NotEqual(Title.Unspecified).WithMessage("Please choose a title");
        RuleFor(r => r.Name).NotEmpty();
        RuleFor(r => r.Color).Must(x => x.IsValidColor()).WithMessage("Must be a valid color");
        RuleFor(r => r.FilmGenres).NotEmpty().WithMessage("Please select at least 1 genre");
        RuleFor(r => r.Age).GreaterThan(13).WithMessage("Contacts must be older than 13");
        RuleFor(x => x.Agree).Equal(true).WithMessage("You must agree before submitting");
    }
}
```

As well as any `ArgumentException` thrown within the Service Implementation:

```csharp
public object Any(CreateContact request) 
{
    var newContact = request.ConvertTo<Data.Contact>();
    newContact.Id = Interlocked.Increment(ref Counter);
    newContact.UserAuthId = this.GetUserId();
    newContact.CreatedDate = newContact.ModifiedDate = DateTime.UtcNow;

    var contacts = Contacts.Values.ToList();
    var alreadyExists = contacts.Any(x => x.UserAuthId == newContact.UserAuthId && x.Name == request.Name);
    if (alreadyExists)
        throw new ArgumentException($"You already have contact named '{request.Name}'",nameof(request.Name));
    
    Contacts[newContact.Id] = newContact;
    return new CreateContactResponse { Result = newContact.ConvertTo<Contact>() };
}
```

## Contacts Page UI

The Contacts Page is representative of a more complex page that utilizes a variety of different form controls where the same page is also responsible for rendering the list of existing contacts:

![](https://raw.githubusercontent.com/ServiceStack/Assets/master/img/apps/Validation/contacts-validation.png)

Here's an example of what a partially submitted invalid form looks like:

![](https://raw.githubusercontent.com/ServiceStack/Assets/master/img/apps/Validation/contacts-validation-failed.png)

To view the complete implementation in context checkout [World Validation Server Implementation](/world-validation#server-implementation).

## Navigation Controls

The Server Navigation Controls are used to render your Apps [Unified Navigation](/navigation#navbar)
where you can use the `@Html.Navbar()` and `@Html.NavButtonGroup()` methods to render NavItems:

#### Navbar

You can render the **main menu** navigation using the 
[Navbar](https://github.com/NetCoreTemplates/razor/blob/e6b2bb82c81fc8fb07eff94e7afbdd42ded2569f/MyApp/Views/Shared/_Layout.cshtml#L52) HTML Helper:

```cs
@Html.Navbar()
```

Which by default renders the `View.NavItems` main navigation, using the default `NavOptions` and User Attributes (if authenticated): 

![](/img/pages/nav/appsettings.png)

You can also render a **different Navigation List** with:

```cs
@Html.Navbar(Html.GetNavItems("submenu"))
```

Which can be customized using the different `NavOptions` properties above, in camelCase:

```cs
@Html.Navbar(Html.GetNavItems("submenu"), new NavOptions {
    NavClass = "navbar-nav navbar-light bg-light" 
})
```

#### Button group

The `NavButtonGroup` HTML Helper can render NavItems in a button group, e.g. the
[OAuth buttons](https://github.com/NetCoreTemplates/razor/blob/ed70e0d9d858e6dc05a267dfc1cd281b70311589/MyApp/wwwroot/login.cshtml#L48-L51)
are rendered with:

```cs
@Html.NavButtonGroup(Html.GetNavItems("auth"), new NavOptions {
    NavClass = "",
    NavItemClass = "btn btn-block btn-lg",
})
```

Which renders a vertical, spaced list of buttons which look like:

![](/img/pages/nav/auth-navitems.png)


### Razor Pages

The same server controls are available in ServiceStack.Razor Apps as HTML Helper extension methods: 

#### Navbar

```csharp
@Html.Navbar()

@Html.Navbar(Html.GetNavItems("submenu"))

@Html.Navbar(Html.GetNavItems("submenu"), new NavOptions {
    NavClass = "navbar-nav navbar-light bg-light"
})
```

#### NavButtonGroup

```csharp
@Html.NavButtonGroup(Html.GetNavItems("auth"), new NavOptions {
    NavClass = "",
    NavItemClass = "btn btn-block btn-lg",
})
```

### NavOptions Properties

Each Nav UI Control can be further customized by overriding the properties on the typed `NavOptions` class: 

```csharp
public class NavOptions
{
    /// User Attributes for conditional rendering, e.g:
    ///  - auth - User is Authenticated
    ///  - role:name - User Role
    ///  - perm:name - User Permission 
    public HashSet<string> Attributes { get; set; }
    
    /// Path Info that should set as active 
    public string ActivePath { get; set; }
    
    /// Prefix to include before NavItem.Path (if any)
    public string BaseHref { get; set; }

    // Custom classes applied to different navigation elements (defaults to Bootstrap classes)
    public string NavClass { get; set; }
    public string NavItemClass { get; set; }
    public string NavLinkClass { get; set; }
    
    public string ChildNavItemClass { get; set; }
    public string ChildNavLinkClass { get; set; }
    public string ChildNavMenuClass { get; set; }
    public string ChildNavMenuItemClass { get; set; }
}
```


# Razor Notes
Source: https://docs.servicestack.net/razor-notes

## VS.NET Intelli-sense for self-hosting projects

VS.NET Intelli-sense relies on the `Web.config` that VS.NET looks for in the root directory of your host projects. As self-hosting projects are **Console Applications** they instead use `App.config` instead which is all ServiceStack looks at for configuring Razor. 

Unfortunately as VS.NET's Razor intelli-sense is coupled to ASP.NET MVC, it requires a dummy Web.config in your self-hosted projects which just contains a copy of the Razor configuration in your **App.config** (which was originally populated when adding the [ServiceStack.Razor](http://www.nuget.org/packages/ServiceStack.Razor) NuGet Package to your project). The Web.config is otherwise benign and has no other effect other than enabling VS.NET's intelli-sense.

### Intelli-sense for View Models

The `@model T` attribute isn't known to VS.NET intelli-sense when self-hosting which means you need to its more verbose alias:

```cs
@inherits ViewPage<T>
```

### Web Configuration for Razor

All ASP.NET Razor VS.NET Templates in [ServiceStackVS](https://github.com/ServiceStack/ServiceStackVS) uses the optimal `Web.config` template below `Web.config` for editing Razor pages without designer errors in VS.NET 2015: 

```xml
<configuration>
    <configSections>
        <sectionGroup name="system.web.webPages.razor" type="System.Web.WebPages.Razor.Configuration.RazorWebSectionGroup, System.Web.WebPages.Razor, Version=3.0.0.0, Culture=neutral, PublicKeyToken=31BF3856AD364E35">
            <section name="host" type="System.Web.WebPages.Razor.Configuration.HostSection, System.Web.WebPages.Razor, Version=3.0.0.0, Culture=neutral, PublicKeyToken=31BF3856AD364E35" requirePermission="false"/>
            <section name="pages" type="System.Web.WebPages.Razor.Configuration.RazorPagesSection, System.Web.WebPages.Razor, Version=3.0.0.0, Culture=neutral, PublicKeyToken=31BF3856AD364E35" requirePermission="false"/>
        </sectionGroup>
    </configSections>

    <appSettings>
        <add key="webPages:Enabled" value="false" />
    </appSettings>

    <system.web.webPages.razor>
        <host factoryType="System.Web.Mvc.MvcWebRazorHostFactory, System.Web.Mvc, Version=5.0.0.0, Culture=neutral, PublicKeyToken=31BF3856AD364E35"/>
        <pages pageBaseType="ServiceStack.Razor.ViewPage">
            <namespaces>
                <add namespace="System" />
                <add namespace="System.Linq" />
                <add namespace="ServiceStack" />
                <add namespace="ServiceStack.Html" />
                <add namespace="ServiceStack.Razor" />
                <add namespace="ServiceStack.Text" />
                <add namespace="ServiceStack.OrmLite" />
                <add namespace="ProjectNamespace" />
                <add namespace="ProjectNamespace.ServiceModel" />
            </namespaces>
        </pages>
    </system.web.webPages.razor>
</configuration>
```

The [ServiceStack.Razor](https://www.nuget.org/packages/ServiceStack.Razor) NuGet package uses the official 
[Microsoft.AspNet.Razor](https://www.nuget.org/packages/Microsoft.AspNet.Razor/) 
but to minimize errors in VS.NET's Razor editor, the ServiceStack' Razor templates also reference MVC's
[Microsoft.AspNet.WebPages](https://www.nuget.org/packages/Microsoft.AspNet.WebPages/) 
NuGet package which is only used to assist Razor intellisense as ServiceStack doesn't use or need itself.

To remove the last designer error **Content pages** can inherit:

```html
@inherits ViewPage
```

And Typed **View Pages** can inherit:

```html
@inherits ViewPage<TResponse>
```

Which also doesn't affect the pages behavior, but can remove the final design-time warning showing up in
VS.NET's error list.

#### Only configuration section used

ServiceStack doesn't use the ASP.NET WebPages implementation itself, the configuration is primarily included to enable VS.NET intelli-sense and provide a way to configure the default namespaces added to Razor pages. 

This can also be done in code by adding to the `Config.RazorNamespaces` collection, but adding them to the config section lets VS.NET knows about them so you can get proper intelli-sense.


# View &amp; Template Selection
Source: https://docs.servicestack.net/view-and-template-selection

ServiceStack provides multiple ways to select the Razor View that will be used to render your services response with. First if the `IHttpRequest.Items["View"]` has been set [via any Global, Request, Response or Action Filter](/order-of-operations) it will use that, otherwise the fallback convention is to use the view with the same name as the **Request DTO** followed finally by one with the **Response DTO** name.

To illustrate this, the below service is overloaded with different ways to select a Razor View, each are assigned a priority number starting from `#1`:

```csharp
[ClientCanSwapTemplates]        // #4 Client can select with ?view=UserSpecified4
[DefaultView("DevSpecified3")]  // #3 
public class RockstarsService : Service 
{
    [DefaultView("DevSpecified2")]        // #2 
    public object Get(Rockstars5 request) // #5
    {
        return new HttpResult(new RockstarsResponse6()) // #6
        {
            View = "DevSpecified1"  // #1
        }
    }
}
```

The above service selects views that are mapped to the below Razor views. The folder structure is inconsequential so Views can be organized and nested in any number of folders, e.g:

```
/Views
    /Any
        /Nested
            /Deep
                DevSpecified1.cshtml       // #1
                DevSpecified2.cshtml       // #2
                DevSpecified3.cshtml       // #3
                UserSpecified4.cshtml      // #4
                Rockstars5.cshtml          // #5
                RockstarsResponse6.cshtml  // #6
    /Shared
        _Layout.cshtml
```

The `DevSpecified1.cshtml` would be selected first because it is last to set the `IHttpRequest.Items["View"]` property that the Razor Format uses to select the view. You're also not limited to these options as you can easily set the same property in any of your own custom filters. 

E.g. this is the entire source code of the [ClientCanSwapTemplates Attribute](https://github.com/ServiceStack/ServiceStack/blob/master/src/ServiceStack.ServiceInterface/ClientCanSwapTemplatesAttribute.cs) which once enabled lets the client to specify the view via HTTP Header, QueryString, FormData or Cookies (in that order):

```csharp
public class ClientCanSwapTemplatesAttribute : ResponseFilterAttribute
{
    public override void Execute(IHttpRequest req, IHttpResponse res, object requestDto)
    {
        req.Items["View"] = req.GetParam("View");
        req.Items["Template"] = req.GetParam("Template");
    }
}
```

The last filter to set `req.Items["View"]` wins.

### Layout Templates

Although the above example only shows how to select the View (e.g. Page Body), the exact same rules applies to select the Layout template via the **Template** field also on the HttpResult and DefaultView attribute. If a template is not specified the default `/Shared/_Layout.cshtml` is used.

## Executing Razor in Code

The `RazorFormat` plugin provides several APIs which lets you access Razor views independently from ServiceStack, e.g:

```csharp
var razorFormat = HostContext.GetPlugin<RazorFormat>();
var razorView = razorFormat.GetViewPage("MyView"); //e.g. /Views/MyView.cshtml
var html = razorFormat.RenderToHtml(razorView, dto);
```

### Creating Pages at Runtime

For views that don't exist you can use the `CreatePage()` API to dynamically create a Razor View from a dynamic string at runtime that can be later reused to generate HTML for multiple models:

```csharp
var razorView = razorFormat.CreatePage("<h3>Hello @Model.name, the year is @DateTime.Now.Year</h3>");
var htmlFoo = razorFormat.RenderToHtml(razorView, new { name = "foo" });
var htmlBar = razorFormat.RenderToHtml(razorView, new { name = "bar" });
```

Or if you don't need to reuse the page again, it can be done in 1-line with:

```csharp
var html = razorFormat.CreateAndRenderToHtml("<h3>Hello @Model.name</h3>", model: new { name = "foo" });
```

## Debuggable Razor Views

Razor Views are now debuggable for 
[Debug builds](/debugging#debugmode) by default, it can also be explicitly specified on:

```csharp
Plugins.Add(new RazorFormat {
    IncludeDebugInformation = true,
    CompileFilter = compileParams => ...
})
```

The `CompileFilter` is an advanced option that lets modify the `CompilerParameters` used by the C# CodeDom provider to compile the Razor Views if needed.


# Compiled Razor Views
Source: https://docs.servicestack.net/compiled-razor-views

The primary benefits of compiled views is improved performance by eliminating compile times of Razor views. They can also provide static compilation benefits by highlighting compile errors during development and can simplify deployment by avoiding the need to deploy any `*.cshtml` files as they end up pre-compiled in the containing Assembly.

### Install ServiceStack.Razor.BuildTask

To enable compiled razor views you need to add the [ServiceStack.Razor.BuildTask](https://www.nuget.org/packages/ServiceStack.Razor.BuildTask) NuGet Package to the project containing your Razor `*.cshtml` pages, i.e:

:::copy
`<PackageReference Include="ServiceStack.Razor.BuildTask" Version="5.*" />`
:::

This doesn't add any additional dlls to your project, instead it just sets the **BuildAction** to all `*.cshtml` pages to **Content** and registers an MSBuild task to your `.csproj` project file set to pre-compile razor views on every build.

### Register Compiled Assembly to RazorFormat Plugin

To register assemblies containing compiled razor views with Razor Format you just need to add it to RazorFormat.LoadFromAssemblies, e.g:

```csharp
Plugins.Add(new RazorFormat {
    LoadFromAssemblies = { typeof(RockstarsService).Assembly }
});
```

### Retains optimal development workflow

The Compiled Views support continues to retain a great development experience in [DebugMode](/debugging#debugmode) as all Razor Views are initially loaded from the Assembly but also continues to monitor the file system for modified views, automatically compiling and loading them on the fly so AppDomain reloads aren't required to see changes.

## Example Projects

### [Razor Rockstars](https://github.com/ServiceStackApps/RazorRockstars)

The [RazorRockstars.CompiledViews](https://github.com/ServiceStackApps/RazorRockstars/tree/master/src/RazorRockstars.CompiledViews) VS.NET project shows an example of [Razor Rockstars](https://razor.netcore.io/) which uses shared compiled Razor Views in a `.dll` in a number of different projects:

  - [WPF Host](https://github.com/ServiceStackApps/RazorRockstars/tree/master/src/RazorRockstars.CompiledViews.WpfHost)
  - [HttpListener SelfHost](https://github.com/ServiceStackApps/RazorRockstars/tree/master/src/RazorRockstars.CompiledViews.SelfHost)
  - [ASP.NET WebHost](https://github.com/ServiceStackApps/RazorRockstars/tree/master/src/RazorRockstars.CompiledViews.WebHost)

### [ServiceStack.Gap](https://github.com/ServiceStack/ServiceStack.Gap)

The [ServiceStack.Gap](https://github.com/ServiceStack/ServiceStack.Gap) project shows how to extend Compiled Razor Views and use them to create embedded ServiceStack solutions that can be ILMerged down to a single `.exe`.


# Razor Views vs Content Pages
Source: https://docs.servicestack.net/razor-views-vs-content-pages

In [ServiceStack][1]: 

  - Razor Pages that exist within the `/Views/` folder are called **View Pages**
  - Razor Pages that exist anywhere else are called **Content Pages**

The difference between them is that **View Pages** are Razor views that are used to provide the HTML representations (aka views) **for services** in much the same way View Pages work for MVC Controllers.

View Pages **cannot** be called directly, that's the role of **Content Pages**, which **can only** be called directly, i.e. outside the context of a service (or redirected to, from a service).

In [Razor Rockstars][2], examples of Content Pages include:

  - [/stars/dead/cobain/][3] which calls the [/stars/dead/Cobain/default.cshtml][4] Content Page
  - [/TypedModelNoController][5] which calls the [/TypedModelNoController.cshtml][6] Content Page

Whereas examples of **View Pages** include:

  - [/rockstars][7] which matches the `/rockstars` route on the [/RockstarsService.cs][8] and because of the `[DefaultView("Rockstars")]` attribute, uses the [/Rockstars.cshtml][9] **View Page**

## Default Pages

For **Content Pages** the `default.cshtml` is the index page for a folder. So to set a default page for the root `/` path, create a `/default.cshtml` page. An example of this is [/default.cshtml][10] home page used in the [Reusability][11] demo.

If you want to use a view page as the Home page, you can set the default redirect to it by adding the AppHost config:

```csharp
SetConfig(new HostConfig { 
    DefaultRedirectPath = "~/home"
});
```

Which would call a **service** matching the `/home` route that will use the most appropriate View Page based on the rules laid out in the [Razor Rockstars][12] page.


  [1]: http://www.servicestack.net/
  [2]: https://razor.netcore.io/
  [3]: https://razor.netcore.io/stars/dead/cobain/
  [4]: https://github.com/ServiceStack/RazorRockstars/blob/master/src/RazorRockstars.WebHost/stars/dead/Cobain/default.cshtml
  [5]: https://razor.netcore.io/TypedModelNoController
  [6]: https://github.com/ServiceStack/RazorRockstars/blob/master/src/RazorRockstars.WebHost/TypedModelNoController.cshtml
  [7]: https://razor.netcore.io/rockstars
  [8]: https://github.com/ServiceStack/RazorRockstars/blob/master/src/RazorRockstars.WebHost/RockstarsService.cs
  [9]: https://github.com/ServiceStack/RazorRockstars/blob/master/src/RazorRockstars.WebHost/Views/Rockstars.cshtml
  [10]: https://github.com/ServiceStack/ServiceStack.UseCases/blob/master/Reusability/default.cshtml
  [11]: https://github.com/ServiceStack/ServiceStack.UseCases/tree/master/Reusability
  [12]: https://razor.netcore.io/


# Vue Components
Source: https://docs.servicestack.net/vue-components

A collection of Vue and Vuetify Components you might find useful for use in your own Apps:

## Vuetify Markdown Editor

To make contributing ServiceStack Community content as pleasant as possible we've developed a custom Markdown Editor that enhances a Vuetify Text Input component with editing features optimal for authoring Markdown of developer content.

[@servicestack/editor](https://github.com/ServiceStack/servicestack-editor) is a developer-friendly Markdown Editor for Vuetify Apps which is optimized for [GitHub Flavored Markdown](https://guides.github.com/features/mastering-markdown/) where it supports popular IDE short-cuts for authoring code like tab un/indenting, single-line code and comments blocks, etc. 

[![](https://i.imgur.com/YPlfplv.png)](https://github.com/ServiceStack/servicestack-editor)

For wrist-friendly productivity the Editor supports many of the popular Keyboard shortcuts found in popular IDEs:

![](https://i.imgur.com/PXqkSuN.png)

It's ideal for use in Apps that need to accept rich Content and can be installed with:

```bash
$ npm install @servicestack/editor
```

Where it's used like a regular Vue or Vuetify component:

```html
<template>
  <Editor v-model="content" label="Markdown" />
</template>

<script>
import Editor from "@servicestack/editor";

export default {
  components: { Editor },
}
</script>
```

See the Project Page for [documented Example Usage](https://github.com/ServiceStack/servicestack-editor/blob/master/README.md#example-usage) of its features and how to make use of it within an existing component.

## Beautiful, free Hero Backgrounds

[@servicestack/images](https://github.com/ServiceStack/images) is a growing hand-picked curated collection of beautiful free images from [unsplash.com](https://unsplash.com) that's an easy drop-in to any Website, with backgrounds being served from GitHub's CDN.

[heroes.js](https://github.com/ServiceStack/img/pages/blob/master/heroes.js) is a dependency-free script that returns different URLs to **2560x1000** [/hero](https://github.com/ServiceStack/img/pages/tree/master/hero) images ideal for usage in hero backgrounds.

It includes a number of different API's to control which hero to get and for how long to return the same hero for:

```
heroes.random()          // a random hero each time
heroes.daily()           // the same hero for the day
heroes.hourly()          // the same hero for the hour
heroes.static('foo')     // the same hero for this string constant
heroes.static('foo',10)  // the same hero + 10 for this string constant
heroes.get(1)            // the first hero
heroes.get(1000000)      // the hero at mod length 1000000

heroes.images            // the array of hero image names
heroes.baseUrl           //= https://servicestack.github.io/img/pages/ 
```

Live Example: [/heroes](https://servicestack.github.io/img/pages/heroes)

It's used in all TechStacks pages containing background hero images where it's embedded inside a [Vuetify Parallax Component](https://vuetifyjs.com/en/components/parallax) where it provides a subtle parallax effect. This example shows the same hero image for each Technology based on its `slug`:

```html
<template>
  <v-parallax :src="heroUrl">
</template>

<script>
  import { heroes } from "@servicestack/images";
  export default {
    heroUrl() { 
      return heroes.static(this.slug); 
    },
  }
</script>
```

The [Usage](https://github.com/ServiceStack/img/pages/blob/master/README.md#usage) section on the project page contains additional examples showing how to use it within a static web page, a npm-based Web App using ES6/TypeScript as well as inside a React or Vue Component.

### Image Upload Vue Component

The [FileInput.vue](https://github.com/NetCoreApps/TechStacks/blob/master/src/TechStacks/src/components/FileInput.vue) is a simple single File Upload Component with an image preview. 

The basic usage example below shows an example of using it to upload files with the `JsonServiceClient` where instead of sending a Request DTO, use `toFormData` to create a "multipart/form-data" `FormData` request that can be sent using the `postBody` API, e.g:

```html
<template>
  <file-input :value="logoUrl" accept="image/*" @input="onFileChange" selectLabel="Add Logo"></file-input>
</template>

<script>

import { JsonServiceClient, toFormData } from "@servicestack/client";

export default {
  components: { FileInput },

  onFileChange(imgFile) {
    const fields = { id: 1, name: 'foo' };
    const body = toFormData({...fields, imgFile });
    await client.postBody(new CreateTechnology(), body);
  }
}
</script>
```

Inside your ServiceStack Service the uploaded file will be accessible from `IRequest.Files` collection with any additional arguments used to populate the Request DTO. 

You could use `VirtualFiles.WriteFile(path, Request.Files[0].InputStream)` to write the file to the configured [Virtual File System provider](/virtual-file-system), but as we want to keep the App Server stateless we're instead uploading it to Imgur and just saving the URL on Imgur:

```csharp
public object Post(CreateTechnology request)
{
    //...
    if (Request.Files.Length > 0)
    {
        tech.LogoUrl = Request.Files[0].UploadToImgur(AppSettings.GetString("oauth.imgur.ClientId"),
            nameof(tech.LogoUrl), minWidth:100, minHeight:50, maxWidth:2000, maxHeight:1000);
    }
}
```

If you'd also like to upload to Imgur you can copy the `UploadToImgur` extension in [ImgurExtensions.cs](https://github.com/NetCoreApps/TechStacks/blob/master/src/TechStacks.ServiceInterface/ImgurExtensions.cs) into your project which includes image size validation as well as extracting any Imgur error responses into a readable C# Exception so it displays the cause of any downstream Imgur Upload Error in your UI.


# Embedded UMD @servicestack/client
Source: https://docs.servicestack.net/servicestack-client-umd

A UMD version of the [@servicestack/client](https://github.com/ServiceStack/servicestack-client) JavaScript client library 
that contains the [TypeScript Service and SSE Clients](/typescript-add-servicestack-reference) is now embedded in **ServiceStack.dll**.
It's the modern, dependency-free replacement to [ss-utils.js](/ss-utils-js) which requires jQuery which is used instead in all
SPA Project Templates.

The embedded UMD version allows for the creation of stand-alone pages that accesses your ServiceStack JSON APIs 
without any external file references with the single `<script/>` reference:

```html
<script src="/js/servicestack-client.js"></script>
```

This is used by the updated [mix init](/mix-tool#mix-usage) gists when generating its empty Web Apps:

```bash
mkdir web && cd web
x mix init
dotnet run
```

Where its dep-free [/index.html](https://gist.github.com/gistlyn/58030e271595520d87873c5df5e4c2eb#file-wwwroot-index-html) use its
`JsonServiceClient` to call its **/hello** API:

```html
<script src="/js/require.js"></script>
<script src="/js/servicestack-client.js"></script>
<script src="/types/js"></script>
<script>
var { JsonServiceClient, Hello } = exports

var client = new JsonServiceClient();
function callHello(name) {
    client.get(new Hello({ name }))
        .then(function(r) {
            document.getElementById('result').innerHTML = r.result;
        });
}
</script>
```

Which utilizes the [JavaScript Add ServiceStack Reference](/javascript-add-servicestack-reference) **/types/js** to instantly generate JavaScript Types for all your APIs DTOs which can immediately be used with the [TypeScript JsonServiceClient](/typescript-add-servicestack-reference#typescript-serviceclient) to make Typed API requests.

That modern browsers (as well as any TypeScript or Webpack project) let you use the much nicer async/await syntax:

```js
let r = await client.get(new Hello({ name: val }))
```

### Rich intelli-sense support

Even pure HTML/JS Apps that don't use TypeScript or any external dependencies will still benefit from the Server 
generated `dtos.ts` and `servicestack-client.d.ts` definitions as Smart IDEs like 
[Rider](https://www.jetbrains.com/rider/) can make use of them to provide a rich productive development UX
on both the built-in `/js/servicestack-client.js` library:

![](/img/pages/mix/init-rider-ts-client.png)

As well as your App's server generated DTOs:

![](/img/pages/mix/init-rider-ts-dto.png)

Including their typed partial constructors:

![](/img/pages/mix/init-rider-ts-dto-props.png)

So even simple Apps without complex bundling solutions or external dependencies can still benefit from a rich typed authoring 
experience without any additional build time or tooling complexity.

### CDN unpkg

A CDN hosted version of UMD @servicestack/client is available on unpkg.com:

```html
<script src="https://unpkg.com/@servicestack/client/dist/servicestack-client.min.js"></script>
```

TypeScript Definition: [index.d.ts](https://unpkg.com/@servicestack/client/dist/index.d.ts)

## Bootstrap Forms

ServiceStack's built-in [Fluent Validation](/validation) and [error handling](/error-handling) support works with Bootstrap's standard HTML Form markup, e.g:

```html
<form id="form-addcontact" action="@(new CreateContact().ToPostUrl())" method="POST">
    <div class="col-sm-3 form-group">
        <label for="Name">Name</label>
        <input class="form-control input-sm" type="text" id="Name" name="Name" value="">
        <span class="help-block"></span>
    </div>
    ...
</form>
```

The first thing to notice is the **action** url is created with a typed API populated using the [Reverse Routing](/routing#reverse-routing) `ToPostUrl()` extension method that looks at `CreateContact` Request DTO to return the best matching route based on the Route definitions and the fields populated in the Request DTO instance, in this case the empty Request DTO matches `[Route("/contacts", "POST")]` so returns `/contacts`.

Other significant parts in this HTML Form is that the **INPUT** field names match up with the Request DTO it posts to and that it includes Bootstraps **class="help-block"** placeholders adjacent to each INPUT element which is what's used to bind the field validation errors.

## Binding HTML Forms

You can ajaxify a HTML FORM by using `bootstrapForm`, e.g:

```js
let $ = sel => document.querySelector(sel);

bootstrapForm($("#form-addcontact"), {
    success: function (contact) {
        addContacts([contact]);
        $("#form-addcontact input").value = '';
    }
});
```

This takes over the handling of this FORM and instead of doing a POST back of the entire page to the server, makes an Ajax request using all the fields in the FORM to POST the data to the **CreateContact** Service:

```csharp
public Contact Post(CreateContact request)
{
    var contact = request.ConvertTo<Contact>();
    Db.Save(contact);
    return contact;
}
```

## Fluent Validation

Normally the Service implementation will be called as-is but as we've added the FluentValidation `ValidationFeature` plugin and there exists a validator for `CreateContact` below:

```csharp
public class ContactsValidator : AbstractValidator<CreateContact>
{
    public ContactsValidator()
    {
        RuleFor(x => x.Name).NotEmpty().WithMessage("A Name is what's needed.");
        RuleFor(x => x.Email).NotEmpty().EmailAddress();
        RuleFor(x => x.Age).GreaterThan(0);
    }
}
```

The Request DTO is first validated with the above declarative rules and if it fails returns a structured error response which is used to bind the validation errors to all the invalid field **class=help-block** (or **help-inline**) placeholders:

![HTML Validation](https://raw.github.com/ServiceStack/EmailContacts/master/src/EmailContacts/Content/html-validation.png)

Whilst the user goes back and corrects their INPUT, we can provide instant feedback and clear the errors as they update each each field with:

```js
clearErrors($("#form-addcontact"));
```

### Manual Error Handling

The `validate` callback can be used to add client side validation logic which can manually set client-side validation errors using `applyErrors()` with a `ResponseStatus` errors collection, e.g:

```js
bootstrapForm($("form"), {
    validate: function(){
        var params = serializeForm(this);
        if (params.Password != params.Confirm) {
            applyErrors(this, {
                errors: [{
                    fieldName: 'Password',
                    message: 'Passwords to not match'
                }]
            })
            return false;
        }
    }
});
```

## Declarative Events

An interesting difference in the dynamically generated HTML are the presence of **data-click=showContact** and **data-click=deleteContact** attributes:

```js
function addContacts(contacts) {
    var html = contacts.map(function (c) {
        return `<li data-id='${c.id}' data-click='showContact'>
                    ${c.name} (${c.age})
                    <span data-click="deleteContact"></span>
                </li>`;
    });
    $("#contacts").insertAdjacentHTML('beforeend', html.join(''));
}
```

This showcases some of the declarative event support allows you to invoke event handlers without needing to maintain bookkeeping of event handlers when adding or removing elements. 
You can instead define one set of event handlers for the entire page with `bindHandlers`, e.g:

### bindHandlers

```js
bindHandlers({
    showContact: function() {
        let id = this.getAttribute("data-id");
        client.get(new GetContact({ id: id }))
            .then(function(r) {
                showContact(r);
            });
    },
    deleteContact: function () {
        var id = this.closest("li").getAttribute("data-id");
        client.delete(new DeleteContact({ id: id }));
    }
});
```

The matching event handler will be invoked whenever an element with **data-{event}={handlerName}** is clicked, e.g: `data-click='showContact'`.
 
In addition to **click**, a number of other DOM events can be declared in this way, as defined in:

```js
['click','dblclick','change','focus','blur','focusin','focusout',
 'select','keydown','keypress','keyup','hover','toggle','input']
```

Or you can specify your own in `bindHandlers` options param, e.g:

```js
bindHandlers({
    showTooltip: function() {}
}, document, { events: ['mouseover'] })
```

### Multiple Arguments

Declarative event handlers can also send multiple arguments:

```html
<ul>
    <li data-click="single">Foo</li>
    <li data-click="multiple:arg1,arg2">Bar</li>
</ul>
```

```js
bindHandlers({
    single: function(){
        var li = this;
    },
    multiple: function(arg1, arg2) {
        var li = this;
    }
});
```

## Advanced bindForm usages

### Form Loading

Whilst a FORM is being processed all its buttons with `[type=submit]` are disabled and a **loading** class is added 
whilst a response from the server is pending. 
This can be used to provide UX feedback to end users with just CSS. E.g. we use `.loading` CSS rule to show the rotating glyphicon:

```css
#email-contact .loading .rotate {
    visibility: visible;
}
```

### Server initiated actions

Some useful functionality not demonstrated in this example is your Services ability to invoke client behavior by returning a response decorated with custom HTTP Headers. 
An example is being able to return "Soft Redirects" to navigate to a different page by adding a **X-Location** HTTP Header, e.g:

```csharp
return new HttpResult(response) {
    Headers = {
        { "X-Location", newLocationUri },
    }
};
```

When returned to a ajax form, it will instruct the page to automatically redirect to the new url.

You can also trigger an event on the page by returning a **X-Trigger** header, e.g:

```csharp
return new HttpResult(response) {
    Headers = {
        { "X-Trigger", "showLoginPopup" },
    }
};
```

In this case the page event handler named **showLoginPopup** will be invoked if it exists.

Alternatively you can use the shorter typed aliases for the above examples:

```csharp
return HttpResult.SoftRedirect(new ViewContact { Id = newContact.Id }.ToGetUrl(), newContact);
return HttpResult.TriggerEvent(contact, eventName:"showLoginPopup");
```

### ajaxSubmit

The `ajaxSubmit` function is available to submit a HTML form via Ajax on demand. 

```js
class Connections extends React.Component {

    onSubmit = (e) => {
        e.preventDefault();

        var $this = this;
        ajaxSubmit(e.target, {
            onSubmitDisable: $("#btnConnect"),
            success: function () {
                $this.setState({ successMessage: "Connection was changed" });
            }
        });
    }

    render() {
        var conn = this.state.connection;
        return (
          <div id="connections-page">
            <div className="content">
                <form className="form-inline" onSubmit={this.onSubmit} action="/connection">
                    <h2>Redis Connection</h2>
                    <div className="form-group">
                        <input name="host" type="text" />
                        <input name="port" type="text" className="form-control" />
                        <input name="db" type="text" className="form-control" />
                    </div>
                    <p className="actions">
                        <img className="loader" src="/img/ajax-loader.gif" />
                        <button id="btnConnect" className="btn btn-default btn-primary">
                            Change Connection
                        </button>
                    </p>
                    <p className="bg-success">{this.state.successMessage}</p>
                    <p className="bg-danger error-summary"></p>
                </form>
            </div>
          </div>
        );
    }
} 
``` 

### parseResponseStatus

Lets you easily parse the raw text of a Ajax Error Response into a responseStatus JavaScript object: 

```js
let status = parseResponseStatus(json, defaultErrorMessage);
```

### combinePaths and createUrl

The `combinePaths` and `createUrl` API's help with constructing urls, e.g:

```js
combinePaths("path","to","..","join")   //= path/join
createPath("path/{foo}", {foo:1,bar:2}) //= path/1
createUrl("http://host/path/{foo}",{foo:1,bar:2}) //= http://host/path/1?bar=2
```

#### Angular HTTP Client

You can use `createUrl()` to utilize Angular's built-in Rx-enabled HTTP Client with ServiceStack’s ambient TypeScript declarations when utilizing Angular's built-in dependencies is preferable, e.g:

```ts
import { createUrl } from '@servicestack/client';
...
this.http.get<HelloResponse>(createUrl('/hello/{Name}', { name })).subscribe(r => {
    this.result = r.result;
});
```

## TypeScript Definition

The TypeScript definitions for `@servicestack/client` is available at [/dist/index.d.ts](https://github.com/ServiceStack/servicestack-client/blob/master/dist/index.d.ts) lets you view all available utility functions in TypeScript method signatures, the full implementation of which is available from [/src/index.ts](https://github.com/ServiceStack/servicestack-client/blob/master/src/index.ts):

```ts
function isFormData(body: any): boolean;
function toCamelCase(s: string): string;
function toPascalCase(s: string): string;
function sanitize(status: any): any;
function nameOf(o: any): any;
function css(selector: string | NodeListOf<Element>, name: string, value: string): void;
function splitOnFirst(s: string, c: string): string[];
function splitOnLast(s: string, c: string): string[];
function leftPart(strVal: string, needle: string): string;
function rightPart(strVal: string, needle: string): string;
function lastLeftPart(strVal: string, needle: string): string;
function lastRightPart(strVal: string, needle: string): string;
function onlyProps(obj: {
    [index: string]: any;
}, keys: string[]): {
    [index: string]: any;
};
function humanize(s: any): any;
function queryString(url: string): any;
function combinePaths(...paths: string[]): string;
function createPath(route: string, args: any): string;
function createUrl(route: string, args: any): string;
function appendQueryString(url: string, args: any): string;
function bytesToBase64(aBytes: Uint8Array): string;
function stripQuotes(s: string): string;
function tryDecode(s: string): string;
function parseCookie(setCookie: string): Cookie;
function normalizeKey(key: string): string;
function normalize(dto: any, deep?: boolean): any;
function getField(o: any, name: string): any;
function parseResponseStatus(json: string, defaultMsg?: any): any;
function toFormData(o: any): FormData;
function toObject(keys: any): {};
function errorResponseSummary(): any;
function errorResponseExcept(fieldNames: string[] | string): any;
function errorResponse(fieldName: string): any;
function toDate(s: string | any): Date;
function toDateFmt(s: string): string;
function padInt(n: number): string | number;
function dateFmt(d?: Date): string;
function dateFmtHM(d?: Date): string;
function timeFmt12(d?: Date): string;
function toLocalISOString(d?: Date): string;
function createElement(tagName: string, options?: ICreateElementOptions, attrs?: any): HTMLElement;
function bootstrap(el?: Element): void;
function bindHandlers(handlers: any, el?: Document | Element, opt?: IBindHandlersOptions): void;
function bootstrapForm(form: HTMLFormElement | null, options: IAjaxFormOptions): void;
function toVarNames(names: string[] | string | null): string[];
function formSubmit(this: HTMLFormElement, options?: IAjaxFormOptions): Promise<any>;
function ajaxSubmit(f: HTMLFormElement, options?: IAjaxFormOptions): any;
function serializeForm(form: HTMLFormElement, contentType?: string | null): string | FormData;
function serializeToObject(form: HTMLFormElement): any;
function serializeToUrlEncoded(form: HTMLFormElement): string;
function serializeToFormData(form: HTMLFormElement): FormData;
function triggerEvent(el: Element, name: string, data?: any): void;
function populateForm(form: HTMLFormElement, model: any): void;
function trimEnd(s: string, c: string): string;
function safeVarName(s: string): string;
function pick(o: any, keys: string[]): {};
function omit(o: any, keys: string[]): {};
function activeClassNav(x: NavItem, activePath: string): string;
function activeClass(href: string | null, activePath: string, exact?: boolean): string;
function btnColorClass(props: any): string;
function btnSizeClass(props: any): string;
function btnClasses(props: any): any[];
function classNames(...args: any[]): string;
function fromXsdDuration(xsd: string): number;
function toXsdDuration(time: number): string;
function toTimeSpanFmt(time: number): string;
```


# ss-utils.js JavaScript Client Library
Source: https://docs.servicestack.net/ss-utils-js

jQuery Apps can take advantage of utils in `ss-utils.js` for easy integration with ServiceStack Services.

An Embedded Resource inside **ServiceStack.dll** is ServiceStack's JavaScript utility library that provides a number of convenience utilities in developing javascript web apps. It enables nicer integration with ServiceStack's Server features including [Validation](/validation), [Error Handling](/error-handling) and [Server Events](https://github.com/ServiceStackApps/Chat#server-sent-events) which can be included in any page with:

```html
<script type="text/javascript" src="/js/ss-utils.js"></script>
```

### DefinitelyTyped and npm

To make it easier to develop with **ss-utils** in any of the npm-based Single Page Apps templates we're also
maintaining a copy of [ss-utils in npm](https://www.npmjs.com/package/ss-utils) and have also added it to JSPM 
and DefinitelyTyped registry so you can now add it to your project like any other external dependency using JSPM:

:::sh
jspm install ss-utils
:::

If you're using TypeScript, you can also download the accompanying TypeScript definition from:

:::sh
typings install ss-utils --ambient --save
:::
    
Or if you're using the older tsd package manager: `tsd install ss-utils --save`.

## Usage

To showcase how it simplifies general web development, we'll walkthrough the JavaScript needed to provide all the behavior for the [entire UI of Email Contacts](https://github.com/ServiceStack/EmailContacts/blob/master/src/EmailContacts/default.cshtml) that uses just jQuery and bootstrap.js:

## Bootstrap Forms

ss-utils.js validation and error handling support works with Bootstrap's standard HTML Form markup, e.g:

```html
<form id="form-addcontact" action="@(new CreateContact().ToPostUrl())" method="POST">
    <div class="col-sm-3 form-group">
        <label for="Name">Name</label>
        <input class="form-control input-sm" type="text" id="Name" name="Name" value="">
        <span class="help-block"></span>
    </div>
    ...
</form>
```

The first thing to notice is the **action** url is created with a typed API populated using the [Reverse Routing](/routing#reverse-routing) `ToPostUrl()` extension method that looks at `CreateContact` Request DTO to return the best matching route based on the Route definitions and the fields populated in the Request DTO instance, in this case the empty Request DTO matches `[Route("/contacts", "POST")]` so returns `/contacts`.

Other significant parts in this HTML Form is that the **INPUT** field names match up with the Request DTO it posts to and that it includes Bootstraps **class="help-block"** placeholders adjacent to each INPUT element which is what **ss-utils.js** uses to bind the field validation errors.

## Binding HTML Forms

You can ajaxify a HTML FORM by using ss-utils `bindForm` jQuery mixin, e.g:

```js
$("#form-addcontact").bindForm({
    success: function (contact) {
        addContacts([contact]);
        $("#form-addcontact input").val('')
            .first().focus();
    }
});
```

This takes over the handling of this FORM and instead of doing a POST back of the entire page to the server, makes an Ajax request using all the fields in the FORM to POST the data to the **CreateContact** Service:

```csharp
public Contact Post(CreateContact request)
{
    var contact = request.ConvertTo<Contact>();
    Db.Save(contact);
    return contact;
}
```

## Fluent Validation

Normally the Service implementation will be called as-is but as we've added the FluentValidation `ValidationFeature` plugin and there exists a validator for `CreateContact` below:

```csharp
public class ContactsValidator : AbstractValidator<CreateContact>
{
    public ContactsValidator()
    {
        RuleFor(x => x.Name).NotEmpty().WithMessage("A Name is what's needed.");
        RuleFor(x => x.Email).NotEmpty().EmailAddress();
        RuleFor(x => x.Age).GreaterThan(0);
    }
}
```

The Request DTO is first validated with the above declarative rules and if it fails returns a structured error response which ss-utils uses to bind the validation errors to all the invalid field **class=help-block** (or **help-inline**) placeholders:

![HTML Validation](https://raw.github.com/ServiceStack/EmailContacts/master/src/EmailContacts/Content/html-validation.png)

Whilst the user goes back and corrects their INPUT, we can provide instant feedback and clear the errors as they update each each field with:

```js
$("input").change($.ss.clearAdjacentError);
```

Once all is successful we invoke the `success:` callback with the response of the Service which in this case is the newly created `Contact` that we dynamically add to the contacts list by calling the existing `addContacts()` method. We also clear all form values and put focus back to the first field, ready for a rapid entry of the next Contact:

```js
$("#form-addcontact").bindForm({
    success: function (contact) {
        addContacts([contact]);
        $("#form-addcontact input").val('')
            .first().focus();
    }
});
```

### Manual Error Handling

The `validate` callback can be used to add client side validation logic which can manually set client-side validation errors using `setFieldError()`, e.g:

```javascript
$("form").bindForm({
    validate: function(){
        var params = $(this).serializeMap();
        if (params.Password != params.Confirm) {
            $(this).setFieldError('Password', 'Passwords to not match');
            return false;
        }
    }
});
```

## Declarative Events

An interesting difference in the dynamically generated HTML are the presence of **data-click=showContact** and **data-click=deleteContact** attributes:

```js
function addContacts(contacts) {
    var html = contacts.map(function (c) {
        return "<li data-id='" + c.Id + "' data-click='showContact'>" +
                "<span class='glyphicon glyphicon-user' style='margin: 0 5px 0 0'></span>" +
                c.Name + " " + " (" + c.Age + ")" +
                '<span class="glyphicon glyphicon-remove-circle" data-click="deleteContact"></span>'
             + "</li>";
    });
    $("#contacts").append(html.join(''));
}
```

This showcases some of the declarative event support in ss-utils which allows you to invoke event handlers without needing to maintain bookkeeping of event handlers when adding or removing elements. 
You can instead define one set of event handlers for the entire page with `bindHandlers`, e.g:

```js
$(document).bindHandlers({
    showContact: function() {
        var id = $(this).data("id");
        $.getJSON("/contacts/" + id, function (contact) {
            $("#email-contact")
                .applyValues(contact)
                .show();
            $("#form-emailcontact .alert-success").hide();
        });
    },
    deleteContact: function () {
        var $li = $(this).closest("li");
        $.post("/contacts/" + $li.data("id") + "/delete", function () {
            $li.remove();
        });
    },
    toggleAction: function() {
        var $form = $(this).closest("form"), action = $form.attr("action");
        $form.attr("action", $form.data("action-alt"))
                .data("action-alt", action);
    }
});
```

The matching event handler will be invoked whenever an element with **data-{event}={handlerName}** is clicked, e.g: `data-click='showContact'`.
 
In addition to **click**, a number of other jQuery events can be declared in this way, as defined in:

```js
$.ss.listenOn = 'click dblclick change focus blur focusin focusout select keydown keypress keyup hover toggle';
```

### Multiple Arguments

Declarative event handlers can also send multiple arguments:

```html
<ul>
    <li data-click="single">Foo</li>
    <li data-click="multiple:arg1,arg2">Bar</li>
</ul>
```

```javascript
$(document).bindHandlers({
    single: function(){
        var li = this;
    },
    multiple: function(arg1, arg2) {
        var li = this;
    }
});
```

## Data Binding

Diving into the implementation of **showContact** we see ss-utils `applyValues()` jQuery mixin which binds a JS object to the target element, in this case **#email-contact**:

```js
showContact: function() {
    var id = $(this).data("id");
    $.getJSON("/contacts/" + id, function (contact) {
        $("#email-contact")
            .applyValues(contact)
            .show();
        $("#form-emailcontact .alert-success").hide();
    });
},
```

The data-binding applied by `applyValues()` include:

  - Set the **value** of all elements with matching **id={field}** or **name={field}**
  - Set the **value** of all elements marked with **data-val={field}**
  - Set the innerHTML contents of all elements marked with **data-html={field}**
  - Set the `data-href` and `data-src` attributes

#### Example Usage 

```javascript
$("#email-contact").applyValues(contact);
```

Which binds the returned **contact** response object to the **#email-contact** HTML Element, populating all matching elements with data from `contact`:

```html
<div id="email-contact">
    ...
    <a data-href="ProfileUrl"><img data-src="ProfileUrl" /></a>
    <h3>
        Email <span data-html="Name"></span>
    </h3>
    <h4>To: <span data-html="Email"></span></h4>
    <div class="clearfix"></div>
    <form id="form-emailcontact" method="POST">
        ...
        <input type="hidden" name="ContactId" data-val="Id"  />
        ...
    </form>
</div>
```

## Advanced bindForm usages

### Form Loading

Whilst a FORM is being processed all its buttons with `[type=submit]` (overridable with `$.ss.onSubmitDisable`) are disabled and a **loading** class is added whilst a response from the server is pending. 
This can be used to provide UX feedback to end users with just CSS. E.g. we use `.loading` CSS rule to show the rotating glyphicon:

```css
#email-contact .loading .rotate {
    visibility: visible;
}
```

### Server initiated actions

Some useful functionality not demonstrated in this example is your Services ability to invoke client behavior by returning a response decorated with custom HTTP Headers. 
An example is being able to return "Soft Redirects" to navigate to a different page by adding a **X-Location** HTTP Header, e.g:

```csharp
return new HttpResult(response) {
    Headers = {
        { "X-Location", newLocationUri },
    }
};
```

When returned to a ajax form, it will instruct the page to automatically redirect to the new url.

You can also trigger an event on the page by returning a **X-Trigger** header, e.g:

```csharp
return new HttpResult(response) {
    Headers = {
        { "X-Trigger", "showLoginPopup" },
    }
};
```

In this case the page event handler named **showLoginPopup** will be invoked if it exists.

As we expect these features to be popular when developing ajax apps we've provided shorter typed aliases for the above examples:

```csharp
return HttpResult.SoftRedirect(new ViewContact { Id = newContact.Id }.ToGetUrl(), newContact);
return HttpResult.TriggerEvent(contact, eventName:"showLoginPopup");
```

### $.ajaxSubmit

The `$.fn.ajaxSubmit` is also available for use independently to submit a HTML form via Ajax on demand. 
This is used in the 
[connections.jsx](https://github.com/ServiceStackApps/RedisReact/blob/15dfc5cfea49d0502ec8c090b5b180d29051ea3a/src/RedisReact/RedisReact/js/components/connections.jsx#L31)
React Component of [Redis React's Connections Page](https://github.com/ServiceStackApps/RedisReact#connections)
to auto submit the form via ajax to the specified `/connection` url with the populated Form INPUT values. It also disables the `#btnConnect` submit button and adds a `.loading` class to the form whilst it's in transit which is used to temporarily show the loading sprite:

```js
var Connections = React.createClass({
    //...
    onSubmit: function (e) {
        e.preventDefault();

        var $this = this;
        $(e.target).ajaxSubmit({
            onSubmitDisable: $("#btnConnect"),
            success: function () {
                $this.setState({ successMessage: "Connection was changed" });
                Actions.loadConnection();
            }
        });
    },
    render: function () {
        var conn = this.state.connection;
        return (
          <div id="connections-page">
            <div className="content">
                <form id="formConnection" className="form-inline" onSubmit={this.onSubmit} action="/connection">
                    <h2>Redis Connection</h2>
                    <div className="form-group">
                        <input name="host" type="text" />
                        <input name="port" type="text" className="form-control" />
                        <input name="db" type="text" className="form-control" />
                    </div>
                    <p className="actions">
                        <img className="loader" src="/img/ajax-loader.gif" />
                        <button id="btnConnect" className="btn btn-default btn-primary">Change Connection</button>
                    </p>
                    <p className="bg-success">{this.state.successMessage}</p>
                    <p className="bg-danger error-summary"></p>
                </form>
            </div>
          </div>
        );
    }
}; 
``` 

### $.ss.parseResponseStatus

Lets you easily parse the raw text of a Ajax Error Response into a responseStatus JavaScript object, example used in Redis React's 
[Console Component](https://github.com/ServiceStackApps/RedisReact/blob/15dfc5cfea49d0502ec8c090b5b180d29051ea3a/src/RedisReact/RedisReact/js/components/console.jsx#L103): 

```js
.fail(function (jq, jqStatus, statusDesc) {
    var status = $.ss.parseResponseStatus(jq.responseText, statusDesc);
    Actions.logEntry({
        cmd: cmd,
        result: status.message,
        stackTrace: status.stackTrace,
        type: 'err',
    });
});
```

### $.ss.bindAll

The `bindAll` API is a simple helper for creating lightweight JavaScript objects by binding `this` for all functions of an object literal to the object instance, e.g:

```js
var Greeting = $.ss.bindAll({
    name: "World",
    sayHello: function() {
        alert("Hello, " + this.name);
    }
});

var fn = Greeting.sayHello;
fn(); // Hello, World
```

## TypeScript Definition

The TypeScript definitions for [ss-utils.d.ts](https://github.com/ServiceStack/ServiceStack/blob/master/src/ServiceStack/js/ss-utils.d.ts) is an embedded resource inside **ServiceStack.dll** which is available from `/js/ss-utils.d.ts`, e.g [servicestack.net/js/ss-utils.d.ts](https://servicestack.net/js/ss-utils.d.ts).

## API Reference

```javascript
$.ss.onSubmitDisable = "[type=submit]"  // Disable elements during form submission

$.ss.validation = {                // Customize Validation
    overrideMessages: false,       // Whether to override Server Error Messages
    messages: {                    // List of Server ErrorCodes to override
      NotEmpty: "Required",        // Override `NotEmpty` ErrorCode with `Required`
    },
}
$.fn.serializeMap()                // Return the FORM's INPUT values as a map
$.fn.setFieldError(name,msg)       // Set the error for field `name` with `msg`
$.fn.applyErrors(status,options)   // Apply errors in ResponseStatus to Element
$.fn.clearErrors()                 // Clear all errors applied to Element
$.ss.clearAdjacentError()          // Clear adjacent errors in help-block/inline
$.ss.parseResponseStatus           // Parse raw JSON Error ResponseStatus

$.fn.bindForm(options)             // Bind and Ajaxify the HTML Form
$.fn.ajaxSubmit()                  // Submit a HTML Form via Ajax
$.fn.applyValues(map)              // Databind values in `map` to HTML Element

$.fn.bindHandlers(handlers)        // Register global declarative JS handlers
$.ss.listenOn = "click ..."        // Specify DOM events for declarative events
$.ss.bindAll                       // Bind all object literal functions to itself

$.fn.setActiveLinks()              // Add `active` class to links with current url

$.ss.todate(string)                // Convert String to Date
$.ss.todfmt(string)                // Convert String to `YYYY-MM-DD` Date Format
$.ss.dfmt(date)                    // Convert Date to `YYYY-MM-DD` Date Format
$.ss.dfmthm(date)                  // Convert Date to `YYYY-MM-DD HH:MM:SS PM`
$.ss.tfmt12(date)                  // Convert Date to `HH:MM:SS PM`

$.ss.splitOnFirst(string,needle)   // Split on first occurrence of needle
$.ss.splitOnLast(string,needle)    // Split on last occurrence of needle

$.ss.getSelection()                // Get currently selected text (if any)

$.ss.queryString(url)              // Return a map of key value pairs

$.fn.handleServerEvents()          // Handle ServiceStack ServerEvents
$.ss.eventReceivers = {}           // Specify global receivers for ServerEvents
```

#### combinePaths and createUrl

The `combinePaths` and `createUrl` API's help with constructing urls, e.g:

```javascript
$.ss.combinePaths("path","to","..","join")   //= path/join
$.ss.createPath("path/{foo}", {foo:1,bar:2}) //= path/1

$.ss.createUrl("http://host/path/{foo}",{foo:1,bar:2}) //= http://host/path/1?bar=2
```

#### normalize and normalizeKey

`normalizeKey` and `normalize` APIs helps with normalizing JSON responses with different naming 
conventions by converting each property into lowercase with any `_` separators removed - `normalizeKey()` 
converts a single string whilst `normalize()` converts an entire object graph, e.g:

```javascript
$.ss.normalizeKey("THE_KEY") //= thekey

JSON.stringify(
    $.ss.normalize({THE_KEY:"key",Foo:"foo",bar:{A:1}})
)   //= {"thekey":"key","foo":"foo","bar":{"A":1}}

const deep = true;
JSON.stringify(
    $.ss.normalize({THE_KEY:"key",Foo:"foo",bar:{A:1}}, deep) 
)   //= {"thekey":"key","foo":"foo","bar":{"a":1}}
```

#### postJSON

`postJSON` is jQuery's missing equivalent to `$.getJSON`, but for POST's, eg:

```javascript
$.ss.postJSON(url, {data:1}, response => ..., error => ...);
```


# IIS Hosting
Source: https://docs.servicestack.net/iis

## Register ServiceStack ASP.NET HttpHandler

ServiceStack integrates with your existing ASP.NET Web Application by registering an ASP.NET HttpHandler used to route HTTP requests to ServiceStack. The configuration below supports both IIS/6.0 and Mono as well as IIS7+ new handler mappings under `<system.webServer>`:

### Configure ServiceStack at `/` root path

Add this configuration in your `Web.config` to host ServiceStack at the `/` root path:

```xml
<!-- For IIS 6.0/Mono -->
<system.web>
  <httpHandlers>    
    <add path="*" type="ServiceStack.HttpHandlerFactory, ServiceStack" 
         verb="*"/>
  </httpHandlers>
</system.web>

<!-- For IIS 7.0+ -->
<system.webServer>
  <validation validateIntegratedModeConfiguration="false" />
  <handlers>
    <add path="*" name="ServiceStack.Factory" preCondition="integratedMode" 
         type="ServiceStack.HttpHandlerFactory, ServiceStack" 
         verb="*" resourceType="Unspecified" allowPathInfo="true" />
  </handlers>
</system.webServer>
```

::: info Tip
If you want to host your webservice on a custom path to avoid conflicts with another web framework (eg ASP.Net MVC), see [Run ServiceStack side-by-side with another Framework](/servicestack-side-by-side-with-another-web-framework)
:::

::: info
Due to limitations in IIS 6 - host [ServiceStack at a /custompath](/mvc-integration#enabling-servicestack-in-webconfig) which must end with `.ashx`, e.g: `path="api.ashx"`
:::

### Configure ServiceStack at `/api` custom path

If you want to use ServiceStack together with an existing ASP.NET Web Framework, you can instead host ServiceStack at `/api` path with:

```xml
<location path="api">
  <system.web>
    <httpHandlers>
      <add path="*" type="ServiceStack.HttpHandlerFactory, ServiceStack" 
           verb="*"/>
    </httpHandlers>
  </system.web>

  <system.webServer>
    <modules runAllManagedModulesForAllRequests="true"/>
    <validation validateIntegratedModeConfiguration="false" />
    <handlers>
      <add path="*" name="ServiceStack.Factory" 
           type="ServiceStack.HttpHandlerFactory, ServiceStack" 
           verb="*" preCondition="integratedMode" 
           resourceType="Unspecified" allowPathInfo="true" />
    </handlers>
  </system.webServer>
</location>
```

To use ServiceStack together with ASP.NET MVC follow the steps in the [Mvc integration](/mvc-integration) docs.

## Troubleshooting

### Disable WebDAV to enable PUT and DELETE Verbs

If you are running IIS 7.5 you may need to disable the WebDAV module to enable `PUT` and `DELETE` verbs.  You can do this globally through IIS or locally through a web.config.

```xml
<system.webServer>
  <modules runAllManagedModulesForAllRequests="true">
    <remove name="WebDAVModule" />
  </modules>
</system.webServer>
```


# Self-Hosting
Source: https://docs.servicestack.net/self-hosting

The quickest way to create a Self-Hosting application is to Create a new self-hosting VS.NET Project Template from [ServiceStackVS VS.NET Extension](https://github.com/ServiceStack/ServiceStackVS#servicestack-vsnet-templates).

Otherwise it's very easy to host ServiceStack in a Console App or Windows Service. You just have to Install the [ServiceStack NuGet package](https://www.nuget.org/packages/ServiceStack) and derive your AppHost from `AppSelfHostBase` instead of `AppHostBase`:

If using this in a .NET standard console app, you should reference [ServiceStack.Kestrel](https://www.nuget.org/packages/ServiceStack.Kestrel) NuGet package.

## Complete C# Console Host Example

```csharp
using System;
using ServiceStack;

class Program 
{
    [Route("/hello/{Name}")]
    public class Hello {
        public string Name { get; set; }
    }

    public class HelloResponse {
        public string Result { get; set; }
    }

    public class HelloService : Service
    {
        public object Any(Hello request) 
        {
            return new HelloResponse { Result = "Hello, " + request.Name };
        }
    }

    //Define the Web Services AppHost
    public class AppHost : AppSelfHostBase {
        public AppHost() 
          : base("HttpListener Self-Host", typeof(HelloService).Assembly) {}

        public override void Configure(Funq.Container container) { }
    }

    //Run it!
    static void Main(string[] args)
    {
        var listeningOn = args.Length == 0 ? "http://*:1337/" : args[0];
        var appHost = new AppHost()
            .Init()
            .Start(listeningOn);

        Console.WriteLine("AppHost Created at {0}, listening on {1}", 
            DateTime.Now, listeningOn);
            
        Console.ReadKey();
    }
}
```

## Complete VB.NET Console Host Example
```vb
Imports System
Imports ServiceStack

Public Class Program

    <Route("/hello/{Name}")>
    Public Class Hello
        Public Property Name As String
    End Class


    Public Class HelloResponse
        Public Property Result As String
    End Class


    Public Class HelloService
        Inherits Service
        Public Function Any(Request As Hello) As Object
            Return New HelloResponse() With {.Result = "Hello" & Request.Name}
        End Function
    End Class

    ' Define the Web Services AppHost
    Public Class AppHost
        Inherits AppSelfHostBase

        Public Sub New()
            MyBase.New("HttpListener Self-Host", GetType(HelloService).Assembly)
        End Sub

        Public Overrides Sub Configure(container As Funq.Container)
        End Sub
    End Class

    ' Run it!
    Overloads Shared Sub Main(ByVal Args() As String)        
        Dim listeningOn As String = If(Args.Length = 0, "http://*:1337/", Args(0))

        Dim AppHost As IAppHost = New AppHost().Init().Start(listeningOn)

        Console.WriteLine("AppHost Created at {0}, listening on {1}",
            DateTime.Now, listeningOn)

        Console.ReadKey()

    End Sub
End Class
```

## Complete F# Console Host Example

```fsharp
open System
open ServiceStack
 
type Hello = { mutable Name: string; }
type HelloResponse = { mutable Result: string; }
type HelloService() =
    interface IService with
        member this.Any (req:Hello) = { Result = "Hello, " + req.Name }
 
//Define the Web Services AppHost
type AppHost =
    inherit AppSelfHostBase 
    new() = { inherit AppSelfHostBase("Hello F# Services", typeof<HelloService>.Assembly) }
    override this.Configure container =
        base.Routes
            .Add<Hello>("/hello")
            .Add<Hello>("/hello/{Name}") |> ignore
 
//Run it!
[<EntryPoint>]
let main args =
    let host = if args.Length = 0 then "http://*:1337/" else args.[0]
    printfn "listening on %s ..." host
    let appHost = new AppHost()
    appHost.Init()
    appHost.Start host
    Console.ReadLine() |> ignore
    0
```

When any of these are running, you can call your hello service at `http://localhost:1337/hello/World!`

## Windows Service Template

You can use [winservice-netfx](https://github.com/NetFrameworkTemplates/winservice-netfx) to create a Windows Service but as this requires Visual Studio it's faster to continue creating new Windows Service projects within VS.NET using the **ServiceStack Windows Service Empty** Project Template.

## Serving Razor Views or Static Files from HttpListener

The PhysicalPath for self-hosted HttpListener hosts is at the same directory where the `.exe` is run (e.g. in `/bin`). To serve any static files or execute any Razor Views you need to set the **Copy Output Directory** of all static assets you want available to `Copy if newer`. The [ServiceStack.Gap](https://github.com/ServiceStack/ServiceStack.Gap) feature provides an alternative packaging approach that can embed static resources and pre-compile razor views into a single `.exe` for the most optimal deployment.

## Serve Static Files from your Project Path

An alternative way for the Self-Hosted Console Application to find your Static files and Razor Views is to change the physical path so it points at your project directory. This enables an optimal **Live Reloading** development experience since its serving the original source Views you edit directly in your Project and not any copies that are copied to your `/bin`. 

You can change the Physical Path from the location where the **.exe** is run in `\bin\Debug` to your Project folder in `DEBUG` builds with: 

```csharp
SetConfig(new HostConfig {
#if DEBUG
    DebugMode = true,
    WebHostPhysicalPath = "~/../..".MapServerPath(),
#endif
});
```

::: info
You will still need to "Copy to Output Directory" in RELEASE builds if you're not using [Embedded Resources](/virtual-file-system#embedded-resources) so the Console App can locate the Razor Views and Static files at runtime
:::

## Host as a Windows or Linux Console Host, Windows Service or Linux Daemon

This will run in as a Console Host in any Operating System with .NET 3.5 or Mono installed. In addition this can also be wrapped-up and run inside a [Windows Service](https://github.com/ServiceStack/ServiceStack.Examples/tree/master/src/StarterTemplates/WinServiceAppHost) or run as a [Linux Daemon](/servicestack-as-daemon-on-linux) which you can optionally elect to serve behind [Apache or Nginx reverse proxies](/servicestack-as-daemon-on-linux).

## Easily Convert to an ASP.NET Web Service

As both AppHostBase and AppHostHttpListenerBase follow the same API they are easily convertible between the two. Here's some step-by-step instructions showing you how to convert an [F# Console Host to an ASP.NET Web Service on OSX!](http://www.servicestack.net/mythz_blog/?p=785)


# Community Resources

  - [ServiceStack how to: SelfHost + Razor + WebForm Auth](http://lderache.github.io/servicestack-how-to-selfhost-plus-razor-plus-webform/) by [@laurentderache](https://twitter.com/laurentderache)  
  - [ServiceStack SelfHosted Performance Boost](http://en.rdebug.com/2013/05/servicestack-selfhosted-performance-boost/) by [@rudygt](https://twitter.com/rudygt)
  - [Self-hosting ServiceStack serving razor'd HTML](http://www.ienablemuch.com/2012/12/self-hosting-servicestack-serving.html) by [@ienablemuch](http://twitter.com/ienablemuch)


# Testing
Source: https://docs.servicestack.net/testing

The tests in [ServiceStack.WebHost.Endpoints.Tests](https://github.com/ServiceStack/ServiceStack/tree/master/tests/ServiceStack.WebHost.Endpoints.Tests) show good examples of how to create stand-alone integration tests that just use a self-hosted HttpListener AppHost. 

## Quick Mix

Use [mix](/mix-tool) to quickly create a [.NET 6 Integration Test](https://gist.github.com/gistlyn/114fbc40a89dbc65cfe9e04c2f4f8ef6) project:

```bash
$ x mix init-test
```

Or if you need to create a source compatible [.NET 6 and .NET v4.72 Integration Test](https://gist.github.com/gistlyn/e7c7fa5e825a033ce45e2edfec4c6244) project:

```bash
$ x mix init-test2
```


## Example Stand-alone Integration tests

  - [BufferedRequestTests](https://github.com/ServiceStack/ServiceStack/blob/master/tests/ServiceStack.WebHost.Endpoints.Tests/BufferedRequestTests.cs)
  - [AuthTests](https://github.com/ServiceStack/ServiceStack/blob/master/tests/ServiceStack.WebHost.Endpoints.Tests/AuthTests.cs)

## Integration Testing

If your test project is targeting netcore, `AppSelfHostBase` is available in the `ServiceStack.Kestrel` package.

The [CustomerRestExample.cs](https://github.com/ServiceStack/ServiceStack/blob/master/tests/ServiceStack.WebHost.Endpoints.Tests/CustomerRestExample.cs) shows an example of a stand-alone integration test. Integration tests in ServiceStack just involves starting a standard [self-host](/self-hosting) ServiceStack Instance when the Test Fixture Starts up and disposing it when it tears down. Your integration tests can then communicate with the self-host exactly the same as if it were a remote ServiceStack instance (since that's all it is), e.g:

```csharp
//Create your ServiceStack AppHost with only the dependencies it needs
public class AppHost : AppSelfHostBase
{
    public AppHost() : base("Customer REST Example", typeof(CustomerService).Assembly) {}

    public override void Configure(Container container)
    {
        container.Register<IDbConnectionFactory>(c => 
            new OrmLiteConnectionFactory(":memory:", SqliteDialect.Provider));

        using var db = container.Resolve<IDbConnectionFactory>().Open();
        db.CreateTableIfNotExists<Customer>();
    }
}

//Add Service Contract DTO's and Data Models
[Route("/customers", "GET")]
public class GetCustomers : IReturn<GetCustomersResponse> {}

public class GetCustomersResponse
{
    public List<Customer> Results { get; set; } 
}

[Route("/customers", "POST")]
public class CreateCustomer : IReturn<Customer>
{
    public string Name { get; set; }
}

public class Customer
{
    [AutoIncrement]
    public int Id { get; set; }

    public string Name { get; set; }
}

//Implement your Service Contracts
public class CustomerService : Service
{
    public object Get(GetCustomers request)
    {
        return new GetCustomersResponse { Results = Db.Select<Customer>() };
    }

    public object Post(CreateCustomer request)
    {
        var customer = new Customer { Name = request.Name };
        Db.Save(customer);
        return customer;
    }
}

//Write your Integration tests
public class CustomerRestExample
{
    const string BaseUri = "http://localhost:2000/";
    ServiceStackHost appHost;

    public CustomerRestExample()
    {
        //Start your AppHost on OneTimeSetUp
        appHost = new AppHost() 
            .Init()
            .Start(BaseUri);
    }

    [OneTimeTearDown]
    public void OneTimeTearDown() => appHost.Dispose();

    /* Write your Integration Tests against the self-host instance */

    [Test]
    public void Can_GET_and_Create_Customers()
    {
        var client = new JsonApiClient(BaseUri);

        //GET /customers
        var all = client.Get(new GetCustomers());
        Assert.That(all.Results.Count, Is.EqualTo(0));

        //POST /customers
        var customer = client.Post(new CreateCustomer { Name = "Foo" });
        Assert.That(customer.Id, Is.EqualTo(1));

        //GET /customers
        all = client.Get(new GetCustomers());
        Assert.That(all.Results.Count, Is.EqualTo(1));
    }
}
```

## Unit testing

If you want to unit test a ServiceStack Service in isolation there are a couple of different approaches you can take. The base [Service](https://github.com/ServiceStack/ServiceStack/blob/master/src/ServiceStack/Service.cs) class itself is just a simple C# class which lets you define and inject dependencies manually or by using the built-in IOC container. 

We'll illustrate both approaches using this [simple unit test example](https://github.com/ServiceStack/ServiceStack/blob/master/tests/ServiceStack.WebHost.Endpoints.Tests/UnitTestExample.cs) that tests this simple Service:

```csharp
// DTOs
public class FindRockstars
{
   public int? Aged { get; set; }
   public bool? Alive { get; set; }
}

public class GetStatus
{
   public string LastName { get; set; }
}

public class RockstarStatus
{
   public int Age { get; set; }
   public bool Alive { get; set; }
}

public class Rockstar
{
   [AutoIncrement]
   public int Id { get; set; }
   public string FirstName { get; set; }
   public string LastName { get; set; }
   public int? Age { get; set; }
}

// Implementation
public class SimpleService : Service
{
   public IRockstarRepository RockstarRepository { get; set; }

   public List<Rockstar> Get(FindRockstars request)
   {
      return request.Aged.HasValue
          ? Db.Select<Rockstar>(q => q.Age == request.Aged.Value)
          : Db.Select<Rockstar>();
   }

   public RockstarStatus Get(GetStatus request)
   {
      var rockstar = RockstarRepository.GetByLastName(request.LastName);
      if (rockstar == null)
          throw HttpError.NotFound($"'{request.LastName}' is not a Rockstar");

      var status = new RockstarStatus
      {
          Alive = RockstarRepository.IsAlive(request.LastName)
      }.PopulateWith(rockstar); //Populates with matching fields

      return status;
   }
}
```

This Service provides 2 operations, `FindRockstars` which makes db queries directly in the service class itself, and `GetStatus` which uses a repository instead for all its Data access.

### Using an in-memory database

If you're accessing `Db` from directly within your service implementation you're going to want to make use of a real DB given the [ADO.NET IDbConnection](http://msdn.microsoft.com/en-us/library/system.data.idbconnection.aspx) requires a lot of effort to mock. You can do this in the same way you would register your dependencies in ServiceStack itself, by using the built-in IOC. For a unit test we can do this without an AppHost by just use a new `Container` in your `OneTimeSetUp`, e.g:

### Test Setup

```csharp
private ServiceStackHost appHost;

[OneTimeSetUp]
public void OneTimeSetUp()
{
    appHost = new BasicAppHost().Init();
    var container = appHost.Container;

    container.Register<IDbConnectionFactory>(
        new OrmLiteConnectionFactory(":memory:", SqliteDialect.Provider));

    container.RegisterAutoWiredAs<RockstarRepository, IRockstarRepository>();

    container.RegisterAutoWired<SimpleService>();

    using (var db = container.Resolve<IDbConnectionFactory>().Open())
    {
        db.DropAndCreateTable<Rockstar>();
        db.InsertAll(SeedData);
    }
}

[OneTimeTearDown]
public void OneTimeTearDown() => appHost.Dispose();
```

With everything setup we can now test the service just like a normal C# class in isolation independently of ServiceStack itself:

```csharp
[Test]
public void Using_in_memory_database()
{
    //Resolve the autowired service from IOC and set Resolver for the base class
    var service = appHost.Container.Resolve<SimpleService>(); 

    var rockstars = service.Get(new FindRockstars { Aged = 27 });

    rockstars.PrintDump(); //Print a dump of the results to Console

    Assert.That(rockstars.Count, Is.EqualTo(SeedData.Count(x => x.Age == 27)));

    var status = service.Get(new GetStatus { LastName = "Vedder" });
    Assert.That(status.Age, Is.EqualTo(48));
    Assert.That(status.Alive, Is.True);

    status = service.Get(new GetStatus { LastName = "Hendrix" });
    Assert.That(status.Age, Is.EqualTo(27));
    Assert.That(status.Alive, Is.False);

    Assert.Throws<HttpError>(() =>
        service.Get(new GetStatus { LastName = "Unknown" }));
}
```

### Manually injecting dependencies

If you prefer your unit tests not to use an in-memory database, you can instead choose to mock your dependencies. In this example we'll use a stand-alone Mock, but you can reduce boilerplate by using mocking library like [Moq](https://github.com/Moq/moq) instead.

```csharp
public class RockstarRepositoryMock : IRockstarRepository
{
    public Rockstar GetByLastName(string lastName)
    {
        return lastName == "Vedder"
            ? new Rockstar(6, "Eddie", "Vedder", 48)
            : null;
    }

    public bool IsAlive(string lastName)
    {
        return lastName == "Grohl" || lastName == "Vedder";
    }
}

[Test]
public void Using_manual_dependency_injection()
{
    var service = new SimpleService
    {
        RockstarRepository = new RockstarRepositoryMock()
    };

    var status = service.Get(new GetStatus { LastName = "Vedder" });
    Assert.That(status.Age, Is.EqualTo(48));
    Assert.That(status.Alive, Is.True);

    Assert.Throws<HttpError>(() =>
        service.Get(new GetStatus { LastName = "Hendrix" }));
}
```

This example doesn't need a container as we're injecting all the dependencies manually.

## Testing ServiceStack classes in Unit Tests

Much of ServiceStack functionality assumes there's an AppHost is available which for Unit Tests you can just use an In Memory AppHost, e.g:

```csharp
[Test]
public void My_unit_test()
{
    using (new BasicAppHost().Init())
    {
        //test ServiceStack classes
    }
}
```

If preferred this can be set up once per test fixture following this pattern:

```csharp
public class MyUnitTests
{
    ServiceStackHost appHost;
    public MyUnitTests() => appHost = new BasicAppHost().Init();

    [OneTimeTearDown]
    public void OneTimeTearDown() => appHost.Dispose();

    [Test]
    public void My_unit_test()
    {
        //test ServiceStack classes
   }
}
```


# Community Resources

  - [ServiceStack 4 HTTP Utilities: Contract Testing](http://kylehodgson.com/2014/06/03/servicestack-4-http-utilities-contract-testing/) by [@kylehodgson](https://twitter.com/kylehodgson)
  - [Regression testing ServiceStack services with RavenDB embedded](http://iwayneo.blogspot.co.uk/2014/05/regression-testing-servicestack.html) by [@wayne_douglas](https://twitter.com/wayne_douglas)
  - [ServiceStack – Testing services with Chrome REST Console](http://dilanperera.wordpress.com/2014/02/23/servicestack-testing-services-with-chrome-rest-console/)
  - [ServiceStack and RavenDB End to End Testing](http://tech.pro/tutorial/1276/servicestack-and-ravendb-end-to-end-testing) by [@aquabirdconsult](https://twitter.com/AquaBirdConsult)
  - [Integration Testing With ServiceStack](http://rossipedia.com/blog/2013/02/integration-testing-with-servicestack/) by [@rossipedia](https://twitter.com/rossipedia)
  - [How to unit test your database code when using ServiceStack OrmLite](http://www.rickardnilsson.net/post/2013/01/19/how-to-unit-test-your-database-code-when-using-servicestack-ormlite.aspx) by [@rickardn](https://twitter.com/rickardn)
  - [EasyHttp and ServiceStack, making the mspec tests better](http://blogs.lessthandot.com/index.php/DesktopDev/MSTech/easyhttp-and-servicestack-making-it) by [@chrissie1](https://twitter.com/chrissie1)
  - [Using ServiceStack for the EasyHttp integration tests](http://blogs.lessthandot.com/index.php/DesktopDev/MSTech/using-servicestack-for-the-easyhttp) by [@chrissie1](https://twitter.com/chrissie1)
  - [Parameterized Tests for ServiceStack Web Services](http://nikosbaxevanis.com/2012/02/18/parameterized-tests-for-servicestack-web-services/)

### Stack Overflow

  - [Unit Test HTTPRequest Headers with ServiceStack](http://stackoverflow.com/a/14791657/85785)
  - [ServiceStack and Mocking, any tutorials?](http://stackoverflow.com/a/9587745/85785)
  - [How do you mock ServiceStack ISession using Moq and StructureMap?](http://stackoverflow.com/a/15012300/85785)


# How to write Unit &amp; Integration tests
Source: https://docs.servicestack.net/howto-write-unit-integration-tests

## Integration test example

The [CustomerRestExample.cs](https://github.com/ServiceStack/ServiceStack/blob/master/tests/ServiceStack.WebHost.Endpoints.Tests/CustomerRestExample.cs) shows an example of a stand-alone integration test:

```csharp
//Create your ServiceStack AppHost with only the dependencies your tests need
public class AppHost : AppSelfHostBase
{
    public AppHost() : base("Customer REST Example", typeof(CustomerService).Assembly) {}

    public override void Configure(Container container)
    {
        container.Register<IDbConnectionFactory>(c => 
            new OrmLiteConnectionFactory(":memory:", SqliteDialect.Provider));

        using var db = container.Resolve<IDbConnectionFactory>().Open();
        db.CreateTableIfNotExists<Customer>();
    }
}

//Add Service Contract DTO's and Data Models
[Route("/customers", "GET")]
public class GetCustomers : IReturn<GetCustomersResponse> {}

public class GetCustomersResponse
{
    public List<Customer> Results { get; set; } 
}

[Route("/customers/{Id}", "GET")]
public class GetCustomer : IReturn<Customer>
{
    public int Id { get; set; }
}

[Route("/customers", "POST")]
public class CreateCustomer : IReturn<Customer>
{
    public string Name { get; set; }
}

[Route("/customers/{Id}", "PUT")]
public class UpdateCustomer : IReturn<Customer>
{
    public int Id { get; set; }

    public string Name { get; set; }
}

[Route("/customers/{Id}", "DELETE")]
public class DeleteCustomer : IReturnVoid
{
    public int Id { get; set; }
}

public class Customer
{
    [AutoIncrement]
    public int Id { get; set; }

    public string Name { get; set; }
}

//Provide the implementation for your above Service Contracts
public class CustomerService : Service
{
    public object Get(GetCustomers request)
    {
        return new GetCustomersResponse { Results = Db.Select<Customer>() };
    }

    public object Get(GetCustomer request)
    {
        return Db.SingleById<Customer>(request.Id);
    }

    public object Post(CreateCustomer request)
    {
        var customer = new Customer { Name = request.Name };
        Db.Save(customer);
        return customer;
    }

    public object Put(UpdateCustomer request)
    {
        var customer = Db.SingleById<Customer>(request.Id);
        if (customer == null)
            throw HttpError.NotFound($"Customer '{request.Id}' does not exist");

        customer.Name = request.Name;
        Db.Update(customer);

        return customer;
    }

    public void Delete(DeleteCustomer request)
    {
        Db.DeleteById<Customer>(request.Id);
    }
}

//Write your Integration tests
public class CustomerRestExample
{
    const string BaseUri = "http://localhost:2000/";
    ServiceStackHost appHost;

    public void CustomerRestExample()
    {
        //Start your AppHost on TestFixture SetUp
        appHost = new AppHost()
            .Init()
            .Start(BaseUri);
    }

    [OneTimeTearDown]
    public void OneTimeTearDown() => appHost.Dispose();

    /* Write your Integration Tests against the self-host instance */

    [Test]
    public void Run_Customer_REST_Example()
    {
        var client = new JsonApiClient(BaseUri);

        //GET /customers
        var all = client.Get(new GetCustomers());
        Assert.That(all.Results.Count, Is.EqualTo(0));

        //POST /customers
        var customer = client.Post(new CreateCustomer { Name = "Foo" });
        Assert.That(customer.Id, Is.EqualTo(1));
        //GET /customer/1
        customer = client.Get(new GetCustomer { Id = customer.Id });
        Assert.That(customer.Name, Is.EqualTo("Foo"));

        //GET /customers
        all = client.Get(new GetCustomers());
        Assert.That(all.Results.Count, Is.EqualTo(1));

        //PUT /customers/1
        customer = client.Put(new UpdateCustomer { Id = customer.Id, Name = "Bar" });
        Assert.That(customer.Name, Is.EqualTo("Bar"));

        //DELETE /customers/1
        client.Delete(new DeleteCustomer { Id = customer.Id });
        //GET /customers
        all = client.Get(new GetCustomers());
        Assert.That(all.Results.Count, Is.EqualTo(0));
    }
}
```


# Blazor Tailwind
Source: https://docs.servicestack.net/templates/blazor-tailwind

<div class="not-prose mt-16 flex flex-col items-center">
   <div class="flex">
      <svg class="w-28 h-28 text-purple-500" xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24"><path fill="currentColor" d="M23.834 8.101a13.912 13.912 0 0 1-13.643 11.72a10.105 10.105 0 0 1-1.994-.12a6.111 6.111 0 0 1-5.082-5.761a5.934 5.934 0 0 1 11.867-.084c.025.983-.401 1.846-1.277 1.871c-.936 0-1.374-.668-1.374-1.567v-2.5a1.531 1.531 0 0 0-1.52-1.533H8.715a3.648 3.648 0 1 0 2.695 6.08l.073-.11l.074.121a2.58 2.58 0 0 0 2.2 1.048a2.909 2.909 0 0 0 2.695-3.04a7.912 7.912 0 0 0-.217-1.933a7.404 7.404 0 0 0-14.64 1.603a7.497 7.497 0 0 0 7.308 7.405s.549.05 1.167.035a15.803 15.803 0 0 0 8.475-2.528c.036-.025.072.025.048.061a12.44 12.44 0 0 1-9.69 3.963a8.744 8.744 0 0 1-8.9-8.972a9.049 9.049 0 0 1 3.635-7.247a8.863 8.863 0 0 1 5.229-1.726h2.813a7.915 7.915 0 0 0 5.839-2.578a.11.11 0 0 1 .059-.034a.112.112 0 0 1 .12.053a.113.113 0 0 1 .015.067a7.934 7.934 0 0 1-1.227 3.549a.107.107 0 0 0-.014.06a.11.11 0 0 0 .073.095a.109.109 0 0 0 .062.004a8.505 8.505 0 0 0 5.913-4.876a.155.155 0 0 1 .055-.053a.15.15 0 0 1 .147 0a.153.153 0 0 1 .054.053A10.779 10.779 0 0 1 23.834 8.1zM8.895 11.628a2.188 2.188 0 1 0 2.188 2.188v-2.042a.158.158 0 0 0-.15-.15Z"></path></svg>
   </div>
</div>
<div class="not-prose mt-4 px-4 sm:px-6">
<div class="text-center"><h3 id="blazor-template" class="text-4xl sm:text-5xl md:text-6xl tracking-tight font-extrabold text-gray-900">
    Blazor WASM Tailwind
</h3></div>
<div class="py-8 max-w-7xl mx-auto px-4 sm:px-6">
    <lite-youtube class="w-full mx-4 my-4" width="560" height="315" videoid="BXjcKkaK-nM" style="background-image: url('https://img.youtube.com/vi/BXjcKkaK-nM/maxresdefault.jpg')"></lite-youtube>
</div>
</div>

<div class="relative bg-white dark:bg-black py-4">
    <div class="mx-auto max-w-md px-4 text-center sm:max-w-3xl sm:px-6 lg:max-w-7xl lg:px-8">
        <h2 class="text-base font-semibold uppercase tracking-wider text-indigo-600">Getting Started</h2>
        <p class="mt-2 text-3xl font-extrabold tracking-tight text-gray-900 dark:text-gray-50 sm:text-4xl">Create a new Blazor WASM Tailwind App</p>
        <p class="mx-auto mt-5 max-w-prose text-xl text-gray-500"> 
            Create a new Blazor WASM Tailwind project with your preferred project name:
        </p>
    </div>
</div>

<blazor-templates class="not-prose pb-8"></blazor-templates>

Alternatively you can create & download a new Blazor Project with the [x dotnet tool](/dotnet-new):

:::sh
x new blazor-wasm ProjectName
:::

The feature-rich Blazor WASM Tailwind template is ideal for teams with strong C# skills building Line Of Business (LOB) applications who prefer utilizing Tailwind's modern utility-first CSS design system to create beautiful, instant-loading Blazor WASM Apps.

<a href="https://blazor-wasm.web-templates.io">
    <div class="block flex justify-center shadow hover:shadow-lg rounded py-1">
        <img class="" src="/img/pages/blazor/blazor-tailwind-splash.png">
    </div>
    <div class="pt-4 text-center">
        blazor-wasm.web-templates.io
    </div>
</a>

Since the release of .NET 8, we have been upgrading our [Blazor Templates](https://servicestack.net/start) and example applications to take advantage of some of the new features, including making use of static Server Side Rendering (SSR) for Blazor, which allows for faster initial page loads and better SEO, and our [blazor-wasm](https://github.com/NetCoreTemplates/blazor-wasm) template uses `InteractiveAuto` by default to provide a more Responsive UI.

## What is InteractiveAuto?

Blazor for .NET 8 has [four different rendering modes](https://learn.microsoft.com/en-us/aspnet/core/blazor/components/render-modes?view=aspnetcore-8.0#render-modes) you can take advantage of:

- Static Server (static SSR)
- Interactive Server
- Interactive WebAssembly (WASM)
- Interactive Auto

For non-interactive pages, the static SSR mode is the fastest, as it renders the page on the server and sends the HTML to the client.
However, when your page needs to be interactive, you need to use one of the interactive modes.

Prior to .NET 8, there was a trade-off between the two available render modes (static server rendering wasn't yet available).
The `Interactive Server` mode was faster to load, but the `Interactive WASM` mode was more responsive.

The initial load times for `Interactive WASM` could be quite slow, as the entire application and all its dependencies needed to be downloaded before the page could render most of the content.

<img class="border-gray-800 border-t border-r" src="/img/pages/blazor/wasm/blazor-wasm-6-slow.gif">

> The initial load time for the `Interactive WASM` mode can be quite slow even for a minimal app

Our templates previously worked around this limitation with a custom Pre-Rendering solution, as the wait times were too long for a good user experience.

.NET 8's new `Interactive Auto` mode provides the best of both worlds as pre-rendering is now enabled by default.

<img class="border-gray-800 border-r" src="/img/pages/blazor/wasm/blazor-wasm-8-fast.gif">

When the page is first loaded, it uses the `Interactive Server` mode, which is faster than `Interactive WASM` as it doesn't need to download WASM resources.
So the user can start interacting with the page straight away, but with a slight delay for each of their interactions due to having to perform round-trips to the server for each interaction.

In the background, the WASM resources are downloaded which can then be used to render the site on the client for subsequent visits.

## Using InteractiveAuto in your Blazor application

In Blazor for .NET 8, render modes can be set on both a per-page and per-component basis.

```html
@page "/counter"
@rendermode InteractiveAuto

<Counter />
```

```html
<Counter @rendermode="RenderMode.InteractiveAuto" />
```

## ServiceStack.Blazor Components

The [ServiceStack.Blazor Components](https://blazor-gallery.jamstacks.net) have been updated for .NET 8 and work with the new `InteractiveAuto` render mode.

This means you can focus more on your application logic and less on the UI, as the components provide a high-productivity UI for common tasks such as CRUD operations.

### AutoQueryGrid

The [AutoQueryGrid](https://blazor-gallery.servicestack.net/gallery/autoquerygrid) component provides a full-featured data grid that can be used to display and edit data from an AutoQuery service.
This is ideal for creating custom admin pages for your application. 
By integrating your admin screens into your application, you can optimize the user experience for specific workflows and get a huge amount of reuse of your existing AutoQuery services.

```html
<AutoQueryGrid Model="Modifier" Apis="Apis.AutoQuery<QueryModifiers,CreateModifier,UpdateModifier,DeleteModifier>()" />
```

![](/img/pages/blazor/wasm/autoquerygrid.png)

For [BlazorDiffusion](https://github.com/NetCoreApps/BlazorDiffusionAuto), our StableDiffusion example application, we used the AutoQueryGrid to create a custom admin page for managing the modifiers in the application.

![](/img/pages/blazor/wasm/stablediffusion-modifiers.png)

This is the simplest and fastest use of the AutoQueryGrid component, but it can also be heavily customized for lots of different use cases.

In [BlazorDiffusion](https://github.com/NetCoreApps/BlazorDiffusionAuto) we customize the grid to enable easy navigation contextually between separate customized admin screens for each Creative, linking to related table data.

![](/img/pages/blazor/wasm/blazordiffusion-creatives.png)

```html
<AutoQueryGrid @ref=@grid Model="Creative" Apis="Apis.AutoQuery<QueryCreatives,UpdateCreative,HardDeleteCreative>()"
               ConfigureQuery="ConfigureQuery">
    <EditForm>
        <div class="relative z-10" aria-labelledby="slide-over-title" role="dialog" aria-modal="true">
            <div class="pointer-events-none fixed inset-y-0 right-0 flex max-w-full pl-10 sm:pl-16">
                <CreativeEdit Creative="context" OnClose="grid.OnEditDone" />
            </div>
        </div>
    </EditForm>
    <Columns>
        <Column Title="User" Field="(Creative x) => x.OwnerId" />
        <Column Title="Id" Field="(Creative x) => x.Id" />
        <Column Field="(Creative x) => x.Modifiers">
            <Template>
                @if (context.Modifiers?.Count > 0)
                {
                <TextLink class="flex" href=@($"/admin/modifiers?Ids={string.Join(",", context.Modifiers.Select(x => x.ModifierId))}")>
                    <Icon class="w-6 h-6 mr-1" Image=@typeof(Modifier).GetIcon() />
                    @TextUtils.Pluralize("Modifier", context.Modifiers)
                </TextLink>
                }
            </Template>
        </Column>
        <Column Field="(Creative x) => x.Artists">
            <Template>
                @if (context.Artists?.Count > 0)
                {
                <TextLink class="flex" href=@($"/admin/artists?Ids={string.Join(",", context.Artists.Select(x => x.ArtistId))}")>
                    <Icon class="w-6 h-6 mr-1" Image=@typeof(Artist).GetIcon() />
                    @TextUtils.Pluralize("Artist", context.Artists)
                </TextLink>
                }
            </Template>
        </Column>
        <Column Field="(Creative x) => x.Artifacts">
            <Template>
                @if (context.Artifacts?.Count > 0)
                {
                <TextLink class="flex" href=@($"/admin/artifacts?CreativeId={context.Id}")>
                    <Icon class="w-6 h-6 mr-1" Image=@typeof(Artifact).GetIcon() />
                    @TextUtils.Pluralize("Artifact", context.Artifacts)
                </TextLink>
                }
            </Template>
        </Column>
        <Column Field="(Creative x) => x.Key" />
        <Column Field="(Creative x) => x.CreatedDate" Format="s" />
        <Column Field="(Creative x) => x.UserPrompt" />
    </Columns>
</AutoQueryGrid>
```

In the above example, we use the `ConfigureQuery` parameter to customize the query used by the AutoQueryGrid when displaying values.
This is ideal if you want to filter the data for specific workflows, for example, only showing the data that is relevant to the current user.

We combine this with a `Tabs` component to provide a navigation bar for the user to switch between the different filters on the same AutoQueryGrid.

```html
<Tabs TabOptions="TabOptions" TabChanged="TabChangedAsync" />
```

:::{.shadow .max-w-screen-sm}
![](/img/pages/blazor/wasm/blazordiffusion-tab.png)
:::

<p></p>

:::{.shadow .max-w-screen-sm}
![](/img/pages/blazor/wasm/blazordiffusion-tab1.png)
:::

We also use the `EditForm` parameter to customize the edit form for the AutoQueryGrid, so the workflow for editing a Creative is optimized using your own completely custom UI.

```html
<AutoQueryGrid @ref=@grid Model="Creative" Apis="Apis.AutoQuery<QueryCreatives,UpdateCreative,HardDeleteCreative>()"
               ConfigureQuery="ConfigureQuery">
    <EditForm>
        <div class="relative z-10" aria-labelledby="slide-over-title" role="dialog" aria-modal="true">
            <div class="pointer-events-none fixed inset-y-0 right-0 flex max-w-full pl-10 sm:pl-16">
                <CreativeEdit Creative="context" OnClose="grid.OnEditDone" />
            </div>
        </div>
    </EditForm>
```

## Upgrading to .NET 8

[BlazorDiffusion](https://github.com/NetCoreApps/BlazorDiffusionAuto) was an example application we originally developed for .NET 6.
We upgraded the production release of this application to use our [blazor-vue](https://github.com/NetCoreTemplates/blazor-vue) template, which can be perfect for public-facing web applications and teams that don't mind including a JavaScript framework in their application.

However, to show the flexibility of Blazor for .NET 8, we also upgraded the whole application from our updated `blazor-wasm` template to take advantage of the new `InteractiveAuto` mode.

### Component Compatibility

Since the ServiceStack.Blazor library has been updated for .NET 8, we just needed to bring over the shared components from the original application and update the references to the new library.

When upgrading your application pages and components, you will need to avoid any JavaScript interop that runs during the `InitializeAsync` lifecycle method, as this is not supported in the `InteractiveAuto` mode.

### Running on both Server vs Client

When using the `InteractiveAuto` mode, first visits will be running on the server, so your pages and components need to be available to both projects, as well as have any required dependencies registered in both projects `Program.cs` files.

By placing your shared pages and components in a shared project like the `.Client` project in the `blazor-wasm` template, you can easily share them between the two projects.

Look for any of your pages or components that use the `@injects` directive, as these will need to be registered in both projects.

::: info
Avoid sharing sensitive information via dependency injection, as this will be available to the client at runtime which will be able to be decompiled and inspected.
:::

### Source code and live demo

The source code for the upgraded `BlazorDiffusionAuto` application is [available on GitHub](https://github.com/NetCoreApps/BlazorDiffusionAuto) and you can view a live demo of the application at [auto.blazordiffusion.com](https://auto.blazordiffusion.com).

### Conclusion

The new `InteractiveAuto` mode in Blazor for .NET 8 provides the best of both worlds for Blazor applications.
A built in pre-rendering solution means that you can have a fast initial load time, but still have a responsive UI for subsequent visits.

And since the ServiceStack.Blazor components have been updated for .NET 8, you can take advantage of the high-productivity UI components to quickly create customizable and professional-looking admin pages in a Blazor application.

---

<div id="blazor-components" class="hide-title not-prose mt-16 mb-8 ml-20 flex flex-col items-center">
    <div class="flex">
        <svg class="w-40 h-40 text-purple-600 mr-8" xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24"><path fill="currentColor" d="M23.834 8.101a13.912 13.912 0 0 1-13.643 11.72a10.105 10.105 0 0 1-1.994-.12a6.111 6.111 0 0 1-5.082-5.761a5.934 5.934 0 0 1 11.867-.084c.025.983-.401 1.846-1.277 1.871c-.936 0-1.374-.668-1.374-1.567v-2.5a1.531 1.531 0 0 0-1.52-1.533H8.715a3.648 3.648 0 1 0 2.695 6.08l.073-.11l.074.121a2.58 2.58 0 0 0 2.2 1.048a2.909 2.909 0 0 0 2.695-3.04a7.912 7.912 0 0 0-.217-1.933a7.404 7.404 0 0 0-14.64 1.603a7.497 7.497 0 0 0 7.308 7.405s.549.05 1.167.035a15.803 15.803 0 0 0 8.475-2.528c.036-.025.072.025.048.061a12.44 12.44 0 0 1-9.69 3.963a8.744 8.744 0 0 1-8.9-8.972a9.049 9.049 0 0 1 3.635-7.247a8.863 8.863 0 0 1 5.229-1.726h2.813a7.915 7.915 0 0 0 5.839-2.578a.11.11 0 0 1 .059-.034a.112.112 0 0 1 .12.053a.113.113 0 0 1 .015.067a7.934 7.934 0 0 1-1.227 3.549a.107.107 0 0 0-.014.06a.11.11 0 0 0 .073.095a.109.109 0 0 0 .062.004a8.505 8.505 0 0 0 5.913-4.876a.155.155 0 0 1 .055-.053a.15.15 0 0 1 .147 0a.153.153 0 0 1 .054.053A10.779 10.779 0 0 1 23.834 8.1zM8.895 11.628a2.188 2.188 0 1 0 2.188 2.188v-2.042a.158.158 0 0 0-.15-.15Z"/></svg>
        <svg class="w-44 h-44" xmlns="http://www.w3.org/2000/svg" width="256" height="154" viewBox="0 0 256 154"><defs><linearGradient id="logosTailwindcssIcon0" x1="-2.778%" x2="100%" y1="32%" y2="67.556%"><stop offset="0%" stop-color="#2298BD"/><stop offset="100%" stop-color="#0ED7B5"/></linearGradient></defs><path fill="url(#logosTailwindcssIcon0)" d="M128 0C93.867 0 72.533 17.067 64 51.2C76.8 34.133 91.733 27.733 108.8 32c9.737 2.434 16.697 9.499 24.401 17.318C145.751 62.057 160.275 76.8 192 76.8c34.133 0 55.467-17.067 64-51.2c-12.8 17.067-27.733 23.467-44.8 19.2c-9.737-2.434-16.697-9.499-24.401-17.318C174.249 14.743 159.725 0 128 0ZM64 76.8C29.867 76.8 8.533 93.867 0 128c12.8-17.067 27.733-23.467 44.8-19.2c9.737 2.434 16.697 9.499 24.401 17.318C81.751 138.857 96.275 153.6 128 153.6c34.133 0 55.467-17.067 64-51.2c-12.8 17.067-27.733 23.467-44.8 19.2c-9.737-2.434-16.697-9.499-24.401-17.318C110.249 91.543 95.725 76.8 64 76.8Z"/></svg>
    </div>
    <h2 class="border-none text-4xl sm:text-5xl md:text-6xl tracking-tight font-extrabold">
        <span class="text-purple-600 mr-6">Blazor</span>
        <span class="mr-6" style="color:#44A8B3">Tailwind</span>
    </h2>
</div>

### Blazor Tailwind Components

[Tailwind](https://tailwindcss.com) has quickly become the best modern CSS framework we've used to create scalable, 
[mobile-first responsive](https://tailwindcss.com/#mobile-first) websites built upon a beautiful expert-crafted constraint-based 
[Design System](https://tailwindcss.com/#constraint-based) that enabled effortless reuse of a growing suite of [Free Community](https://tailwindcomponents.com)
and professionally-designed [Tailwind UI Component Libraries](https://tailwindui.com) which has proven invaluable in quickly creating beautiful websites & docs
that have benefited all our new modern jamstacks.net templates.

[![](/img/pages/blazor/tailwindui.png)](https://tailwindui.com)

### ServiceStack.Blazor Components

Many of Tailwind UI's popular components are encapsulated in ServiceStack.Blazor's righ high-level tailwind components to enable the rapid development of CRUD UIs in Blazor Server and WASM Apps:

<div class="my-8 flex justify-center">
    <lite-youtube class="w-full mx-4 my-4" width="560" height="315" videoid="iKpQI2233nY" style="background-image: url('https://img.youtube.com/vi/iKpQI2233nY/maxresdefault.jpg')"></lite-youtube>
</div>

<div id="blazor-component-gallery" class="mt-16 relative bg-white py-4">
  <div class="mx-auto max-w-md px-4 text-center sm:max-w-3xl sm:px-6 lg:max-w-7xl lg:px-8">
    <p class="mt-2 text-3xl font-extrabold tracking-tight text-gray-900 dark:text-gray-50 sm:text-4xl">Blazor Gallery</p>
    <p class="mx-auto mt-5 max-w-prose text-xl text-gray-500">
      Discover ServiceStack.Blazor Rich UI Components and Integrated Features
    </p>
  </div>
</div>

[![](/img/pages/blazor/gallery-splash.png)](https://blazor-gallery.servicestack.net)

ServiceStack.Blazor Components support both hosting models which sees Blazor Gallery running on both **Blazor Server** and **WASM**:

<div class="not-prose mb-16 mx-auto mt-5 max-w-md sm:flex sm:justify-center md:mt-8">
  <div class="rounded-md shadow">
    <a href="https://blazor-gallery.servicestack.net" class="flex w-full items-center justify-center rounded-md border border-transparent bg-indigo-600 px-8 py-3 text-base font-medium text-white hover:bg-indigo-700 md:py-4 md:px-10 md:text-lg hover:no-underline">
      Blazor Server
    </a>
  </div>
  <div class="mt-3 rounded-md shadow sm:mt-0 sm:ml-3">
    <a href="https://blazor-gallery.jamstacks.net" class="flex w-full items-center justify-center rounded-md border border-transparent bg-white px-8 py-3 text-base font-medium text-indigo-600 hover:bg-gray-50 md:py-4 md:px-10 md:text-lg hover:no-underline">
      Blazor WASM
    </a>
  </div>
</div>

For a closer look at ServiceStack.Blazor Components in action, download & run them to see how good they'll run in your Environment:

<div class="flex flex-col">
  <a href="https://github.com/NetCoreApps/BlazorGallery" class="flex text-xl text-gray-800">
    <svg class="w-6 h-6 mr-2 align-text-bottom" xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24"><path fill="currentColor" d="M12 .297c-6.63 0-12 5.373-12 12c0 5.303 3.438 9.8 8.205 11.385c.6.113.82-.258.82-.577c0-.285-.01-1.04-.015-2.04c-3.338.724-4.042-1.61-4.042-1.61C4.422 18.07 3.633 17.7 3.633 17.7c-1.087-.744.084-.729.084-.729c1.205.084 1.838 1.236 1.838 1.236c1.07 1.835 2.809 1.305 3.495.998c.108-.776.417-1.305.76-1.605c-2.665-.3-5.466-1.332-5.466-5.93c0-1.31.465-2.38 1.235-3.22c-.135-.303-.54-1.523.105-3.176c0 0 1.005-.322 3.3 1.23c.96-.267 1.98-.399 3-.405c1.02.006 2.04.138 3 .405c2.28-1.552 3.285-1.23 3.285-1.23c.645 1.653.24 2.873.12 3.176c.765.84 1.23 1.91 1.23 3.22c0 4.61-2.805 5.625-5.475 5.92c.42.36.81 1.096.81 2.22c0 1.606-.015 2.896-.015 3.286c0 .315.21.69.825.57C20.565 22.092 24 17.592 24 12.297c0-6.627-5.373-12-12-12"/></svg>
    <span>NetCoreApps/BlazorGallery</span>
  </a>
  <a href="https://github.com/NetCoreApps/BlazorGalleryWasm" class="flex mt-2 text-xl text-gray-800">
    <svg class="w-6 h-6 mr-2 align-text-bottom" xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24"><path fill="currentColor" d="M12 .297c-6.63 0-12 5.373-12 12c0 5.303 3.438 9.8 8.205 11.385c.6.113.82-.258.82-.577c0-.285-.01-1.04-.015-2.04c-3.338.724-4.042-1.61-4.042-1.61C4.422 18.07 3.633 17.7 3.633 17.7c-1.087-.744.084-.729.084-.729c1.205.084 1.838 1.236 1.838 1.236c1.07 1.835 2.809 1.305 3.495.998c.108-.776.417-1.305.76-1.605c-2.665-.3-5.466-1.332-5.466-5.93c0-1.31.465-2.38 1.235-3.22c-.135-.303-.54-1.523.105-3.176c0 0 1.005-.322 3.3 1.23c.96-.267 1.98-.399 3-.405c1.02.006 2.04.138 3 .405c2.28-1.552 3.285-1.23 3.285-1.23c.645 1.653.24 2.873.12 3.176c.765.84 1.23 1.91 1.23 3.22c0 4.61-2.805 5.625-5.475 5.92c.42.36.81 1.096.81 2.22c0 1.606-.015 2.896-.015 3.286c0 .315.21.69.825.57C20.565 22.092 24 17.592 24 12.297c0-6.627-5.373-12-12-12"/></svg>
    <span>NetCoreApps/BlazorGalleryWasm</span>
  </a>
</div>

<div class="my-16 px-4 sm:px-6">
    <div class="text-center">
        <h1 class="text-4xl sm:text-5xl md:text-6xl tracking-tight font-extrabold text-gray-900">
            <span class="block">
                Creating Beautiful <span class="text-purple-600">Blazor Apps</span>
            </span>
            <span style="color:#44A8B3" class="block">with Tailwind</span>
        </h1>
    </div>
        <p class="mx-auto mt-5 max-w-prose text-xl text-gray-500"> 
            Preview the highly productive development model of the new Blazor Tailwind 
            template showing how easy it is to utilize beautifully designed components
        </p>
    <div class="my-8">
        <lite-youtube class="w-full mx-4 my-4" width="560" height="315" videoid="3gD_MMcYI-4" style="background-image: url('https://img.youtube.com/vi/3gD_MMcYI-4/maxresdefault.jpg')"></lite-youtube>
    </div>    
</div>


<div class="relative bg-white py-4 mt-12">
    <div class="mx-auto max-w-md px-4 text-center sm:max-w-3xl sm:px-6 lg:max-w-7xl lg:px-8">
        <p class="mt-2 text-3xl font-extrabold tracking-tight text-gray-900 dark:text-gray-50 sm:text-4xl">Blazor Components</p>
        <p class="mx-auto mt-5 max-w-prose text-xl text-gray-500"> 
            Rich, themable UI Component Library with declarative contextual Validation
        </p>
    </div>
</div>

To maximize productivity the template utilizes the **ServiceStack.Blazor** library containing integrated functionality for Blazor including an optimal JSON API HttpClient Factory, API-enabled base components and a rich library of Tailwind & Bootstrap UI Input components with integrated contextual validation support 
of ServiceStack's [structured Error responses](/error-handling) heavily utilized throughout each project template.

### Blazor Tailwind UI Components

The Built-in UI Components enable a clean & productive dev model, which as of this release include:

| Component         | Description                                                                       |
|-------------------|-----------------------------------------------------------------------------------|
| `<TextInput>`     | Text Input control for string properties                                          |
| `<DateTimeInput>` | Date Input control for Date properties                                            |
| `<CheckboxInput>` | Checkbox Input control for Boolean properties                                     |
| `<SelectInput>`   | Select Dropdown for properties with finite list of values like Enums              |
| `<TextAreaInput>` | Text Input control for large strings                                              |
| `<DynamicInput>`  | Dynamic component utilizing the appropriate above Input controls in Auto Forms    |
| `<AlertSuccess>`  | Displaying successful notification feedback                                       |
| `<ErrorSummary>`  | Displaying error summary message when no contextual field validation is available |
| `<FileUpload>`    | Used with `FilesUploadFeature` and `UploadTo` attribute to upload files           |


The Tailwind & Bootstrap components share the same functionally equivalent base classes that can be easily swapped when switching CSS frameworks by updating its namespace in your App's `_Imports.razor`.

```csharp
@using ServiceStack.Blazor.Components.Tailwind
//@using ServiceStack.Blazor.Components.Bootstrap
```

#### Themable 

Should it be needed, their decoupled design also allows easy customization by running the included [README.ss](https://github.com/LegacyTemplates/blazor-wasm/blob/main/MyApp.Client/Shared/Components/README.ss) executable documentation to copy each controls **Razor** UI markup locally into your project, enabling easy customization of all UI input controls.

### Bookings CRUD Example

To demonstrate ServiceStack's clean & highly productive Blazor dev model, we'll walk through implementing the [AutoQuery Bookings CRUD](/autoquery/crud-bookings) example in Blazor.

Since we're using [AutoQuery CRUD](/autoquery/crud) we only need to define the Request DTO with the input fields we want the user to populate in our `Booking` RDBMS table in [Bookings.cs](https://github.com/NetCoreTemplates/blazor/blob/main/MyApp.ServiceModel/Bookings.cs):

```csharp
[Tag("bookings"), Description("Create a new Booking")]
[Route("/bookings", "POST")]
[ValidateHasRole("Employee")]
[AutoApply(Behavior.AuditCreate)]
public class CreateBooking : ICreateDb<Booking>, IReturn<IdResponse>
{
    [Description("Name this Booking is for"), ValidateNotEmpty]
    public string Name { get; set; }
    public RoomType RoomType { get; set; }
    [ValidateGreaterThan(0)]
    public int RoomNumber { get; set; }
    [ValidateGreaterThan(0)]
    public decimal Cost { get; set; }
    public DateTime BookingStartDate { get; set; }
    public DateTime? BookingEndDate { get; set; }
    [Input(Type = "textarea")]
    public string? Notes { get; set; }
}
```

Where we make use of [Declarative Validation](/declarative-validation) attributes to define the custom validation rules for this API.

::: tip
The `[Tag]`, `[Description]` and `[Input]` attributes are optional to markup how this API appears in ServiceStack's built-in [API Explorer](/api-explorer.html#details-tab) and [Locode UIs](/locode/declarative)
:::

### Blazor WASM App

Thanks to ServiceStack's [Recommended Project Structure](/physical-project-structure) no any additional classes are needed as we're able to bind UI Controls directly to our typed server `CreateBooking` Request DTO used to define the API in 
[BookingsCrud/Create.razor](https://github.com/LegacyTemplates/blazor-wasm/blob/main/MyApp.Client/Pages/BookingsCrud/Create.razor):

```csharp
<form @onsubmit="_ => OnSubmit()" @onsubmit:preventDefault>
<CascadingValue Value=@api.Error>
<div class=@CssUtils.ClassNames("shadow overflow-hidden sm:rounded-md bg-white", @class)>
    <div class="relative px-4 py-5 bg-white sm:p-6">
        <CloseButton OnClose="close" />
        <fieldset>
            <legend class="text-base font-medium text-gray-900 text-center mb-4">New Booking</legend>

            <ErrorSummary Except=@VisibleFields />

            <div class="grid grid-cols-6 gap-6">
                <div class="col-span-6 sm:col-span-3">
                    <TextInput @bind-Value="request.Name" required placeholder="Name for this booking" />
                </div>

                <div class="col-span-6 sm:col-span-3">
                    <SelectInput @bind-Value="request.RoomType" Options=@(Enum.GetValues<RoomType>()) /> 
                </div>

                <div class="col-span-6 sm:col-span-3">
                    <TextInput type="number" @bind-Value="request.RoomNumber" min="0" required />
                </div>

                <div class="col-span-6 sm:col-span-3">
                    <TextInput type="number" @bind-Value="request.Cost" min="0" required />
                </div>

                <div class="col-span-6 sm:col-span-3">
                    <DateTimeInput @bind-Value="request.BookingStartDate" required />
                </div>
                <div class="col-span-6 sm:col-span-3">
                    <DateTimeInput @bind-Value="request.BookingEndDate" />
                </div>
    
                <div class="col-span-6">
                    <TextAreaInput @bind-Value="request.Notes" placeholder="Notes about this booking" />
                </div>
            </div>
        </fieldset>
    </div>
</div>
</CascadingValue>
</form>

@code {
    [Parameter] public EventCallback<IdResponse> done { get; set; }
    [Parameter] public string? @class { get; set; }

    CreateBooking request = new() {
        BookingStartDate = DateTime.UtcNow,
    };

    // Hide Error Summary Messages for Visible Fields which displays contextual validation errors
    string[] VisibleFields => new[] {
        nameof(request.Name), 
        nameof(request.RoomType), 
        nameof(request.RoomNumber), 
        nameof(request.BookingStartDate),
        nameof(request.BookingEndDate), 
        nameof(request.Cost), 
        nameof(request.Notes),
    };

    ApiResult<IdResponse> api = new();

    async Task OnSubmit()
    {
        api = await ApiAsync(request);

        if (api.Succeeded)
        {
            await done.InvokeAsync(api.Response!);
            request = new();
        }
    }

    async Task close() => await done.InvokeAsync(null);
}
```

Calling ServiceStack APIs requires no additional code-gen or boilerplate where the populated Request DTO can be sent as-is using the
[JsonApiClient Api methods](/csharp-client#high-level-api-and-apiasync-methods) which returns an encapsulated successful API or structured error response 
in its typed `ApiResult<T>`.

The UI validation binding uses Blazor's `<CascadingValue>` to propagate any `api.error` responses down to the child Input components.

That's all there's to it, we use [Tailwind's CSS Grid classes](https://tailwindcss.com/docs/grid-template-columns) to define our UI layout which shows each control in its own row for mobile UIs or 2 fields per row in resolutions larger than the [Tailwind's sm: responsive breakpoint](https://tailwindcss.com/docs/responsive-design) to render our beautiful Bookings Form:

<div class="mx-auto max-w-screen-md text-center py-8">
    <img src="/img/pages/blazor/bookings-create.png">
</div>

Which utilizes both client and server validation upon form submission, displaying UX friendly contextual errors under each field when they violate any server [declarative validation](/declarative-validation) or Client UI **required** rules:

<div class="mx-auto max-w-screen-md text-center py-8">
        <img src="/img/pages/blazor/bookings-create-validation.png">
</div>

## Optimal Development Workflow

Utilizing Blazor WebAssembly (WASM) with a ServiceStack backend yields an optimal frictionless [API First development model](/api-first-development) where UIs can bind directly to Typed DTOs whilst benefiting from ServiceStack's [structured error handling](/validation) & rich contextual form validation binding.

By utilizing ServiceStack's [decoupled project structure](/physical-project-structure), combined with Blazor enabling C# on the client, we're able to get 100% reuse of your APIs shared DTOs as-is to enable an end-to-end Typed API automatically free from any additional tooling or code-gen complexity.

<lite-youtube class="w-full mx-4 my-4" width="560" height="315" videoid="BcQqCzm4tK0" style="background-image: url('https://img.youtube.com/vi/BcQqCzm4tK0/maxresdefault.jpg')"></lite-youtube>

## Api and ApiAsync methods

.NET was originally conceived to use Exceptions for error control flow however there's been a tendency in modern languages & libraries to shun Exceptions and return errors as normal values, an approach we believe is a more flexible & ergonomic way to handle API responses.

### The ApiResult way

The `Api(Request)` and `ApiAsync(Request)` APIs returns a typed `ApiResult<Response>` Value Result encapsulating either a Typed Response or a structured API Error populated in `ResponseStatus` allowing you to handle API responses programmatically without `try/catch` handling:

The below example code to create a new Booking:

```csharp
CreateBooking request = new();

ApiResult<IdResponse> api = new();

async Task OnSubmit()
{
    api = await Client.ApiAsync(request);

    if (api.Succeeded)
    {
        await done.InvokeAsync(api.Response!);
        request = new();
    }
}
```

Which despite its terseness handles both **success** and **error** API responses, **if successful** it invokes the `done()` callback notifying its parent of the new Booking API Response before resetting the Form's data model with a new Request DTO.

Upon **failure** the error response is populated in `api.Error` which binds to the UI via Blazor's `<CascadingValue Value=@api.Error>` to propagate it to all its child components in order to show contextual validation errors next to their respective Input controls.

## JSON API Client

The recommended way for configuring a Service Client to use in your Blazor WASM Apps is to use `AddBlazorApiClient()`, e.g:

```csharp
builder.Services.AddBlazorApiClient(builder.Configuration["ApiBaseUrl"] ?? builder.HostEnvironment.BaseAddress);
```

Which registers a typed Http Client factory returning a recommended pre-configured `JsonApiClient` to communicate with your back-end ServiceStack APIs including support for CORS, required when hosting the decoupled UI on a different server (e.g. CDN) to your server. 

If you're deploying your Blazor WASM UI to a CDN you'll need to specify the URL for the server, otherwise if it's deployed together with your Server App you can use the Host's Base Address.

### Public Pages & Components

To reduce boiler plate, your Blazor Pages & components can inherit the templates local [AppComponentBase.cs](https://github.com/NetCoreTemplates/blazor-wasm/blob/main/MyApp.Client/AppComponentBase.cs) which inherits `BlazorComponentBase` which gets injected with the `JsonApiClient` and provides short-hand access to its most common APIs:

```csharp
public class BlazorComponentBase : ComponentBase, IHasJsonApiClient
{
    [Inject]
    public JsonApiClient? Client { get; set; }

    public virtual Task<ApiResult<TResponse>> ApiAsync<TResponse>(IReturn<TResponse> request)  => Client!.ApiAsync(this, request);
    public virtual Task<ApiResult<EmptyResponse>> ApiAsync(IReturnVoid request) => Client!.ApiAsync(this, request);
    public virtual Task<TResponse> SendAsync<TResponse>(IReturn<TResponse> request) => Client!.SendAsync(this, request);
}
```

### Protected Pages & Components

Pages and Components requiring Authentication should inherit from [AppAuthComponentBase](https://github.com/NetCoreTemplates/blazor-wasm/blob/main/MyApp.Client/AppComponentBase.cs) instead which integrates with Blazor's Authentication Model to provide access to the currently authenticated user:

```csharp
public abstract class AppAuthComponentBase : AppComponentBase
{
    [CascadingParameter]
    protected Task<AuthenticationState>? AuthenticationStateTask { get; set; }

    protected bool HasInit { get; set; }

    protected bool IsAuthenticated => User?.Identity?.IsAuthenticated ?? false;

    protected ClaimsPrincipal? User { get; set; }

    protected override async Task OnParametersSetAsync()
    {
        var state = await AuthenticationStateTask!;
        User = state.User;
        HasInit = true;
    }
}
```

## Benefits of Shared DTOs

Typically with Web Apps, our client is using a different language to C#, so an equivalent request DTOs need to be generated for the client.

### TypeScript Example

For example, TypeScript generated DTOs still give us typed end-to-end services with the help of tooling like [Add ServiceStack Reference](/add-servicestack-reference)

```csharp
[Route("/hello/{Name}")]
public class Hello : IReturn<HelloResponse>
{
    public string Name { get; set; }
}

public class HelloResponse
{
    public string Result { get; set; }
}
```

Turns into:

```typescript
// @Route("/hello/{Name}")
export class Hello implements IReturn<HelloResponse>
{
    public name: string;

    public constructor(init?: Partial<Hello>) { (Object as any).assign(this, init); }
    public getTypeName() { return 'Hello'; }
    public getMethod() { return 'POST'; }
    public createResponse() { return new HelloResponse(); }
}

export class HelloResponse
{
    public result: string;
    public responseStatus: ResponseStatus;

    public constructor(init?: Partial<HelloResponse>) { (Object as any).assign(this, init); }
}
```

When Request or Response DTOs changes during development, the client DTOs need to be regenerated using a command like [`x csharp`](./add-servicestack-reference.md#simple-command-line-utilities).

### Blazor WASM Example

Developing your Blazor WASM UI however, you just change your shared request/response DTO in the shared `ServiceModel` project, and both your client and server compile against the same request/response DTO classes.
This eliminates the need for any additional step.

In the `ServiceModel` project, we still have:

```csharp
[Route("/hello/{Name}")]
public class Hello : IReturn<HelloResponse>
{
    public string Name { get; set; }
}

public class HelloResponse
{
    public string Result { get; set; }
}
```

Which the Blazor C# App can use directly in its **.razor** pages:

```csharp
@code {
    Hello request = new()
    {
        Name = "Blazor WASM"
    };

    ApiResult<HelloResponse> api = new();

    protected override async Task OnInitializedAsync() => await submit();

    async Task submit() => api = await ApiAsync(request);
}
```

### FileUpload Control

The File Upload UI component used in the [File Blazor Demo](/locode/files-blazor) has been extracted into a reusable Blazor component you can utilize in your own apps:

![](/img/pages/templates/fileupload-blazor-usage-example.png)

It's a simple control that takes advantage of ServiceStack's declarative [Managed File Uploads](/locode/files-overview) support to effortlessly enable multiple file uploads that can be declaratively added to any Request DTO, which only requires setting 2 properties:

| Property         | Description                                                                                        |
|------------------|----------------------------------------------------------------------------------------------------|
| Request          | Request DTO object instance populated with into to be sent to your endpoint                        |
| FilePropertyName | The name of the property that is used to reference your file, used with the `[UploadTo]` attribute |

#### Example usage

Below is an AutoQuery CRUD API example that references an upload location defined when configuring the [FileUploadFeature Plugin](/locode/files-upload-filesystem.md):

```csharp
public class CreateMyDtoWithFileUpload : ICreateDb<MyDtoWithFileUpload>, IReturn<IdResponse>
{
    [Input(Type="file"), UploadTo("fs")]
    public string FilePath { get; set; }
    
    public string OtherData { get; set; }
}

public class QueryFileUpload : QueryDb<MyDtoWithFileUpload> {}

public class MyDtoWithFileUpload
{
    [AutoIncrement]
    public int Id { get; set; }
    
    public string FilePath { get; set; }
    
    public string OtherData { get; set; }
}
```

When calling this API, the Managed File Uploads feature will upload the HTTP File Upload included in the API request to the configured **fs** upload location and populate the uploaded path to the `FilePath` Request DTO property. 

The Blazor `FileUpload` Control handles the [C# File Upload API Request](/locode/files.html#uploading-files-from-c) by providing the Request DTO instance to send and the DTO property the File Upload should populate:

```html
@page "/file-upload"
<h3>FileUploadPage</h3>

<FileUpload Request="request" FilePropertyName="@nameof(CreateMyDtoWithFileUpload.FilePath)" />

@code {

    // Any additional values should be populated 
    // on the request object before the upload starts.
    CreateMyDtoWithFileUpload request = new() {
        OtherData = "Test"
    };
}
```

![](/img/pages/templates/fileupload-blazor-example.png)

The `FilePropertyName` matches the property name that is annotated by the `UploadTo` attribute. The `Request` is the instance of the Request DTO.

### Existing Template Upgrade for 6.3

If you created a `blazor-tailwind` project using this template before the ServiceStack 6.4 release, you should run the following commands to upgrade your project to use components from `ServiceStack.Blazor` component library which should be run from your `.Client` project:

::: sh
x mix -delete blazor-upgrade-clean
:::

::: sh
x mix blazor-upgrade
:::


# Blazor Server Tailwind Template
Source: https://docs.servicestack.net/templates/blazor-server

<div class="not-prose">
    <div id="blazor-server" class="hide-title mt-12 ml-20 flex flex-col items-center">
        <div class="flex">
            <svg class="w-24 h-24 text-purple-600 mr-8" xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24"><path fill="currentColor" d="M23.834 8.101a13.912 13.912 0 0 1-13.643 11.72a10.105 10.105 0 0 1-1.994-.12a6.111 6.111 0 0 1-5.082-5.761a5.934 5.934 0 0 1 11.867-.084c.025.983-.401 1.846-1.277 1.871c-.936 0-1.374-.668-1.374-1.567v-2.5a1.531 1.531 0 0 0-1.52-1.533H8.715a3.648 3.648 0 1 0 2.695 6.08l.073-.11l.074.121a2.58 2.58 0 0 0 2.2 1.048a2.909 2.909 0 0 0 2.695-3.04a7.912 7.912 0 0 0-.217-1.933a7.404 7.404 0 0 0-14.64 1.603a7.497 7.497 0 0 0 7.308 7.405s.549.05 1.167.035a15.803 15.803 0 0 0 8.475-2.528c.036-.025.072.025.048.061a12.44 12.44 0 0 1-9.69 3.963a8.744 8.744 0 0 1-8.9-8.972a9.049 9.049 0 0 1 3.635-7.247a8.863 8.863 0 0 1 5.229-1.726h2.813a7.915 7.915 0 0 0 5.839-2.578a.11.11 0 0 1 .059-.034a.112.112 0 0 1 .12.053a.113.113 0 0 1 .015.067a7.934 7.934 0 0 1-1.227 3.549a.107.107 0 0 0-.014.06a.11.11 0 0 0 .073.095a.109.109 0 0 0 .062.004a8.505 8.505 0 0 0 5.913-4.876a.155.155 0 0 1 .055-.053a.15.15 0 0 1 .147 0a.153.153 0 0 1 .054.053A10.779 10.779 0 0 1 23.834 8.1zM8.895 11.628a2.188 2.188 0 1 0 2.188 2.188v-2.042a.158.158 0 0 0-.15-.15Z"/></svg>
            <svg class="w-28 h-28" xmlns="http://www.w3.org/2000/svg" width="256" height="154" viewBox="0 0 256 154"><defs><linearGradient id="logosTailwindcssIcon0" x1="-2.778%" x2="100%" y1="32%" y2="67.556%"><stop offset="0%" stop-color="#2298BD"/><stop offset="100%" stop-color="#0ED7B5"/></linearGradient></defs><path fill="url(#logosTailwindcssIcon0)" d="M128 0C93.867 0 72.533 17.067 64 51.2C76.8 34.133 91.733 27.733 108.8 32c9.737 2.434 16.697 9.499 24.401 17.318C145.751 62.057 160.275 76.8 192 76.8c34.133 0 55.467-17.067 64-51.2c-12.8 17.067-27.733 23.467-44.8 19.2c-9.737-2.434-16.697-9.499-24.401-17.318C174.249 14.743 159.725 0 128 0ZM64 76.8C29.867 76.8 8.533 93.867 0 128c12.8-17.067 27.733-23.467 44.8-19.2c9.737 2.434 16.697 9.499 24.401 17.318C81.751 138.857 96.275 153.6 128 153.6c34.133 0 55.467-17.067 64-51.2c-12.8 17.067-27.733 23.467-44.8 19.2c-9.737-2.434-16.697-9.499-24.401-17.318C110.249 91.543 95.725 76.8 64 76.8Z"/></svg>
        </div>
    </div>
    <div class="relative bg-white dark:bg-black py-4">
      <div class="mx-auto max-w-md px-4 text-center sm:max-w-3xl sm:px-6 lg:max-w-7xl lg:px-8">
        <p class="mt-2 text-3xl font-extrabold tracking-tight text-gray-900 dark:text-gray-50 sm:text-4xl">Blazor Server Tailwind Template</p>
        <p class="mx-auto mt-5 max-w-prose text-xl text-gray-500">
          Ultimate dev model & UX ideal for low-latency Intranet environments
        </p>
      </div>
    </div>
    <a href="https://blazor.web-templates.io">
      <div class="block flex justify-center shadow hover:shadow-lg rounded py-1">
        <img class="p-4" src="https://raw.githubusercontent.com/ServiceStack/Assets/master/csharp-templates/blazor.png">
      </div>
    </a>
</div>

[ServiceStack.Blazor's Tailwind Components](/templates/blazor-components) also work flawlessly in [Blazor Server Apps](https://learn.microsoft.com/en-us/aspnet/core/blazor/hosting-models?view=aspnetcore-6.0#blazor-server) which benefits from fast startup and exceptional responsiveness in low latency environments thanks to its architecture of running your App in a server session that only needs to propagate thin UI Virtual DOM updates to clients.

The Blazor Server App template offers a number compelling advantages over Blazor WASM, including:

 - A superior dev model and debugging experience
 - Improved live-reload and faster iterative dev cycles
 - Full access to .NET Server functionality
 - Better start times & UI responsiveness
 - Less complexity from unnecessary client project or pre-rendering solutions

Although [the limitations](https://learn.microsoft.com/en-us/aspnet/core/blazor/hosting-models?view=aspnetcore-6.0#blazor-server) of its highly-coupled stateful server rendering session architecture does make it a poor fit for most high latency Internet sites which we continue to recommend our [Blazor WASM project template](/templates/blazor-tailwind) for.

To better showcase our growing Blazor functionality we've created the new Blazor Gallery websites showcasing usage of available rich Blazor Components for rapidly develop beautiful Tailwind Web Apps:

<div id="blazor-component-gallery" class="relative bg-white dark:bg-black py-4">
  <div class="mx-auto max-w-md px-4 text-center sm:max-w-3xl sm:px-6 lg:max-w-7xl lg:px-8">
    <p class="mt-2 text-3xl font-extrabold tracking-tight text-gray-900 dark:text-gray-50 sm:text-4xl">Blazor Gallery</p>
    <p class="mx-auto mt-5 max-w-prose text-xl text-gray-500">
      Discover ServiceStack.Blazor Rich UI Components and Integrated Features
    </p>
  </div>
</div>

[![](/img/pages/blazor/gallery-splash.png)](https://blazor-gallery.servicestack.net)

As our components support both hosting models we're maintaining identical Gallery sites running on both **Blazor Server** and **WASM**:

<div class="not-prose mb-16 mx-auto mt-5 max-w-md sm:flex sm:justify-center md:mt-8">
  <div class="rounded-md shadow">
    <a href="https://blazor-gallery.servicestack.net" class="flex w-full items-center justify-center rounded-md border border-transparent bg-indigo-600 px-8 py-3 text-base font-medium text-white hover:bg-indigo-700 md:py-4 md:px-10 md:text-lg hover:no-underline">
      Blazor Server
    </a>
  </div>
  <div class="mt-3 rounded-md shadow sm:mt-0 sm:ml-3">
    <a href="https://blazor-gallery.jamstacks.net" class="flex w-full items-center justify-center rounded-md border border-transparent bg-white px-8 py-3 text-base font-medium text-indigo-600 hover:bg-gray-50 md:py-4 md:px-10 md:text-lg hover:no-underline">
      Blazor WASM
    </a>
  </div>
</div>

For a closer look at ServiceStack.Blazor Components in action, download & run them to see how good they'll run in your Environment:

<div class="flex flex-col">
  <a href="https://github.com/NetCoreApps/BlazorGallery" class="flex text-xl text-gray-800">
    <svg class="w-6 h-6 mr-2 align-text-bottom" xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24"><path fill="currentColor" d="M12 .297c-6.63 0-12 5.373-12 12c0 5.303 3.438 9.8 8.205 11.385c.6.113.82-.258.82-.577c0-.285-.01-1.04-.015-2.04c-3.338.724-4.042-1.61-4.042-1.61C4.422 18.07 3.633 17.7 3.633 17.7c-1.087-.744.084-.729.084-.729c1.205.084 1.838 1.236 1.838 1.236c1.07 1.835 2.809 1.305 3.495.998c.108-.776.417-1.305.76-1.605c-2.665-.3-5.466-1.332-5.466-5.93c0-1.31.465-2.38 1.235-3.22c-.135-.303-.54-1.523.105-3.176c0 0 1.005-.322 3.3 1.23c.96-.267 1.98-.399 3-.405c1.02.006 2.04.138 3 .405c2.28-1.552 3.285-1.23 3.285-1.23c.645 1.653.24 2.873.12 3.176c.765.84 1.23 1.91 1.23 3.22c0 4.61-2.805 5.625-5.475 5.92c.42.36.81 1.096.81 2.22c0 1.606-.015 2.896-.015 3.286c0 .315.21.69.825.57C20.565 22.092 24 17.592 24 12.297c0-6.627-5.373-12-12-12"/></svg>
    <span>NetCoreApps/BlazorGallery</span>
  </a>
  <a href="https://github.com/NetCoreApps/BlazorGalleryWasm" class="flex mt-2 text-xl text-gray-800">
    <svg class="w-6 h-6 mr-2 align-text-bottom" xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24"><path fill="currentColor" d="M12 .297c-6.63 0-12 5.373-12 12c0 5.303 3.438 9.8 8.205 11.385c.6.113.82-.258.82-.577c0-.285-.01-1.04-.015-2.04c-3.338.724-4.042-1.61-4.042-1.61C4.422 18.07 3.633 17.7 3.633 17.7c-1.087-.744.084-.729.084-.729c1.205.084 1.838 1.236 1.838 1.236c1.07 1.835 2.809 1.305 3.495.998c.108-.776.417-1.305.76-1.605c-2.665-.3-5.466-1.332-5.466-5.93c0-1.31.465-2.38 1.235-3.22c-.135-.303-.54-1.523.105-3.176c0 0 1.005-.322 3.3 1.23c.96-.267 1.98-.399 3-.405c1.02.006 2.04.138 3 .405c2.28-1.552 3.285-1.23 3.285-1.23c.645 1.653.24 2.873.12 3.176c.765.84 1.23 1.91 1.23 3.22c0 4.61-2.805 5.625-5.475 5.92c.42.36.81 1.096.81 2.22c0 1.606-.015 2.896-.015 3.286c0 .315.21.69.825.57C20.565 22.092 24 17.592 24 12.297c0-6.627-5.373-12-12-12"/></svg>
    <span>NetCoreApps/BlazorGalleryWasm</span>
  </a>
  <a href="https://docs.servicestack.net/vue/" class="flex mt-2 text-xl text-gray-800">
    <svg class="w-6 h-6 mr-2 align-text-bottom" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" aria-hidden="true" role="img" class="w-28 h-28 sm:w-44 sm:h-44 iconify iconify--vscode-icons" width="1em" height="1em" viewBox="0 0 32 32"><path fill="#41b883" d="M24.4 3.925H30l-14 24.15L2 3.925h10.71l3.29 5.6l3.22-5.6Z"></path><path fill="#41b883" d="m2 3.925l14 24.15l14-24.15h-5.6L16 18.415L7.53 3.925Z"></path><path fill="#35495e" d="M7.53 3.925L16 18.485l8.4-14.56h-5.18L16 9.525l-3.29-5.6Z"></path></svg>
    <span>Vue Component Gallery</span>
  </a>
</div>

<p class="hide-h2"></p>

## Getting Started

Customize and Download a new Blazor WASM Bootstrap project with your preferred project name:

<h3 class="text-center">Download new C# Blazor Project</h3>

<blazor-templates class="not-prose pb-8"></blazor-templates>

Alternatively you can create & download a new Blazor Project with the [x dotnet tool](/dotnet-new):

:::sh
x new blazor ProjectName
:::


## Universal Blazor Components

Blazor Server has become our preferred platform for Interactive **Intranet** Apps which excels in **low-latency environments** to enable a best-in-class responsive end-user UX that also offers a superior development experience in Visual Studio's live reload where it enables a fast iterative development workflow and good debugging experience.

A fantastic property of Blazor is its support for multiple hosting modes which allows the same components from being able to run in the Browser with Blazor WASM or rendered on the Server with Blazor Server. But whilst Blazor is capable of it, this trait is typically conceded in most Apps with database access where it recommends using
[EF Core directly in Blazor components](https://learn.microsoft.com/en-us/aspnet/core/blazor/blazor-server-ef-core?view=aspnetcore-7.0) - effectively prohibiting reuse in Blazor WASM should you ever want to utilize Blazor's preferred hosting model for hosting your Blazor App's on the Internet.

<div class="my-8 flex justify-center">
    <lite-youtube class="w-full mx-4 my-4" width="560" height="315" videoid="66DgLHExC9E" style="background-image: url('https://img.youtube.com/vi/66DgLHExC9E/maxresdefault.jpg')"></lite-youtube>
</div>

## Blazing Fast Networkless APIs

Whilst better performing, having Blazor components access DB's directly encourages a more tightly-coupled and less reusable & testable architecture than the traditional well-defined API dev model used in client/server Mobile & Desktop Apps or Web SPA Apps like WASM.

To achieve the best of both worlds, we've enabled support for utilizing the In Process [Service Gateway](/service-gateway) in Blazor Server Apps which lets you retain the traditional client/server dev model for invoking your Server APIs **In Process** - avoiding any serialization, HTTP networking or even Kestrel middleware overhead to invoke your APIs directly!

This enables using the **exact same source code** to call APIs in Blazor Server and WASM which allows us to develop reusable Blazor Components to invoke the same Server APIs that serve Web, Mobile and Desktop Apps in Blazor Server Apps. Where instead of using HttpClient to invoke your APIs, they're invoked directly from a C# method which will preserve its StackTrace where you'll be able to track the API call down to the Blazor UI component calling it.

ServiceStack's [Message-based API Design](/api-design) makes it possible for all API calls in ServiceStack.Blazor components and project templates to be routed through these 2 methods:

```csharp
public interface IServiceGatewayAsync
{
  Task<TResponse> SendAsync<TResponse>(object dto, CancellationToken ct=default);
  //...
}

public interface IServiceGatewayFormAsync
{
  Task<TResponse> SendFormAsync<TResponse>(object dto, MultipartFormDataContent form, CancellationToken ct);
}
```

::: info
The `SendFormAsync` API is a new method added to support multi-part API requests with File Uploads
:::

Which allows the HTTP `JsonApiClient` and networkless `InProcessGateway` clients to be used interchangeably. By default Blazor Server Apps now use the InProcess Gateway but can be switched over to invoke APIs using the HTTP `JsonApiClient` with:

```csharp
BlazorConfig.Set(new() {
    UseInProcessClient = false
});
```

Which changes all `Api*` methods in Blazor components and Pages inheriting ServiceStack.Blazor's [BlazorComponentBase](https://reference.servicestack.net/api/ServiceStack.Blazor/BlazorComponentBase) to use the registered `JsonApiClient` client.

Other components can access both the InProcess Gateway or `JsonApiClient` by injecting the `IClientFactory` dependency into their components, e.g:

```csharp
public class MyComponent : ComponentBase
{
    [Inject] public IClientFactory? ClientFactory { get; set; }

    public IServiceGateway Gateway => ClientFactory!.GetGateway();
    public JsonApiClient Client => ClientFactory!.GetClient();
}
```

This capability is what has made it possible for high-level "API-enabled" components like [AutoQuery Grids](https://blazor-gallery.jamstacks.net/grid) and [AutoForm](https://blazor-gallery.jamstacks.net/gallery/autoform) to support both Blazor Server and Blazor WASM utilizing the most efficient API client available to its platform.

The Blazor Gallery websites themselves are also good demonstrations of being able to run **entire Web Apps** in both Blazor Server and WASM, with all development being done with Blazor Server to take advantage of its superior iterative dev model then a script is used to "export" all pages to an identical Blazor WASM project.

## Api and ApiAsync methods

.NET was originally conceived to use Exceptions for error control flow however there's been a tendency in modern languages & libraries to shun Exceptions and return errors as normal values, an approach we believe is a more flexible & ergonomic way to handle API responses.

### The ApiResult way

The `Api(Request)` and `ApiAsync(Request)` APIs returns a typed `ApiResult<Response>` Value Result encapsulating either a Typed Response or a structured API Error populated in `ResponseStatus` allowing you to handle API responses programmatically without `try/catch` handling:

The below example code to create a new Booking:

```csharp
CreateBooking request = new();

ApiResult<IdResponse> api = new();

async Task OnSubmit()
{
    api = await Client.ApiAsync(request);

    if (api.Succeeded)
    {
        await done.InvokeAsync(api.Response!);
        request = new();
    }
}
```

Which despite its terseness handles both **success** and **error** API responses, **if successful** it invokes the `done()` callback notifying its parent of the new Booking API Response before resetting the Form's data model with a new Request DTO.

Upon **failure** the error response is populated in `api.Error` which binds to the UI via Blazor's `<CascadingValue Value=@api.Error>` to propagate it to all its child components in order to show contextual validation errors next to their respective Input controls.

### Public Pages & Components

To reduce boiler plate, your Blazor Pages & components can inherit the templates local [AppComponentBase.cs](https://github.com/NetCoreTemplates/blazor-wasm/blob/main/MyApp.Client/AppComponentBase.cs) which inherits `BlazorComponentBase` that gets injected with the `IClientFactory` and provides convenient access to most common APIs:

```csharp
public class BlazorComponentBase : ComponentBase, IHasJsonApiClient
{
    [Inject] public IClientFactory? ClientFactory { get; set; }
    public IServiceGateway Gateway => ClientFactory!.GetGateway();
    public JsonApiClient Client => ClientFactory!.GetClient();

    public virtual Task<ApiResult<TResponse>> ApiAsync<TResponse>(IReturn<TResponse> request) => UseGateway
        ? Gateway.ManagedApiAsync(request)
        : Client.ManagedApiAsync(request);

    public virtual Task<ApiResult<EmptyResponse>> ApiAsync(IReturnVoid request); /*...*/
    public virtual Task<TResponse> SendAsync<TResponse>(IReturn<TResponse> request);
    public virtual Task<IHasErrorStatus> ApiAsync<Model>(object request);
    public virtual Task<ApiResult<Model>> ApiFormAsync<Model>(object requestDto, MultipartFormDataContent request);
}
```

### Protected Pages & Components

Pages and Components requiring Authentication should inherit from [AppAuthComponentBase](https://github.com/NetCoreTemplates/blazor-wasm/blob/main/MyApp.Client/AppComponentBase.cs) instead which integrates with Blazor's Authentication Model to provide access to the currently authenticated user:

```csharp
public abstract class AppAuthComponentBase : AppComponentBase
{
    [CascadingParameter]
    protected Task<AuthenticationState>? AuthenticationStateTask { get; set; }

    protected bool HasInit { get; set; }

    protected bool IsAuthenticated => User?.Identity?.IsAuthenticated ?? false;

    protected ClaimsPrincipal? User { get; set; }

    protected override async Task OnParametersSetAsync()
    {
        var state = await AuthenticationStateTask!;
        User = state.User;
        HasInit = true;
    }
}
```

## Benefits of Shared DTOs

Typically with Web Apps, our client is using a different language to C#, so an equivalent request DTOs need to be generated for the client.

### TypeScript Example

For example, TypeScript generated DTOs still give us typed end-to-end services with the help of tooling like [Add ServiceStack Reference](/add-servicestack-reference)

```csharp
[Route("/hello/{Name}")]
public class Hello : IReturn<HelloResponse>
{
    public string Name { get; set; }
}

public class HelloResponse
{
    public string Result { get; set; }
}
```

Turns into:

```typescript
// @Route("/hello/{Name}")
export class Hello implements IReturn<HelloResponse>
{
    public name: string;

    public constructor(init?: Partial<Hello>) { (Object as any).assign(this, init); }
    public getTypeName() { return 'Hello'; }
    public getMethod() { return 'POST'; }
    public createResponse() { return new HelloResponse(); }
}

export class HelloResponse
{
    public result: string;
    public responseStatus: ResponseStatus;

    public constructor(init?: Partial<HelloResponse>) { (Object as any).assign(this, init); }
}
```

When Request or Response DTOs changes during development, the client DTOs need to be regenerated using a command like [`x csharp`](./add-servicestack-reference.md#simple-command-line-utilities).

### Blazor Server Example

Developing your Blazor Server UI however, you just change your shared request/response DTO in the shared `ServiceModel` project, and both your client and server compile against the same request/response DTO classes.
This eliminates the need for any additional step.

In the `ServiceModel` project, we still have:

```csharp
[Route("/hello/{Name}")]
public class Hello : IReturn<HelloResponse>
{
    public string Name { get; set; }
}

public class HelloResponse
{
    public string Result { get; set; }
}
```

Which the Blazor C# App can use directly in its **.razor** pages:

```csharp
@code {
    Hello request = new()
    {
        Name = "Blazor WASM"
    };

    ApiResult<HelloResponse> api = new();

    protected override async Task OnInitializedAsync() => await submit();

    async Task submit() => api = await ApiAsync(request);
}
```

## ServiceStack.Blazor Components

The [ServiceStack.Blazor Components library](/templates/blazor-components) contains integrated functionality for Blazor including API-enabled base components, HTML Utils and Tailwind UI Input components heavily utilized throughout the template.


# Blazor WASM Bootstrap
Source: https://docs.servicestack.net/templates/blazor-bootstrap

<div class="not-prose hide-title my-8 ml-20 flex flex-col items-center">
    <div>
        <svg class="w-44 h-44 text-purple-600 mr-8" xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24"><path fill="currentColor" d="M23.834 8.101a13.912 13.912 0 0 1-13.643 11.72a10.105 10.105 0 0 1-1.994-.12a6.111 6.111 0 0 1-5.082-5.761a5.934 5.934 0 0 1 11.867-.084c.025.983-.401 1.846-1.277 1.871c-.936 0-1.374-.668-1.374-1.567v-2.5a1.531 1.531 0 0 0-1.52-1.533H8.715a3.648 3.648 0 1 0 2.695 6.08l.073-.11l.074.121a2.58 2.58 0 0 0 2.2 1.048a2.909 2.909 0 0 0 2.695-3.04a7.912 7.912 0 0 0-.217-1.933a7.404 7.404 0 0 0-14.64 1.603a7.497 7.497 0 0 0 7.308 7.405s.549.05 1.167.035a15.803 15.803 0 0 0 8.475-2.528c.036-.025.072.025.048.061a12.44 12.44 0 0 1-9.69 3.963a8.744 8.744 0 0 1-8.9-8.972a9.049 9.049 0 0 1 3.635-7.247a8.863 8.863 0 0 1 5.229-1.726h2.813a7.915 7.915 0 0 0 5.839-2.578a.11.11 0 0 1 .059-.034a.112.112 0 0 1 .12.053a.113.113 0 0 1 .015.067a7.934 7.934 0 0 1-1.227 3.549a.107.107 0 0 0-.014.06a.11.11 0 0 0 .073.095a.109.109 0 0 0 .062.004a8.505 8.505 0 0 0 5.913-4.876a.155.155 0 0 1 .055-.053a.15.15 0 0 1 .147 0a.153.153 0 0 1 .054.053A10.779 10.779 0 0 1 23.834 8.1zM8.895 11.628a2.188 2.188 0 1 0 2.188 2.188v-2.042a.158.158 0 0 0-.15-.15Z"/></svg>
    </div>
    <h1 class="text-3xl font-extrabold tracking-tight text-gray-900 dark:text-gray-50 sm:text-4xl">Blazor WASM Bootstrap Template</h1>
</div>

The feature-rich Blazor WASM Bootstrap template is ideal for teams with strong C# skills building Line Of Business (LOB) applications.
Utilizing Blazor WebAssembly (WASM) with a ServiceStack backend yields an optimal frictionless [API First development model](/api-first-development) where UIs can bind directly to Typed DTOs whilst benefiting from ServiceStack's [structured error handling](/validation) & rich contextual form validation binding.

<lite-youtube class="w-full mx-4 my-4" width="560" height="315" videoid="TIgjMf_vtCI" style="background-image: url('https://img.youtube.com/vi/TIgjMf_vtCI/maxresdefault.jpg')"></lite-youtube>

## Getting Started

Customize and Download a new Blazor WASM Bootstrap project with your preferred project name:

<h3 class="text-center">Download new C# Blazor WASM Project</h3>

<blazor-templates class="not-prose pb-8"></blazor-templates>

Alternatively you can create & download a new Blazor Project with the [x dotnet tool](/dotnet-new):

:::sh
x new blazor-wasm ProjectName
:::

## Optimal Development Workflow

By utilizing ServiceStack's [decoupled project structure](/physical-project-structure), combined with Blazor enabling C# on the client, we're able to get 100% reuse of your APIs shared DTOs as-is to enable an end-to-end Typed API automatically free from any additional tooling or code-gen complexity.

<lite-youtube class="w-full mx-4 my-4" width="560" height="315" videoid="BcQqCzm4tK0" style="background-image: url('https://img.youtube.com/vi/BcQqCzm4tK0/maxresdefault.jpg')"></lite-youtube>

## Api and ApiAsync methods

.NET was originally conceived to use Exceptions for error control flow however there's been a tendency in modern languages & libraries to shun Exceptions and return errors as normal values, an approach we believe is a more flexible & ergonomic way to handle API responses.

### The ApiResult way

The `Api(Request)` and `ApiAsync(Request)` APIs returns a typed `ApiResult<Response>` Value Result encapsulating either a Typed Response or a structured API Error populated in `ResponseStatus` allowing you to handle API responses programmatically without `try/catch` handling:

The below example code to create a new Booking:

```csharp
CreateBooking request = new();

ApiResult<IdResponse> api = new();

async Task OnSubmit()
{
    api = await Client.ApiAsync(request);

    if (api.Succeeded)
    {
        await done.InvokeAsync(api.Response!);
        request = new();
    }
}
```

Which despite its terseness handles both **success** and **error** API responses, **if successful** it invokes the `done()` callback notifying its parent of the new Booking API Response before resetting the Form's data model with a new Request DTO.

Upon **failure** the error response is populated in `api.Error` which binds to the UI via Blazor's `<CascadingValue Value=@api.Error>` to propagate it to all its child components in order to show contextual validation errors next to their respective Input controls.

## JSON API Client

The recommended way for configuring a Service Client to use in your Blazor WASM Apps is to use `AddBlazorApiClient()`, e.g:

```csharp
builder.Services.AddBlazorApiClient(builder.Configuration["ApiBaseUrl"] ?? builder.HostEnvironment.BaseAddress);
```

Which registers a typed Http Client factory returning a recommended pre-configured `JsonApiClient` to communicate with your back-end ServiceStack APIs including support for CORS, required when hosting the decoupled UI on a different server (e.g. CDN) to your server. 

If you're deploying your Blazor WASM UI to a CDN you'll need to specify the URL for the server, otherwise if it's deployed together with your Server App you can use the Host's Base Address.

### Public Pages & Components

To reduce boiler plate, your Blazor Pages & components can inherit the templates local [AppComponentBase.cs](https://github.com/NetCoreTemplates/blazor-wasm/blob/main/MyApp.Client/AppComponentBase.cs) which inherits `BlazorComponentBase` which gets injected with the `JsonApiClient` and provides short-hand access to its most common APIs:

```csharp
public class BlazorComponentBase : ComponentBase, IHasJsonApiClient
{
    [Inject]
    public JsonApiClient? Client { get; set; }

    public virtual Task<ApiResult<TResponse>> ApiAsync<TResponse>(IReturn<TResponse> request)  => Client!.ApiAsync(this, request);
    public virtual Task<ApiResult<EmptyResponse>> ApiAsync(IReturnVoid request) => Client!.ApiAsync(this, request);
    public virtual Task<TResponse> SendAsync<TResponse>(IReturn<TResponse> request) => Client!.SendAsync(this, request);
}
```

### Protected Pages & Components

Pages and Components requiring Authentication should inherit from [AppAuthComponentBase](https://github.com/NetCoreTemplates/blazor-wasm/blob/main/MyApp.Client/AppComponentBase.cs) instead which integrates with Blazor's Authentication Model to provide access to the currently authenticated user:

```csharp
public abstract class AppAuthComponentBase : AppComponentBase
{
    [CascadingParameter]
    protected Task<AuthenticationState>? AuthenticationStateTask { get; set; }

    protected bool HasInit { get; set; }

    protected bool IsAuthenticated => User?.Identity?.IsAuthenticated ?? false;

    protected ClaimsPrincipal? User { get; set; }

    protected override async Task OnParametersSetAsync()
    {
        var state = await AuthenticationStateTask!;
        User = state.User;
        HasInit = true;
    }
}
```

## Benefits of Shared DTOs

Typically with Web Apps, our client is using a different language to C#, so an equivalent request DTOs need to be generated for the client.

### TypeScript Example

For example, TypeScript generated DTOs still give us typed end-to-end services with the help of tooling like [Add ServiceStack Reference](/add-servicestack-reference)

```csharp
[Route("/hello/{Name}")]
public class Hello : IReturn<HelloResponse>
{
    public string Name { get; set; }
}

public class HelloResponse
{
    public string Result { get; set; }
}
```

Turns into:

```typescript
// @Route("/hello/{Name}")
export class Hello implements IReturn<HelloResponse>
{
    public name: string;

    public constructor(init?: Partial<Hello>) { (Object as any).assign(this, init); }
    public getTypeName() { return 'Hello'; }
    public getMethod() { return 'POST'; }
    public createResponse() { return new HelloResponse(); }
}

export class HelloResponse
{
    public result: string;
    public responseStatus: ResponseStatus;

    public constructor(init?: Partial<HelloResponse>) { (Object as any).assign(this, init); }
}
```

When Request or Response DTOs changes during development, the client DTOs need to be regenerated using a command like [`x csharp`](./add-servicestack-reference.md#simple-command-line-utilities).

### Blazor WASM Example

Developing your Blazor WASM UI however, you just change your shared request/response DTO in the shared `ServiceModel` project, and both your client and server compile against the same request/response DTO classes.
This eliminates the need for any additional step.

In the `ServiceModel` project, we still have:

```csharp
[Route("/hello/{Name}")]
public class Hello : IReturn<HelloResponse>
{
    public string Name { get; set; }
}

public class HelloResponse
{
    public string Result { get; set; }
}
```

Which the Blazor C# App can use directly in its **.razor** pages:

```csharp
@code {
    Hello request = new()
    {
        Name = "Blazor WASM"
    };

    ApiResult<HelloResponse> api = new();

    protected override async Task OnInitializedAsync() => await submit();

    async Task submit() => api = await ApiAsync(request);
}
```

## ServiceStack.Blazor

The **ServiceStack.Blazor** library contains integrated functionality for Blazor including an optimal JSON API HttpClient Factory, API-enabled base components, HTML Utils and Bootstrap & Tailwind UI Input components heavily utilized throughout the template.

### Built-in Blazor and Tailwind UI Components

The Built-in UI Components enable a clean & productive dev model and share the same base classes making them functionally equivalent and can be swapped when switching CSS frameworks by updating its namespace in your projects `_Imports.razor`

The Blazor Components in **ServiceStack.Blazor** include:

| Component         | Description                                                                       |
|-------------------|-----------------------------------------------------------------------------------|
| `<TextInput>`     | Text Input control for string properties                                          |
| `<DateTimeInput>` | Date Input control for Date properties                                            |
| `<CheckboxInput>` | Checkbox Input control for Boolean properties                                     |
| `<SelectInput>`   | Select Dropdown for properties with finite list of values like Enums              |
| `<TextAreaInput>` | Text Input control for large strings                                              |
| `<DynamicInput>`  | Dynamic component utilizing the appropriate above Input controls in Auto Forms    |
| `<AlertSuccess>`  | Displaying successful notification feedback                                       |
| `<ErrorSummary>`  | Displaying error summary message when no contextual field validation is available |
| `<FileUpload>`    | Used with `FilesUploadFeature` and `UploadTo` attribute to upload files           |


::: info
All Input controls support contextual validation of ServiceStack's existing [structured Error responses](/error-handling)
:::

### Themable

Should it be needed, all components are themable by running the included [README.ss](https://github.com/NetCoreTemplates/blazor-wasm/blob/main/MyApp.Client/Shared/Components/README.ss) executable documentation that copies its **Razor** UI markup locally into your project enabling customization of UI including controls.

### Bookings CRUD

The C# Service Client `Api*` methods make calling remote ServiceStack APIs similar to calling a C# method as its returned `ApiResult<Response>` encapsulates both a typed **Error** & API **Response** as an alternate way to handle errors as all components can bind directly to its `api.Error`.

The reusability extends to your APIs typed Request DTOs which components can directly 2-way data bind to.

Below is an example of a CRUD Booking form [BookingsCrud/Create.razor](https://github.com/ServiceStack/ServiceStack/blob/master/tests/ServiceStack.Blazor.Tests/Client/Pages/BookingsCrud/Create.razor) used to Create Bookings:

```html
@attribute [Authorize(Roles="Employee")]
@inherits AppAuthComponentBase

<form @onsubmit="_ => OnSubmit()" @onsubmit:preventDefault 
     class=@CssUtils.ClassNames("relative shadow rounded p-4",@class)>
<CascadingValue Value=@api.Error>
    <button type="button" class="close" @onclick="close"><i></i></button>

    <h1 class="fs-4 text-secondary text-center">
        New Booking
    </h1>

    <ErrorSummary Except=@VisibleFields />

    <div class="mb-3 form-floating">
        <TextInput @bind-Value="request.Name" required placeholder="Name for this booking" />
    </div>

    <div class="mb-3 form-floating">
        <SelectInput @bind-Value="request.RoomType" Options=@(Enum.GetValues<RoomType>()) /> 
    </div>

    <div class="d-flex">
        <div class="mb-3 flex-fill form-floating me-1">
            <TextInput type="number" @bind-Value="request.RoomNumber" min="0" required />
        </div>

        <div class="mb-3 flex-fill form-floating">
            <TextInput type="number" @bind-Value="request.Cost" min="0" required />
        </div>
    </div>

    <div class="d-flex">
        <div class="mb-3 flex-fill form-floating me-1">
            <DateTimeInput @bind-Value="request.BookingStartDate" required />
        </div>

        <div class="mb-3 flex-fill form-floating">
            <DateTimeInput @bind-Value="request.BookingEndDate" />
        </div>
    </div>
    
    <div class="mb-3 form-floating">
        <TextAreaInput @bind-Value="request.Notes" placeholder="Notes about this booking" style="height:6rem" />
    </div>

    <div class="d-flex justify-content-between align-items-center">
        <div>
            <button type="submit" class="btn btn-primary">Create Booking</button>
        </div>
    </div>
</CascadingValue>
</form>

@code {
    [Parameter] public EventCallback<IdResponse> done { get; set; }
    [Parameter] public string? @class { get; set; }

    CreateBooking request = new()
    {
        BookingStartDate = DateTime.UtcNow,
    };

    // Hide Error Summary Messages for Visible Fields which displays contextual validation errors
    string[] VisibleFields => new[] {
        nameof(request.Name), 
        nameof(request.RoomType), 
        nameof(request.RoomNumber), 
        nameof(request.BookingStartDate),
        nameof(request.BookingEndDate), 
        nameof(request.Cost), 
        nameof(request.Notes),
    };

    ApiResult<IdResponse> api = new();

    async Task OnSubmit()
    {
        api = await ApiAsync(request);

        if (api.Succeeded)
        {
            await done.InvokeAsync(api.Response!);
            request = new();
        }
    }

    async Task close() => await done.InvokeAsync(null);
}
```

Which binds directly to the [CreateBooking](https://github.com/NetCoreTemplates/blazor-wasm/blob/main/MyApp.ServiceModel/Bookings.cs) Request DTO:

```csharp
[Tag("bookings"), Description("Create a new Booking")]
[Route("/bookings", "POST")]
[ValidateHasRole("Employee")]
[AutoApply(Behavior.AuditCreate)]
public class CreateBooking : ICreateDb<Booking>, IReturn<IdResponse>
{
    [Description("Name this Booking is for"), ValidateNotEmpty]
    public string Name { get; set; }
    public RoomType RoomType { get; set; }
    [ValidateGreaterThan(0)]
    public int RoomNumber { get; set; }
    [ValidateGreaterThan(0)]
    public decimal Cost { get; set; }
    public DateTime BookingStartDate { get; set; }
    public DateTime? BookingEndDate { get; set; }
    [Input(Type = "textarea")]
    public string? Notes { get; set; }
}
```

To initially render this form:

<a class="flex flex-col justify-center items-center my-8" href="https://vue-vite.jamstacks.net/bookings-crud">
    <img src="/img/pages/jamstack/blazor-wasm/booking-new.png" class="max-w-screen-md" />
</a>

Whose `[ValidateNotEmpty]` [declarative validator](/declarative-validation) filters down to the **client Input** UI to prevent unnecessary invalid API requests:

<a class="flex flex-col justify-center items-center my-8" href="https://vue-vite.jamstacks.net/bookings-crud">
    <img src="/img/pages/jamstack/blazor-wasm/booking-new-validation-client.png" class="max-w-screen-md" />
</a>

Validation of server error responses looks like:

<a class="flex flex-col justify-center items-center my-8" href="https://vue-vite.jamstacks.net/bookings-crud">
    <img src="/img/pages/jamstack/blazor-wasm/booking-new-validation-server.png" class="max-w-screen-md" />
</a>

#### Use of `form`

Validation errors use the standard `<form>` element and `api.Error` responses that can be passed directly to each control or in this case uses Blazor's built-in `<CascadingValue Value=@api.Error>` to cascade it to child components controls that can make use of it to display contextual errors.

#### Integrated Auth

It uses the templates included [AppComponentBase](https://github.com/NetCoreTemplates/blazor-wasm/blob/main/MyApp.Client/AppComponentBase.cs) which integrates with Blazor's Auth model allowing it to use its standard `[Authorize(Roles="Employee")]` attributes and provides access to the Authenticated User's info populated from Secure; HttpOnly JWT Cookies for secure stateless client Authentication that works across App deployments and without any server infrastructure.

Public pages can inherit `AppComponentBase` to access ServiceStack.Blazor's [BlazorComponentBase](https://github.com/ServiceStack/ServiceStack/blob/master/src/ServiceStack.Blazor/BlazorComponentBase.cs) and get access to `JsonApiClient` dependency and related functionality.

#### AutoQuery CRUD Example

`CreateBooking` is an [AutoQuery CRUD](/autoquery/crud) Request DTO, it works without a server implementation as it uses the default (and [overridable](/autoquery/crud#custom-autoquery-crud-services)) implementation generated by AutoQuery.

## Blazor Trade-offs

Blazor WASM enables reuse of C# skills, tooling & libraries offers a compelling advantage for .NET teams, so much so
it has become our preferred technology for developing internal LOB applications as it's better able to reuse existing
C# investments in an integrated SPA Framework utilizing a single toolchain.

It does however come at a cost of a larger initial download size and performance cost resulting in a high Time-To-First-Render (TTFR)
and an overall poor initial User Experience when served over the Internet, that's further exacerbated over low speed Mobile connections.

This is likely an acceptable trade-off for most LOB applications served over high-speed local networks but may not be a
suitable choice for public Internet sites _(an area our other [jamstacks.net](https://jamstacks.net) templates may serve better)_.

As an SPA it also suffers from poor SEO as content isn't included in the initial page and needs to be rendered in the browser after
the App has initialized. For some content heavy sites this can be a deal-breaker either requiring proxy rules so content pages
are served by a different SEO friendly site or otherwise prohibits using Blazor WASM entirely.

### Improving Startup Performance

The solution to both issues is fairly straightforward, by utilizing the mainstay solution behind
[Jamstack Frameworks](https://jamstack.org/generators/) and prerender content at build time.

We know what needs to be done, but how best to do it in Blazor WASM? Unfortunately the
[official Blazor WASM prerendering guide](https://docs.microsoft.com/en-us/aspnet/core/blazor/components/prerendering-and-integration?view=aspnetcore-6.0&pivots=webassembly)
isn't actually a prerendering solution, as is typically used to describe
[Static Site Generators (SSG)](https://www.netlify.com/blog/2020/04/14/what-is-a-static-site-generator-and-3-ways-to-find-the-best-one/)
prerendering static content at build-time, whilst Blazor WASM prerendering docs instead describes
a [Server-Side-Rendering (SSR)](https://www.omnisci.com/technical-glossary/server-side-rendering) solution mandating the additional 
complexity of maintaining your Apps dependencies in both client and server projects. Unfortunately this approach also wont yield an 
optimal result since prerendering is typically used so Apps can host their SSG content on static file hosts, instead SSR does the 
opposite whose forced runtime coupling to the .NET Server Host prohibits Blazor WASM Apps from being served from a CDN.

As this defeats [many of the benefits](https://blazor-wasm.web-templates.io/docs/hosting) of a Blazor WASM Jamstack App in the first place, 
we've instead opted for a more optimal solution that doesn't compromise its CDN hostability.

### Increasing Perceived Performance

We have little opportunity over improving the startup time of the real C# Blazor App beyond hosting its static assets on CDN edge caches,
but ultimately what matters is [perceived performance](https://marvelapp.com/blog/a-designers-guide-to-perceived-performance/) which
we do have control over given the screen for a default Blazor WASM project is a glaring white screen flash:

![](/img/pages/jamstack/blazor-wasm/loading-default.png)

The longer users have to wait looking at this black loading screen without signs of progress, the more they'll associate your site
with taking forever to load.

One technique many popular sites are using to increase perceived performance is to use content placeholders in place of real-content
which gives the impression that the site has almost loaded and only requires a few moments more for the latest live data to be slotted in.

As an example here's what YouTube content placeholders mimicking the page layout looks like before the real site has loaded:

![](/img/pages/jamstack/youtube-placeholder.png)

But we can do even better than an inert content placeholder, and load a temporary chrome of our App. But as this needs to be done
before Blazor has loaded we need to implement this with a sprinkling of HTML + JS.

First thing we need to do is move the scoped styles of our Apps
[MainLayout](https://github.com/NetCoreTemplates/blazor-wasm/blob/main/MyApp.Client/Shared/MainLayout.razor) and
[NavMenu](https://github.com/NetCoreTemplates/blazor-wasm/blob/main/MyApp.Client/Shared/NavMenu.razor) into an external
[main-layout.css](https://github.com/NetCoreTemplates/blazor-wasm/blob/main/MyApp.Client/wwwroot/css/main-layout.css) so our temp
App chrome can use it.

Then in our [/wwwroot/index.html](https://github.com/NetCoreTemplates/blazor-wasm/blob/main/MyApp.Client/wwwroot/index.html) anything
between `<div id="app"></div>` is displayed whilst our Blazor App is loading, before it's replaced with the real App.

So Here we just paste in the **MainLayout** markup:

```html
<div id="app">
    <!-- loading: render temp static app chrome to improve perceived performance -->
    <div id="app-loading" class="main-layout page">
        <div class="sidebar">
            <div class="top-row navbar navbar-dark">
                <a class="navbar-brand ps-4" href="/">MyApp</a>
                <button class="navbar-toggler">
                    <span class="navbar-toggler-icon"></span>
                </button>
            </div>
            <div class="collapse">
                <ul class="nav flex-column"></ul>
            </div>
        </div>
        <div class="main">
            <div class="main-top-row px-4">
                <ul class="nav nav-pills"></ul>
                <a href="signin?return=docs/deploy" class="btn btn-outline-primary">
                    Login
                </a>
            </div>
            <div class="content px-4">
                <!--PAGE-->
                <div class="spinner-border float-start mt-2 me-2" role="status">
                    <span class="sr-only"></span>
                </div>
                <h1 style="font-size:36px">
                    Loading...
                </h1>
                <!--/PAGE-->
            </div>
        </div>
    </div>
</div>
```

Less our App's navigation menus which we'll dynamically generate with the splash of JS below:

```js
const SIDEBAR = `
    Home,home,/$
    Counter,plus,/counter
    Todos,clipboard,/todomvc
    Bookings CRUD,calendar,/bookings-crud
    Call Hello,transfer,/hello$
    Call HelloSecure,shield,/hello-secure
    Fetch data,list-rich,/fetchdata
    Admin,lock-locked,/admin
    Login,account-login,/signin
`
const TOP = `
    0.40 /mo,dollar,/docs/hosting
    Prerendering,loop-circular,/docs/prerender
    Deployments,cloud-upload,/docs/deploy
`

const path = location.pathname
const NAV = ({ label, cls, icon, route, exact }) => `<li class="nav-item${cls}">
    <a href="${route}" class="nav-link${(exact ? path==route : path.startsWith(route)) ? ' active' : ''}">
        <span class="oi oi-${icon}" aria-hidden="true"></span> ${label}
    </a></li>`
const renderNav = (csv,f) => csv.trim().split(/\r?\n/g).map(s => NAV(f.apply(null,s.split(',')))).join('')
const $1 = s => document.querySelector(s)

$1('#app-loading .sidebar .nav').innerHTML = renderNav(SIDEBAR, (label, icon, route) => ({
    label, cls: ` px-3${route == SIDEBAR[0].route ? ' pt-3' : ''}`,
    icon, route: route.replace(/\$$/, ''), exact: route.endsWith('$')
}))

$1('#app-loading .main-top-row .nav').innerHTML = renderNav(TOP, (label, icon, route) => ({
    label, cls: '', icon, route: route.replace(/\$$/, ''), exact: route.endsWith('$')
}))
```

Which takes care of both rendering the top and sidebar menus as well as highlighting the active menu for the active
nav item being loaded, and because we're rendering our real App navigation with real links, users will be able to navigate
to the page they want before our App has loaded.

So you can distinguish a prerendered page from a Blazor rendered page we've added a **subtle box shadow** to prerendered content
which you'll see initially before being reverting to a flat border when the Blazor App takes over and replaces the entire page:

```html
<style>
#app-loading .content { box-shadow: inset 0 4px 4px 0 rgb(0 0 0 / 0.05) }
</style>
```

With just this, every page now benefits from an instant App chrome to give the perception that our App has loaded instantly
before any C# in our Blazor App is run. E.g. here's what the [Blazor Counter](https://blazor-wasm.web-templates.io/counter) page looks like while it's loading:

![](/img/pages/jamstack/blazor-wasm/loading.png)

If you click refresh the [/counter](https://blazor-wasm.web-templates.io/counter) page a few times you'll see the new loading screen prior to the Counter page being available.

Our App is now in a pretty shippable state with decent UX of a loading page that looks like it loaded instantly instead
of the "under construction" Loading... page from the default Blazor WASM project template.

It's not quite a zero maintenance solution but still fairly low maintenance as only the `SIDEBAR` and `TOP` csv lists
need updating when add/removing menu items.

### Improving UX with Prerendering

We'll now turn our focus to the most important page in our App, the [Home Page](https://blazor-wasm.web-templates.io) which is the page most people will see
when loading the App from the first time.

With the above temp App chrome already in place, a simple generic pre-rendering solution to be able to load any prerendered
page is to check if any prerendered content exists in the
[/prerender](https://github.com/NetCoreTemplates/blazor-wasm/tree/gh-pages/prerender)
folder for the current path, then if it does replace the default index.html `Loading...` page with it:

```js
const pagePath = path.endsWith('/') 
    ? path.substring(0, path.length - 2) + '/index.html' 
    : path
fetch(`/prerender${pagePath}`)
    .then(r => r.text())
    .then(html => {
        if (html.indexOf('<!DOCTYPE html>') >= 0) return // ignore CDN 404.html
        const pageBody = $1('#app-loading .content')
        if (pageBody) 
            pageBody.innerHTML = `<i hidden data-prerender="${path}"></i>` + html
    })
    .catch(/* no prerendered content found for this path */)
```

We also tag which path the prerendered content is for and provide a JS function to fetch the prerendered content
which we'll need to access later in our App:

```html
<script>
/* Loading */
window.prerenderedPage = function () {
    const el = document.querySelector('#app-loading .content')
    return el && el.innerHTML || ''
}
</script>
```

We now have a solution in place to load pre-rendered content from the `/prerender` folder, but still need some way of generating it.

The solution is technology independent in that you can you use any solution your most comfortable with, (even manually construct
each prerendered page if preferred), although it's less maintenance if you automate and get your CI to regenerate it when it publishes
your App.

Which ever tool you choose would also need to be installed in your CI/GitHub Action if that's where it's run, so we've opted for
a dependency-free & least invasive solution by utilizing the existing Tests project, which has both great IDE tooling support and
can easily be run from the command-line and importantly is supported by the [bUnit](https://bunit.dev) testing library which we'll
be using to render component fragments in isolation.

To distinguish prerendering tasks from our other Tests we've tagged
[PrerenderTasks.cs](https://github.com/NetCoreTemplates/blazor-wasm/blob/main/MyApp.Tests/PrerenderTasks.cs)
with the `prerender` Test category. The only configuration the tasks require is the location of the `ClientDir` WASM Project
defined in [appsettings.json](https://github.com/NetCoreTemplates/blazor-wasm/blob/main/MyApp.Tests/appsettings.json)
that's setup in the constructor.

The `Render<T>()` method renders the Blazor Page inside a `Bunit.TestContext` which it saves at the location
specified by its `@page` directive.

```csharp
[TestFixture, Category("prerender")]
public class PrerenderTasks
{
    Bunit.TestContext Context;
    string ClientDir;
    string WwrootDir => ClientDir.CombineWith("wwwroot");
    string PrerenderDir => WwrootDir.CombineWith("prerender");

    public PrerenderTasks()
    {
        Context = new();
        var config = new ConfigurationBuilder().AddJsonFile("appsettings.json").Build();
        ClientDir = config[nameof(ClientDir)] 
            ?? throw new Exception($"{nameof(ClientDir)} not defined in appsettings.json");
        FileSystemVirtualFiles.RecreateDirectory(PrerenderDir);
    }

    void Render<T>(params ComponentParameter[] parameters) where T : IComponent
    {
        WriteLine($"Rendering: {typeof(T).FullName}...");
        var component = Context.RenderComponent<T>(parameters);
        var route = typeof(T).GetCustomAttribute<RouteAttribute>()?.Template;
        if (string.IsNullOrEmpty(route))
            throw new Exception($"Couldn't infer @page for component {typeof(T).Name}");

        var fileName = route.EndsWith("/") ? route + "index.html" : $"{route}.html";

        var writeTo = Path.GetFullPath(PrerenderDir.CombineWith(fileName));
        WriteLine($"Written to {writeTo}");
        File.WriteAllText(writeTo, component.Markup);
    }

    [Test]
    public void PrerenderPages()
    {
        Render<Client.Pages.Index>();
        // Add Pages to prerender...
    }
}
```

Being a unit test gives it a number of different ways it can be run, using any of the NUnit test runners, from the GUI
integrated in C# IDEs or via command-line test runners like `dotnet test` which can be done with:

```bash
$ dotnet test --filter TestCategory=prerender 
```

To have CI automatically run it when it creates a production build of our App we'll add it to our Host `.csproj`:

```xml
<PropertyGroup>
    <TestsDir>$(MSBuildProjectDirectory)/../MyApp.Tests</TestsDir>
</PropertyGroup>
<Target Name="AppTasks" AfterTargets="Build" Condition="$(APP_TASKS) != ''">
    <CallTarget Targets="Prerender" Condition="$(APP_TASKS.Contains('prerender'))" />
</Target>
<Target Name="Prerender">
    <Exec Command="dotnet test --filter TestCategory=prerender --logger:&quot;console;verbosity=detailed&quot;" 
            WorkingDirectory="$(TestsDir)" />
</Target>
```

Which allows [GitHub Actions to run it](https://github.com/NetCoreTemplates/blazor-wasm/blob/9460ebf57d3e46af1680eb3a2ff5080e59d33a54/.github/workflows/release.yml#L80)
when it publishes the App with:

```bash
$ dotnet publish -c Release /p:APP_TASKS=prerender
```

Now when we next commit code, the GitHub CI Action will run the above task to generate our
[/prerender/index.html](https://github.com/NetCoreTemplates/blazor-wasm/blob/gh-pages/prerender/index.html) page
that now loads our [Home Page](https://blazor-wasm.web-templates.io) instantly!

[![](/img/pages/jamstack/blazor-wasm/home-prerendered.png)](/)

The only issue now is that the default Blazor template behavior will yank our pre-rendered page, once during loading
and another during Authorization. To stop the unwanted yanking we've updated the
[`<Loading/>`](https://github.com/NetCoreTemplates/blazor-wasm/blob/main/MyApp.Client/Shared/Loading.razor) component
to instead load the prerendered page content if it's **for the current path**:

```html
@inject IJSRuntime JsRuntime
@inject NavigationManager NavigationManager

@if (!string.IsNullOrEmpty(prerenderedHtml))
{
    @((MarkupString)prerenderedHtml)
}
else
{
    <div class=@CssUtils.ClassNames("spinner-border float-start mt-2 me-2", @class)>
        <span class="sr-only"></span>
    </div>
    <h1 style="font-size:36px">
        Loading...
    </h1>
}

@code {
    [Parameter]
    public string Message { get; set; } = "Loading...";

    [Parameter]
    public string @class { get; set; } = "";

    public string prerenderedHtml { get; set; } = "";

    protected override async Task OnInitializedAsync()
    {
        var html = await JsRuntime.InvokeAsync<string>("prerenderedPage") ?? "";
        var currentPath = new Uri(NavigationManager.Uri).AbsolutePath;
        if (html.IndexOf($"data-prerender=\"{currentPath}\"") >= 0)
            prerenderedHtml = html;
    }
}
```

Whilst to prevent yanking by the Authorization component we'll also include the current page when rendering
the alternate layout with an `Authenticating...` text that will appear under the Login/Logout buttons on the top-right:

```xml
<AuthorizeRouteView RouteData="@routeData" DefaultLayout="@typeof(MainLayout)">
  <Authorizing>
    <p class="text-muted" style="float:right;margin:1rem 1rem 0 0">Authenticating...</p>
    <RouteView RouteData="@routeData" />
  </Authorizing>
</AuthorizeRouteView>
```

This last change brings us to the optimal UX we have now with the home page loading instantly whilst our Blazor App
is loading in the background that'll eventually replace the home page with its identical looking C# version except
for the **box-shadow under the top navigation** so you can tell when you're looking at the pre-rendered version
instead of the C# Blazor version.

### Prerendering Markdown Content

The other pages that would greatly benefit from prerendering are the Markdown `/docs/*` pages (like this one) that's implemented in
[Docs.razor](https://github.com/NetCoreTemplates/blazor-wasm/blob/main/MyApp.Client/Pages/Docs.razor).

However to enable SEO friendly content our `fetch(/prerender/*)` solution isn't good enough as the initial page download
needs to contain the prerendered content, i.e. instead of being downloaded in after.

### PrerenderMarkdown Task

To do this our `PrerenderMarkdown` Task scans all `*.md` pages in the
[content](https://github.com/NetCoreTemplates/blazor-wasm/tree/main/MyApp.Client/wwwroot/content)
directory and uses the same
[/MyApp.Client/MarkdownUtils.cs](https://github.com/NetCoreTemplates/blazor-wasm/blob/main/MyApp.Client/MarkdownUtils.cs)
implementation [Docs.razor](https://github.com/NetCoreTemplates/blazor-wasm/blob/main/MyApp.Client/Pages/Docs.razor)
uses to generate the markdown and embeds it into the `index.html` loading page to generate the pre-rendered page:

```csharp
[Test]
public async Task PrerenderMarkdown()
{
    var srcDir = WwrootDir.CombineWith("content").Replace('\\', '/');
    var dstDir = WwrootDir.CombineWith("docs").Replace('\\', '/');
            
    var indexPage = PageTemplate.Create(WwrootDir.CombineWith("index.html"));
    if (!Directory.Exists(srcDir)) throw new Exception($"{Path.GetFullPath(srcDir)} does not exist");
    FileSystemVirtualFiles.RecreateDirectory(dstDir);

    foreach (var file in new DirectoryInfo(srcDir).GetFiles("*.md", SearchOption.AllDirectories))
    {
        WriteLine($"Converting {file.FullName} ...");

        var name = file.Name.WithoutExtension();
        var docRender = await Client.MarkdownUtils.LoadDocumentAsync(name, doc =>
            Task.FromResult(File.ReadAllText(file.FullName)));

        if (docRender.Failed)
        {
            WriteLine($"Failed: {docRender.ErrorMessage}");
            continue;
        }

        var dirName = dstDir.IndexOf("wwwroot") >= 0
            ? dstDir.LastRightPart("wwwroot").Replace('\\', '/')
            : new DirectoryInfo(dstDir).Name;
        var path = dirName.CombineWith(name == "index" ? "" : name);

        var mdBody = @$"
<div class=""prose lg:prose-xl min-vh-100 m-3"" data-prerender=""{path}"">
    <div class=""markdown-body"">
        {docRender.Response!.Preview!}
    </div>
</div>";
        var prerenderedPage = indexPage.Render(mdBody);
        string htmlPath = Path.GetFullPath(Path.Combine(dstDir, $"{name}.html"));
        File.WriteAllText(htmlPath, prerenderedPage);
        WriteLine($"Written to {htmlPath}");
    }
}

public class PageTemplate
{
    string? Header { get; set; }
    string? Footer { get; set; }

    public PageTemplate(string? header, string? footer)
    {
        Header = header;
        Footer = footer;
    }

    public static PageTemplate Create(string indexPath)
    {
        if (!File.Exists(indexPath))
            throw new Exception($"{Path.GetFullPath(indexPath)} does not exist");

        string? header = null;
        string? footer = null;

        var sb = new StringBuilder();
        foreach (var line in File.ReadAllLines(indexPath))
        {
            if (header == null)
            {
                if (line.Contains("<!--PAGE-->"))
                {
                    header = sb.ToString(); // capture up to start page marker
                    sb.Clear();
                }
                else sb.AppendLine(line);
            }
            else
            {
                if (sb.Length == 0)
                {
                    if (line.Contains("<!--/PAGE-->")) // discard up to end page marker
                    {
                        sb.AppendLine();
                        continue;
                    }
                }
                else sb.AppendLine(line);
            }
        }
        footer = sb.ToString();

        if (string.IsNullOrEmpty(header) || string.IsNullOrEmpty(footer))
            throw new Exception($"Parsing {indexPath} failed, missing <!--PAGE-->...<!--/PAGE--> markers");

        return new PageTemplate(header, footer);
    }

    public string Render(string body) => Header + body + Footer;
}
```

Whilst the `wwwroot/index.html` is parsed with `PageTemplate` above who uses the resulting layout to generate pages
within `<!--PAGE--><!--/PAGE-->` markers.

After it's also executed by the same MSBuild task run by GitHub Actions it prerenders all `/wwwroot/content/*.md` pages
which are written to the [/wwwroot/docs/*.html](https://github.com/NetCoreTemplates/blazor-wasm/tree/gh-pages/docs) folder.

This results in the path to the pre-generated markdown docs i.e. [/docs/prerender](https://github.com/LegacyTemplates/blazor-tailwind/blob/main/MyApp.Client/wwwroot/content/prerender.md) having the **exact same path**
as its route in the Blazor App, which when exists, CDNs give priority to over the SPA fallback the Blazor App is loaded with.

It shares similar behavior as the home page where its pre-rendered content is initially loaded before it's replaced with the
C# version once the Blazor App loads. The difference is that it prerenders "complete pages" for better SEO & TTFR.


# Blazor Tailwind Components
Source: https://docs.servicestack.net/templates/blazor-components

ServiceStack.Blazor high-productivity components enable rapid development in Blazor Server and WASM Apps:

<div class="my-8 flex justify-center">
    <lite-youtube class="w-full mx-4 my-4" width="560" height="315" videoid="iKpQI2233nY" style="background-image: url('https://img.youtube.com/vi/iKpQI2233nY/maxresdefault.jpg')"></lite-youtube>
</div>

<div id="blazor-component-gallery" class="not-prose mt-16 relative bg-white dark:bg-black py-4">
  <div class="mx-auto max-w-md px-4 text-center sm:max-w-3xl sm:px-6 lg:max-w-7xl lg:px-8">
    <p class="mt-2 text-3xl font-extrabold tracking-tight text-gray-900 dark:text-gray-50 sm:text-4xl">Blazor Gallery</p>
    <p class="mx-auto mt-5 max-w-prose text-xl text-gray-500">
      Discover ServiceStack.Blazor Rich UI Components and Integrated Features
    </p>
  </div>
</div>

[![](/img/pages/blazor/gallery-splash.png)](https://blazor-gallery.servicestack.net)

As our components support both hosting models we're maintaining identical Gallery sites running on both **Blazor Server** and **WASM**:

<div class="not-prose mb-16 mx-auto mt-5 max-w-md sm:flex sm:justify-center md:mt-8">
  <div class="rounded-md shadow">
    <a href="https://blazor-gallery.servicestack.net" class="flex w-full items-center justify-center rounded-md border border-transparent bg-indigo-600 px-8 py-3 text-base font-medium text-white hover:bg-indigo-700 md:py-4 md:px-10 md:text-lg hover:no-underline">
      Blazor Server
    </a>
  </div>
  <div class="mt-3 rounded-md shadow sm:mt-0 sm:ml-3">
    <a href="https://blazor-gallery.jamstacks.net" class="flex w-full items-center justify-center rounded-md border border-transparent bg-white px-8 py-3 text-base font-medium text-indigo-600 hover:bg-gray-50 md:py-4 md:px-10 md:text-lg hover:no-underline">
      Blazor WASM
    </a>
  </div>
</div>

For a closer look at ServiceStack.Blazor Components in action, download & run them to see how good they'll run in your Environment:

<div class="flex flex-col">
  <a href="https://github.com/NetCoreApps/BlazorGallery" class="flex text-xl text-gray-800">
    <svg class="w-6 h-6 mr-2 align-text-bottom" xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24"><path fill="currentColor" d="M12 .297c-6.63 0-12 5.373-12 12c0 5.303 3.438 9.8 8.205 11.385c.6.113.82-.258.82-.577c0-.285-.01-1.04-.015-2.04c-3.338.724-4.042-1.61-4.042-1.61C4.422 18.07 3.633 17.7 3.633 17.7c-1.087-.744.084-.729.084-.729c1.205.084 1.838 1.236 1.838 1.236c1.07 1.835 2.809 1.305 3.495.998c.108-.776.417-1.305.76-1.605c-2.665-.3-5.466-1.332-5.466-5.93c0-1.31.465-2.38 1.235-3.22c-.135-.303-.54-1.523.105-3.176c0 0 1.005-.322 3.3 1.23c.96-.267 1.98-.399 3-.405c1.02.006 2.04.138 3 .405c2.28-1.552 3.285-1.23 3.285-1.23c.645 1.653.24 2.873.12 3.176c.765.84 1.23 1.91 1.23 3.22c0 4.61-2.805 5.625-5.475 5.92c.42.36.81 1.096.81 2.22c0 1.606-.015 2.896-.015 3.286c0 .315.21.69.825.57C20.565 22.092 24 17.592 24 12.297c0-6.627-5.373-12-12-12"/></svg>
    <span>NetCoreApps/BlazorGallery</span>
  </a>
  <a href="https://github.com/NetCoreApps/BlazorGalleryWasm" class="flex mt-2 text-xl text-gray-800">
    <svg class="w-6 h-6 mr-2 align-text-bottom" xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24"><path fill="currentColor" d="M12 .297c-6.63 0-12 5.373-12 12c0 5.303 3.438 9.8 8.205 11.385c.6.113.82-.258.82-.577c0-.285-.01-1.04-.015-2.04c-3.338.724-4.042-1.61-4.042-1.61C4.422 18.07 3.633 17.7 3.633 17.7c-1.087-.744.084-.729.084-.729c1.205.084 1.838 1.236 1.838 1.236c1.07 1.835 2.809 1.305 3.495.998c.108-.776.417-1.305.76-1.605c-2.665-.3-5.466-1.332-5.466-5.93c0-1.31.465-2.38 1.235-3.22c-.135-.303-.54-1.523.105-3.176c0 0 1.005-.322 3.3 1.23c.96-.267 1.98-.399 3-.405c1.02.006 2.04.138 3 .405c2.28-1.552 3.285-1.23 3.285-1.23c.645 1.653.24 2.873.12 3.176c.765.84 1.23 1.91 1.23 3.22c0 4.61-2.805 5.625-5.475 5.92c.42.36.81 1.096.81 2.22c0 1.606-.015 2.896-.015 3.286c0 .315.21.69.825.57C20.565 22.092 24 17.592 24 12.297c0-6.627-5.373-12-12-12"/></svg>
    <span>NetCoreApps/BlazorGalleryWasm</span>
  </a>
</div>

<div class="not-prose pt-8 my-8 ml-20 flex flex-col items-center">
    <div>
        <svg class="w-40 h-40 text-gray-800 mr-8" xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24"><path fill="currentColor" d="M9.37 5.51A7.35 7.35 0 0 0 9.1 7.5c0 4.08 3.32 7.4 7.4 7.4c.68 0 1.35-.09 1.99-.27A7.014 7.014 0 0 1 12 19c-3.86 0-7-3.14-7-7c0-2.93 1.81-5.45 4.37-6.49zM12 3a9 9 0 1 0 9 9c0-.46-.04-.92-.1-1.36a5.389 5.389 0 0 1-4.4 2.26a5.403 5.403 0 0 1-3.14-9.8c-.44-.06-.9-.1-1.36-.1z"/></svg>
    </div>
    <h2 id="darkmode" class="border-none text-4xl sm:text-5xl md:text-6xl tracking-tight font-extrabold">
        <span class="text-gray-800 mr-6">Dark Mode</span>
    </h2>
</div>

All ServiceStack.Blazor components take advantage of Tailwind DarkMode support to include full support for Dark Mode.

![](/img/pages/blazor/dark-and-light-mode.png)

[Tailwind](https://tailwindcss.com) has revolutionized how we style our Web Apps with its [mobile first](https://tailwindcss.com/#mobile-first) design system that's dramatically simplified creating maintainable responsive Web Apps. It also excels at adding support for [Dark Mode](https://tailwindcss.com/#dark-mode) with its first-class **dark:** modifier allowing the use of standard tailwind classes to specify what elements should look like when viewed in **Dark Mode**, e.g:

<div class="not-prose relative bg-slate-50 rounded-xl overflow-hidden dark:bg-slate-800/25"><div style="background-position:10px 10px" class="absolute inset-0 bg-grid-slate-100 [mask-image:linear-gradient(0deg,#fff,rgba(255,255,255,0.6))] dark:bg-grid-slate-700/25 dark:[mask-image:linear-gradient(0deg,rgba(255,255,255,0.1),rgba(255,255,255,0.5))]"></div><div class="relative rounded-xl overflow-auto">
  <div class="grid grid-cols-1 sm:grid-cols-2">
    <div class="p-8 pt-7">
      <p class="mb-2 text-sm font-medium text-slate-500">Light mode</p>
      <div class="bg-white rounded-lg px-6 py-8 ring-1 ring-slate-900/5 shadow-xl">
        <div>
          <span class="inline-flex items-center justify-center p-2 bg-indigo-500 rounded-md shadow-lg">
            <svg class="h-6 w-6 text-white" xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke="currentColor" aria-hidden="true">
              <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M11 5H6a2 2 0 00-2 2v11a2 2 0 002 2h11a2 2 0 002-2v-5m-1.414-9.414a2 2 0 112.828 2.828L11.828 15H9v-2.828l8.586-8.586z"></path></svg>
          </span>
        </div>
        <h3 class="mt-5 text-base font-medium text-slate-900 tracking-tight">Writes Upside-Down</h3>
        <p class="mt-2 text-sm text-slate-500">
          The Zero Gravity Pen can be used to write in any orientation, including upside-down. It even works in outer space.
        </p>
      </div>
    </div>
    <div class="bg-slate-900 p-8 pt-7">
      <p class="mb-2 text-sm font-medium text-slate-400">Dark mode</p>
      <div class="bg-slate-800 rounded-lg px-6 py-8 ring-1 ring-slate-900/5 shadow-xl">
        <div>
          <span class="inline-flex items-center justify-center p-2 bg-indigo-500 rounded-md shadow-lg">
            <svg class="h-6 w-6 text-white" xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke="currentColor" aria-hidden="true">
              <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M11 5H6a2 2 0 00-2 2v11a2 2 0 002 2h11a2 2 0 002-2v-5m-1.414-9.414a2 2 0 112.828 2.828L11.828 15H9v-2.828l8.586-8.586z"></path></svg>
          </span>
        </div>
        <h3 class="mt-5 text-base font-medium text-white tracking-tight">Writes Upside-Down</h3>
        <p class="mt-2 text-sm text-slate-400">
          The Zero Gravity Pen can be used to write in any orientation, including upside-down. It even works in outer space.
        </p>
      </div>
    </div>
  </div>
</div><div class="absolute inset-0 pointer-events-none border border-black/5 rounded-xl dark:border-white/5"></div></div>

```html
<div class="bg-white dark:bg-slate-800 rounded-lg px-6 py-8 ring-1 ring-slate-900/5 shadow-xl">
  <div>
    <span class="inline-flex items-center justify-center p-2 bg-indigo-500 rounded-md shadow-lg">
      <svg class="h-6 w-6 text-white" xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke="currentColor" aria-hidden="true"><!-- ... --></svg>
    </span>
  </div>
  <h3 class="text-slate-900 dark:text-white mt-5 text-base font-medium tracking-tight">Writes Upside-Down</h3>
  <p class="text-slate-500 dark:text-slate-400 mt-2 text-sm">
    The Zero Gravity Pen can be used to write in any orientation, including upside-down. It even works in outer space.
  </p>
</div>
```

### View ServiceStack.Blazor in Dark Mode

We're happy to announce that Dark Mode support is included in **all ServiceStack.Blazor components** and all Blazor Tailwind project templates where you'll be able to toggle on/off Dark Mode with the new `<DarkModeToggle>` component. Checkout this video to see how beautiful Dark Mode looks like in the latest ServiceStack.Blazor Components and Tailwind project templates:

<div class="my-8 flex justify-center">
    <lite-youtube class="w-full mx-4 my-4" width="560" height="315" videoid="8nwpC_B4AC4" style="background-image: url('https://img.youtube.com/vi/8nwpC_B4AC4/maxresdefault.jpg')"></lite-youtube>
</div>

For a more interactive view, use the right Dark Mode toggle to turn on/off Dark Mode in the embedded [Blazor Gallery Contacts Page](https://blazor-gallery.jamstacks.net/grid/contacts-meta):

<iframe src="https://blazor-gallery.jamstacks.net/grid/contacts-meta/embed" class="w-full border-none h-[970px]"></iframe>

Dark Mode is all implemented with CSS, controlled by toggling the **dark** class on the `<html class="dark">` element, `<DarkModeToggle>` also saves this user preference in `localStorage` where it's preserved across browser restarts.

### View in Dark Mode

The Blazor Tailwind templates also include the ability to override the users color scheme preference and open a page in dark or light mode with the 
`?dark` and `?light` query params:

<div class="not-prose relative">
  <div class="grid grid-cols-1 sm:grid-cols-2 text-center">
    <div>
        <a class="flex flex-col" href="https://blazor.web-templates.io/?light">
            <div class="py-4">blazor.web-templates.io/?light</div>
            <img class="rounded-xl overflow-hidden" src="/img/pages/blazor/blazor-gallery-light.png">
        </a>
    </div>
    <div>
        <a class="flex flex-col" href="https://blazor.web-templates.io/?dark">
            <div class="py-4">blazor.web-templates.io/?dark</div>
            <img class="rounded-xl overflow-hidden" src="/img/pages/blazor/blazor-gallery-dark.png">
        </a>
    </div>
  </div>
</div>

### Force Dark Mode

If your App is best viewed in Dark Mode you can force it to use Dark Mode with `JS.init()` when initializing ServiceStack.Blazor's JS library in Blazor Server's **_Layout.cshtml** or Blazor WASM's **index.html**, e.g:

```html
<script src="_framework/blazor.server.js"></script>
<script src="/js/servicestack-blazor.js"></script>
<script>JS.init({ colorScheme:'dark' })</script>
```

<p class="hide-h2"></p>

## Blazor Tailwind Components

<div id="blazor-components" class="not-prose mt-16 mb-8 ml-20 flex flex-col items-center">
    <div class="flex">
        <svg class="w-40 h-40 text-purple-600 mr-8" xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24"><path fill="currentColor" d="M23.834 8.101a13.912 13.912 0 0 1-13.643 11.72a10.105 10.105 0 0 1-1.994-.12a6.111 6.111 0 0 1-5.082-5.761a5.934 5.934 0 0 1 11.867-.084c.025.983-.401 1.846-1.277 1.871c-.936 0-1.374-.668-1.374-1.567v-2.5a1.531 1.531 0 0 0-1.52-1.533H8.715a3.648 3.648 0 1 0 2.695 6.08l.073-.11l.074.121a2.58 2.58 0 0 0 2.2 1.048a2.909 2.909 0 0 0 2.695-3.04a7.912 7.912 0 0 0-.217-1.933a7.404 7.404 0 0 0-14.64 1.603a7.497 7.497 0 0 0 7.308 7.405s.549.05 1.167.035a15.803 15.803 0 0 0 8.475-2.528c.036-.025.072.025.048.061a12.44 12.44 0 0 1-9.69 3.963a8.744 8.744 0 0 1-8.9-8.972a9.049 9.049 0 0 1 3.635-7.247a8.863 8.863 0 0 1 5.229-1.726h2.813a7.915 7.915 0 0 0 5.839-2.578a.11.11 0 0 1 .059-.034a.112.112 0 0 1 .12.053a.113.113 0 0 1 .015.067a7.934 7.934 0 0 1-1.227 3.549a.107.107 0 0 0-.014.06a.11.11 0 0 0 .073.095a.109.109 0 0 0 .062.004a8.505 8.505 0 0 0 5.913-4.876a.155.155 0 0 1 .055-.053a.15.15 0 0 1 .147 0a.153.153 0 0 1 .054.053A10.779 10.779 0 0 1 23.834 8.1zM8.895 11.628a2.188 2.188 0 1 0 2.188 2.188v-2.042a.158.158 0 0 0-.15-.15Z"/></svg>
        <svg class="w-44 h-44" xmlns="http://www.w3.org/2000/svg" width="256" height="154" viewBox="0 0 256 154"><defs><linearGradient id="logosTailwindcssIcon0" x1="-2.778%" x2="100%" y1="32%" y2="67.556%"><stop offset="0%" stop-color="#2298BD"/><stop offset="100%" stop-color="#0ED7B5"/></linearGradient></defs><path fill="url(#logosTailwindcssIcon0)" d="M128 0C93.867 0 72.533 17.067 64 51.2C76.8 34.133 91.733 27.733 108.8 32c9.737 2.434 16.697 9.499 24.401 17.318C145.751 62.057 160.275 76.8 192 76.8c34.133 0 55.467-17.067 64-51.2c-12.8 17.067-27.733 23.467-44.8 19.2c-9.737-2.434-16.697-9.499-24.401-17.318C174.249 14.743 159.725 0 128 0ZM64 76.8C29.867 76.8 8.533 93.867 0 128c12.8-17.067 27.733-23.467 44.8-19.2c9.737 2.434 16.697 9.499 24.401 17.318C81.751 138.857 96.275 153.6 128 153.6c34.133 0 55.467-17.067 64-51.2c-12.8 17.067-27.733 23.467-44.8 19.2c-9.737-2.434-16.697-9.499-24.401-17.318C110.249 91.543 95.725 76.8 64 76.8Z"/></svg>
    </div>
    <h2 class="border-none text-4xl sm:text-5xl md:text-6xl tracking-tight font-extrabold">
        <span class="text-purple-600 mr-6">Blazor</span>
        <span class="mr-6" style="color:#44A8B3">Tailwind</span>
        <span class="text-gray-800">Components</span>
    </h2>
</div>

We encourage you to explore to the Blazor Gallery websites for the full preview, but we'll look at some of the Components here to give you some idea of the functionality available.

### DataGrid

`DataGrid` is a versatile Component we expect to be heavily used for rendering any typed collection:

```html
<DataGrid Model="Track" Items=@Track.Results />
```

Which by default renders results in a striped Tailwind Table:

![](/img/pages/blazor/datagrid-tracks.png)

Whose appearance can be styled to support many of the [Tailwind Table Styles](https://tailwindui.com/components/application-ui/lists/tables) with the `TableStyles` Flag enum, e.g:

```html
<DataGrid Model="Track" Items=@Track.Results TableStyle="TableStyle.VerticalLines" />

<DataGrid Model="Track" Items=@Track.Results TableStyle="TableStyle.WhiteBackground" />

<DataGrid Model="Track" Items=@Track.Results TableStyle="TableStyle.FullWidth" />

<DataGrid Model="Track" Items=@Track.Results 
          TableStyle="TableStyle.UppercaseHeadings | TableStyle.FullWidth | TableStyle.VerticalLines" />
```

![](/img/pages/blazor/datagrid-table-styles.png)

It's a highly versatile component where you'll be able to control which columns are displayed and how they're formatted using `<Column>` definitions, e.g. here's how we can customize the table to look like Blazor's [FetchData.cshtml](https://github.com/SteveSanderson/Blazor/blob/master/samples/ClientServerApp/ClientServerApp.Client/FetchData.cshtml) tabular results:

```html
<DataGrid Items=@forecasts class="max-w-screen-md" TableStyle="TableStyle.StripedRows | TableStyle.UppercaseHeadings">
    <Column Field="(WeatherForecast x) => x.Date" Format="dd/MM/yyyy" />
    <Column Title="Temp. (C)" Field="(WeatherForecast x) => x.TemperatureC" />
    <Column Title="Temp. (F)" Field="(WeatherForecast x) => x.TemperatureF" />
    <Column Field="(WeatherForecast x) => x.Summary" />
</DataGrid>

@code {
    List<WeatherForecast> forecasts = new();

    protected override async Task OnInitializedAsync()
    {
        forecasts = await Http.GetFromJsonAsync<List<WeatherForecast>>("data/weather.json") ?? new();
    }
}
```

[![](/img/pages/blazor/datagrid-weather.png)](https://blazor-gallery.servicestack.net/fetchdata)


Here's a more advanced example showing how to implement a responsive DataGrid by utilizing custom Header and Table Cell templates to define what columns and Headers are visible at different responsive breakpoints and how to enable different features like **Row Selection** and **Filtering** and examples of handling the Row and Header selected events App's can use for executing custom logic:

```html
<DataGrid Model="Booking" Items=@Items AllowSelection="true" AllowFiltering="true"
          HeaderSelected="HandleSelectedHeader" RowSelected="HandleSelectedRow">
    <Column Field="(Booking x) => x.Id" class="text-gray-900" />
    <Column Field="(Booking x) => x.Name" VisibleFrom="Breakpoint.ExtraLarge" />
    <Column Field="(Booking x) => x.RoomType">
        <Header>
            <span class="hidden lg:inline">Room </span>Type
        </Header>
    </Column>
    <Column Field="(Booking x) => x.RoomNumber">
        <Header>
            <span class="hidden lg:inline">Room </span>No
        </Header>
    </Column>
    <Column Field="(Booking x) => x.Cost" Format="C" />
    <Column Field="(Booking x) => x.BookingStartDate" Formatter="FormatDate" VisibleFrom="Breakpoint.Small">
        <Header>
            Start<span class="hidden lg:inline"> Date</span>
        </Header>
    </Column>
    <Column Field="(Booking x) => x.BookingEndDate" Formatter="FormatDate" VisibleFrom="Breakpoint.ExtraLarge">
        <Header>
            End<span class="hidden lg:inline"> Date</span>
        </Header>
        <Template>@{ var booking = context as Booking; }@booking.BookingEndDate?.ToString("D")
        </Template>
    </Column>
    <Column Title="Employee" Field="(Booking x) => x.CreatedBy" VisibleFrom="Breakpoint.Medium" />
</DataGrid>

@code {
    public List<Booking> Items { get; set; } = new() {
        Create.Booking("First Booking!",  RoomType.Queen,  10, 100, "employee@email.com", "BOOK10"),
        Create.Booking("Booking 2",       RoomType.Double, 12, 120, "manager@email.com",  "BOOK25"),
        Create.Booking("Booking the 3rd", RoomType.Suite,  13, 130, "employee@email.com", "BOOK50"),
    };

    string FormatDate(object o) => o is DateTime d ? d.ToShortDateString() : "";

    public async Task HandleSelectedHeader(Column<Booking> item)
    {
        await JS.Log(item.Name);
    }

    public async Task HandleSelectedRow(Booking x)
    {
        await JS.Log(x);
    }
}
```

:::tip
Resize webpage to preview its responsive appearance and different resolution breakpoints
:::

<iframe class="w-full border-none" style="height:385px" src="https://blazor-gallery.jamstacks.net/gallery/datagrid/responsive"></iframe>

### AutoQueryGrid

The functionality and extensibility in `DataGrid` lays the foundation for higher-level components like `AutoQueryGrid` which makes use of it to enable its Auto UI around [AutoQuery CRUD](/autoquery/crud) Services. 

### AutoQueryGrid Read Only

At a minimum AutoQueryGrid requires the AutoQuery APIs it should call to implement its functionality, so you can implement a **read-only** grid by only
specifying the AutoQuery API to query a data model, e.g:

```csharp
<AutoQueryGrid Model="Booking" Apis="Apis.AutoQuery<QueryBookings>()" />
```

This one AutoQuery API is enough to power a functional read-only UI enabling multi flexible querying capabilities, paging, custom column selection and the ability to export the desired filtered resultset to .csv which can be open in Excel or copy the API URL Apps can use to consume the JSON API results:

<iframe class="w-full border-none" style="height:430px" src="https://blazor-gallery.jamstacks.net/gallery/autoquerygrid/readonly"></iframe>

### AutoQueryGrid CRUD

Full CRUD functionality can be enabled by specifying the AutoQuery CRUD APIs for a specified data model, e.g:

```csharp
<AutoQueryGrid Model="Booking" Apis="Apis.AutoQuery<QueryBookings,CreateBooking,UpdateBooking,DeleteBooking>()" />
```

[![](/img/pages/blazor/autoquerygrid-crud.png)](https://blazor-gallery.jamstacks.net/gallery/autoquerygrid/crud)

### Customizable Columns

As `AutoQueryGrid` builds on `DataGrid` it also inherits its customizable option allowing for [customizable responsive columns](https://blazor-gallery.servicestack.net/gallery/autoquerygrid), e.g:

```html
<AutoQueryGrid Model="Booking" Apis="Apis.AutoQuery<QueryBookings,CreateBooking,UpdateBooking,DeleteBooking>()"
               AllowSelection="true" AllowFiltering="true"
               HeaderSelected="OnSelectedHeader" RowSelected="OnSelectedRow">
    <Columns>
        <!-- Custom class -->
        <Column Field="(Booking x) => x.Id" class="text-gray-900" />
        <!-- Only show from Tailwind's xl responsive Breakpoint -->
        <Column Field="(Booking x) => x.Name" VisibleFrom="Breakpoint.ExtraLarge" />
        <!-- Custom Header collapsing 'Room' below 'lg' responsive breakpoint -->
        <Column Field="(Booking x) => x.RoomType">
            <Header>
                <span class="hidden lg:inline">Room </span>Type
            </Header>
        </Column>
        <!-- Custom Header collapsing 'Room' below 'lg' responsive breakpoint -->
        <Column Field="(Booking x) => x.RoomNumber">
            <Header>
                <span class="hidden lg:inline">Room </span>No
            </Header>
        </Column>
        <!-- Custom string Format -->
        <Column Field="(Booking x) => x.Cost" Format="C" />
        <!-- Custom C# Formatter -->
        <Column Field="(Booking x) => x.BookingStartDate" Formatter="FormatDate" VisibleFrom="Breakpoint.Small">
            <Header>
                Start<span class="hidden lg:inline"> Date</span>
            </Header>
        </Column>
        <!-- Custom Header and Cell Value -->
        <Column Field="(Booking x) => x.BookingEndDate" VisibleFrom="Breakpoint.ExtraLarge2x">
            <Header>
                End<span class="hidden lg:inline"> Date</span>
            </Header>
            <Template>
                @context.BookingEndDate?.ToString("D")
            </Template>
        </Column>
        <!-- Custom Title and Complex Type Cell with Reference Link -->
        <Column Title="Voucher" Field="(Booking x) => x.Discount" VisibleFrom="Breakpoint.ExtraLarge">
            <Template>
@if (context.Discount != null)
{
    <TextLink class="flex items-end" href=@($"/gallery/autoquerygrid/coupons?Id={context.Discount.Id}")>
        <PreviewFormat Value=@context.Discount />
    </TextLink>
}          </Template>
        </Column>
    </Columns>
</AutoQueryGrid>
```

Customizing how and when columns are rendered at different breakpoints using different formatting options and custom table header and cell templates:

[![](/img/pages/blazor/autoquerygrid-responsive.png)](https://blazor-gallery.jamstacks.net/gallery/autoquerygrid/responsive)

### Declarative Customizations

The columns can also be customized declaratively using the `[Format]` Metadata Attribute on the Model type:

```csharp
public class Contact : AuditBase
{
    [AutoIncrement]
    public int Id { get; set; }

    [Format(FormatMethods.IconRounded)]
    public string ProfileUrl { get; set; }

    public string FirstName { get; set; }
    public string LastName { get; set; }

    [Format(FormatMethods.Currency)]
    public int? SalaryExpectation { get; set; }

    [Format(FormatMethods.LinkEmail, Options = 
        @"{target:'_self',subject:'New Job Opportunity',
           body:'We have an exciting new opportunity...', cls:'text-green-600'}")]
    public string Email { get; set; }

    [Format(FormatMethods.LinkPhone)]
    public string Phone { get; set; }
}
```

Which can change how results are formatted in the data grid results:

[![](/img/pages/blazor/autoquerygrid-metadata.png)](https://blazor-gallery.jamstacks.net/grid/contacts-meta)

Whilst the `[Input]` and `[FieldCss]` attributes on the AutoQuery CRUD DTOs:

```csharp
public class UpdateContact : IPatchDb<Contact>, IReturn<Contact>
{
    public int Id { get; set; }

    [ValidateNotEmpty]
    public string? FirstName { get; set; }

    [ValidateNotEmpty]
    public string? LastName { get; set; }

    [Input(Type = "file"), UploadTo("profiles")]
    public string? ProfileUrl { get; set; }
    
    public int? SalaryExpectation { get; set; }

    [ValidateNotEmpty]
    public string? JobType { get; set; }

    public int? AvailabilityWeeks { get; set; }
    public EmploymentType? PreferredWorkType { get; set; }
    public string? PreferredLocation { get; set; }

    [ValidateNotEmpty]
    public string? Email { get; set; }
    public string? Phone { get; set; }
 
    [Input(Type="textarea")]
    [FieldCss(Field="col-span-12 text-center", Input="h-48", Label="text-xl text-indigo-700")]
    public string? About { get; set; }
}
```

Can customize how forms are rendered, e.g:

[![](/img/pages/blazor/autoquerygrid-metadata-form.png)](https://blazor-gallery.jamstacks.net/grid/contacts-meta)


### ToolbarButtons

The `<ToolbarButtons>` element can be used to customize the AutoQueryGrid to add your own custom Toolbar buttons, e.g:

```html
<AutoQueryGrid>
  <ToolbarButtons>
    <div class="pl-2"><button>1</button></div>
    <div class="pl-2"><button>2</button></div>
  </ToolbarButtons>
</AutoQueryGrid>
```

 Enabling complete control over the Toolbar as all existing toolbar buttons can be removed with [AutoQueryGrid parameters](https://reference.servicestack.net/api/ServiceStack.Blazor.Components.Tailwind/AutoQueryGrid%60Model%60).

### Custom Edit and Create Forms

The `<CreateForm>` and `<EditForm>` elements can be used to replace the default [Auto Forms](https://blazor-gallery.jamstacks.net/gallery/autoform) used in creating and editing rows when more advanced or customized functionality is needed.

With this feature we can create a Custom AutoQueryGrid component that uses Custom Edit & Create Forms when selecting and adding new records and also customize the Grid results displayed with the new `ConfigureQuery` parameter to ensure results are filtered to the selected Tenant records:

```html
<AutoQueryGrid @ref=@grid Model="Item" Apis="Apis.AutoQuery<QueryItems,NewItem,EditItem>()" ConfigureQuery="Configure">
    <CreateForm>
        <div class="relative z-10">
            <div class="pointer-events-none fixed inset-y-0 right-0 flex max-w-full pl-10 sm:pl-16">
                <CustomCreateItem OnClose="grid!.OnEditDone" />
            </div>
        </div>
    </CreateForm>
    <EditForm>
        <div class="relative z-10">
            <div class="pointer-events-none fixed inset-y-0 right-0 flex max-w-full pl-10 sm:pl-16">
                <CustomEditItem Item="context" OnClose="grid!.OnEditDone" />
            </div>
        </div>
    </EditForm>
</AutoQueryGrid>

@code {
    AutoQueryGrid<Creative>? grid;
    [Parameter, SupplyParameterFromQuery] public int? TenantId { get; set; }

    void Configure(QueryBase query)
    {
        query.AddQueryParam("TenantId", TenantId);
    }
}
```

### Managing Filters & Preferences

By default the AutoQueryGrid displays the user's selected columns and query limit preferences which are persisted in localStorage. 
They can be overridden with the new **Prefs** attribute which has different ergonomic methods for configuration within an attribute:

To limit the Query Results Limit:

```html
<AutoQueryGrid @ref=@grid Model="Contact" Apis="Apis.AutoQuery<QueryContacts,CreateContact,UpdateContact>()"
               Prefs="ApiPrefs.Create(take:10)" />
```

To limit which columns are displayed in the Query Results:

```html
<AutoQueryGrid @ref=@grid Model="Contact" Apis="Apis.AutoQuery<QueryContacts,CreateContact,UpdateContact>()"
               Prefs="ApiPrefs.Columns(nameof(Contact.Id), nameof(Contact.LastName))" />
```

```html
<AutoQueryGrid @ref=@grid Model="Contact" Apis="Apis.AutoQuery<QueryContacts,CreateContact,UpdateContact>()"
               Prefs="ApiPrefs.Columns<Contact>(x => new { x.Id, x.LastName, x.Email })" />
```

To configure both Query Limit and Selected Columns:

```html
<AutoQueryGrid @ref=@grid Model="Contact" Apis="Apis.AutoQuery<QueryContacts,CreateContact,UpdateContact>()"
               Prefs="ApiPrefs.Create(take:10, columns:new(){ nameof(Contact.Id), nameof(Contact.LastName) })" />
```

```html
<AutoQueryGrid @ref=@grid Model="Contact" Apis="Apis.AutoQuery<QueryContacts,CreateContact,UpdateContact>()"
               Prefs="ApiPrefs.Configure(x => { x.Take = 5; x.SelectedColumns=new() { nameof(Contact.LastName) }; })"/>
```

In addition the new methods below can be used to clear any user-defined query filters and column preferences:

| Method | Description |
|--|--|
| grid.ClearFiltersAsync()     | Remove user-defined Filters |
| grid.ResetPreferencesAsync() | Remove user-defined Filters and Column Preferences |


### Disable Column Filtering

By default Filtering and Sorting are disabled for complex type columns, they can also be explicitly disabled per column with `AllowFiltering`, e.g:

```html
<AutoQueryGrid>
    <Column Field="(Contact x) => x.Phone" AllowFiltering="false" />
<AutoQueryGrid>
```

### Changing AutoQueryGrid Defaults

A lot of AutoQueryGrid's UI is customizable allowing you to easily toggle on/off UI features as needed, if you have a consistent style you wish to enforce you can 
change the defaults of every AutoQueryGrid component with [BlazorConfig](#blazor-config), e.g. you can remove **Copy URL** button and change the default Table style to use Uppercase Headings with:

```csharp
BlazorConfig.Set(new() {
    //...
    AutoQueryGridDefaults = new() {
        TableStyle = TableStyle.StripedRows | TableStyle.UppercaseHeadings,
        ShowCopyApiUrl = false,
    }
});
```

Which will change the appearance of every `AutoQueryGrid` Component used in the App unless overridden.

### AutoQueryGrid Gallery

As AutoQueryGrid is a core component for the rapid development of Apps we're maintaining a dedicated section showcasing their different features at [blazor-gallery.servicestack.net/grid](https://blazor-gallery.servicestack.net/grid):

[![](/img/pages/blazor/autoquerygrid-more.png)](https://blazor-gallery.servicestack.net/grid)

## Modal Lookups

To provide an optimal UX for relational fields `AutoQueryGrid` utilizes Modal Lookups for searching and selecting referential data that's automatically inferred from your OrmLite data model relationships, e.g:

```csharp
public class JobApplication : AuditBase
{
    [AutoIncrement]
    public int Id { get; set; }

    [References(typeof(Job))]
    public int JobId { get; set; }
    
    [References(typeof(Contact))]
    public int ContactId { get; set; }
    //...
}
```

Where it will display an enhanced [LookupInput](https://reference.servicestack.net/api/ServiceStack.Blazor.Components.Tailwind/LookupInput) instead of a plain Text Input for the relational `JobId` and `ContactId` fields:

[![](/img/pages/blazor/modalLookup-input.png)](https://blazor-gallery.servicestack.net/grid/job-applications?edit=1)

Which users can use to quickly search for the related record instead of manually inserting Foreign Key Ids:

[![](/img/pages/blazor/modalLookup-dialog.png)](https://blazor-gallery.servicestack.net/grid/job-applications?edit=1)

## File Uploads

Another feature showcased in the above screenshots is support for [Managed File Uploads](/locode/files-overview) which can be declaratively added with the `[Input(Type="file")]` to render the [FileInput](https://reference.servicestack.net/api/ServiceStack.Blazor.Components.Tailwind/FileInput) Component and `[UploadTo]` attribute to specify which File [Upload location](/locode/files#basic-file-upload-example) it should use:

```csharp
public class UpdateJobApplication : IPatchDb<JobApplication>, IReturn<JobApplication>
{
    public int Id { get; set; }
    public int? JobId { get; set; }
    public int? ContactId { get; set; }
    public DateTime? AppliedDate { get; set; }
    public JobApplicationStatus? ApplicationStatus { get; set; }

    [Input(Type = "file"), UploadTo("applications")]
    public List<JobApplicationAttachment>? Attachments { get; set; }
}
```

For a quick primer on using Managed File Uploads to [Upload files from Blazor](/locode/files-blazor) checkout:

<div class="my-16 px-4 sm:px-6">
    <div class="text-center">
      <h1 class="text-4xl tracking-tight font-extrabold text-gray-900 sm:text-5xl">
        <a href="/locode/files-blazor" class="block xl:inline">File Blazor</a>
      </h1>
    </div>
    <div class="my-8">
        <lite-youtube class="w-full mx-4 my-4" width="560" height="315" videoid="5sd00MzHpaU" style="background-image: url('https://img.youtube.com/vi/5sd00MzHpaU/maxresdefault.jpg')"></lite-youtube>
    </div>
</div>

## Auto Forms

The Auto Form components are other high productivity components which can be used to create an automated form based from a Request DTO definition:

```csharp
<AutoCreateForm Model="Booking" ApiType="typeof(CreateBooking)" />
```

[![](/img/pages/blazor/AutoCreateForm.png)](https://blazor-gallery.servicestack.net/gallery/autoform)

### AutoEditForm

Whilst `AutoEditForm` can be used to render an automated form based to update and delete an [AutoQuery CRUD](/autoquery/crud) API:

```csharp
<AutoEditForm Model="Booking" Edit="Model" ApiType="typeof(UpdateBooking)" DeleteApiType="typeof(DeleteBooking)" />

@code {
    Booking Model = Create.Booking("First Booking!", RoomType.Queen, 10, 100, "employee@email.com");
}
```

[![](/img/pages/blazor/AutoEditForm.png)](https://blazor-gallery.servicestack.net/gallery/autoform)

The forms behavior and appearance is further customizable with the [API annotation](/locode/declarative#annotate-apis), declarative [validation](/locode/declarative#type-validation-attributes) and the custom [Field and Input](/locode/declarative#custom-fields-and-inputs) attributes, e.g:

```csharp
[Description("Update an existing Booking")]
[Notes("Find out how to quickly create a <a class='svg-external' target='_blank' href='https://youtu.be/rSFiikDjGos'>C# Bookings App from Scratch</a>")]
[Route("/booking/{Id}", "PATCH")]
[ValidateHasRole("Employee")]
[AutoApply(Behavior.AuditModify)]
public class UpdateBooking : IPatchDb<Booking>, IReturn<IdResponse>
{
    public int Id { get; set; }
    public string? Name { get; set; }
    public RoomType? RoomType { get; set; }
    [ValidateGreaterThan(0)]
    public int? RoomNumber { get; set; }
    [ValidateGreaterThan(0)]
    public decimal? Cost { get; set; }
    public DateTime? BookingStartDate { get; set; }
    public DateTime? BookingEndDate { get; set; }
    [Input(Type = "textarea")]
    public string? Notes { get; set; }
    public bool? Cancelled { get; set; }
}
```


Both AutoForm components will render the Forms UI in a Slide Over dialog and includes built-in support for calling the API to update or edit the record with integrated contextual validation, reporting any field validation errors alongside their Input controls.

### AutoFormFields

If more advanced customization of a Forms appearance and behavior is required, you can use `AutoFormFields` to just render the Form's fields (including Validation binding) that can be used to populate a Request DTO that your App can handle sending, e.g:

[![](/img/pages/blazor/AutoFormFields.png)](https://blazor-gallery.servicestack.net/gallery/autoform)

```csharp
<form @onsubmit="submit" @onsubmit:preventDefault>
    <div class="shadow sm:overflow-hidden sm:rounded-md max-w-screen-lg">
        <div class="space-y-6 bg-white py-6 px-4 sm:p-6">
            <div>
                <h3 class="text-lg font-medium leading-6 text-gray-900">@(ApiType.GetDescription())</h3>
                <p class="notes mt-1 text-sm text-gray-500">
                    @((MarkupString)ApiType.GetNotes())
                </p>
            </div>

            <AutoFormFields Type="typeof(Booking)" Api="Api" FormLayout="FormLayout" ModelDictionary="ModelDictionary"/>

        </div>
        <div class="bg-gray-50 px-4 py-3 text-right sm:px-12">
            <PrimaryButton type="submit" onclick="submit">Save</PrimaryButton>
        </div>
    </div>
</form>

@code {
    [Inject] public JsonApiClient? Client { get; set; }
    IHasErrorStatus? Api { get; set; }
    Type ApiType = typeof(UpdateBooking);
    List<InputInfo>? FormLayout { get; set; }
    Dictionary<string, object> ModelDictionary { get; set; } = new();
    MetadataType MetadataType => ApiType.ToMetadataType();

    Booking Edit = Create.Booking("First Booking!", RoomType.Queen, 10, 100, "employee@email.com");

    protected override async Task OnParametersSetAsync()
    {
        await base.OnParametersSetAsync();
        Api = null;

        ModelDictionary = Edit.ToModelDictionary();
        FormLayout ??= MetadataType.CreateFormLayout<Booking>();
    }

    async Task submit()
    {
        var request = ModelDictionary.FromModelDictionary<UpdateBooking>();
        Api = await Client!.ApiAsync(request);
    }
}
```

## Autocomplete

The `<Autocomplete>` component provides a user friendly Input for being able to search and quickly select items, that includes support for rich templated content, custom matching and infinite scrolling that avoids pre-loading the entire bound list of items. 

Instead of being populated with a fixed List of strings or Key Value Pairs the Autocomplete component can bind directly to a list of POCOs to render its templated content where you'll be able to specify a custom `Match` filter to control which filtered items are displayed, that it can fuzzy match on single or multiple POCO properties.

### Single Contact

Here's a simple Autocomplete example that binds to a **simple** `Contact` from a `List<Contact>` in **allContacts**:

```html
<Autocomplete T="Contact" Options="allContacts" @bind-Value="simple" Label="Single Contact"
    Match="(x, value) => x!.DisplayName.Contains(value, StringComparison.OrdinalIgnoreCase)"
    placeholder="Select Contact">
    <Item>
        <span class="block truncate">@context!.DisplayName</span>
    </Item>
</Autocomplete>
```

### Single Contact with Icon

The item content is templated allowing for rich content which can be used to display a Contact's profile picture and name:

```html
<Autocomplete T="Contact" Options="allContacts" @bind-Value="contact" Label="Single Contact with Icon"
    Match="(x, value) => x!.DisplayName.Contains(value, StringComparison.OrdinalIgnoreCase)"
    placeholder="Select Contact">
    <Item>
        <div class="flex items-center">
            <Icon class="h-6 w-6 flex-shrink-0 rounded-full" Src=@context.ProfileUrl />
            <span class="ml-3 truncate">@context!.DisplayName</span>
        </div>
    </Item>
</Autocomplete>
```

### Multiple Contacts with Icon

It also supports multiple selection by using `@bind-Values` to bind to the `List<Contact>` in **contacts** instead, e.g:

```html
<Autocomplete Options="allContacts" @bind-Values="contacts" Label="Multiple Contacts with Icon"
    Match="(x, value) => x!.DisplayName.Contains(value, StringComparison.OrdinalIgnoreCase)"
    placeholder="Select Contacts">
    <Item>
        <div class="flex items-center">
            <Icon class="h-6 w-6 flex-shrink-0 rounded-full" Src=@context.ProfileUrl />
            <span class="ml-3 truncate">@context!.DisplayName</span>
        </div>
    </Item>
</Autocomplete>
```

and here's a working example of what they look like together in the same form ([example source code](https://blazor-gallery.jamstacks.net/gallery/inputs)):

<div class="pt-12 flex justify-center">
    <iframe src="https://blazor-gallery.jamstacks.net/gallery/inputs/autocomplete" class="w-[500px] border-none h-[560px]"></iframe>
</div>

## TagInput

The TagInput component is useful for when you want to manage a list of strings like words or tags - an input that's notably lacking in HTML Forms.
Best of all `<TagInput>` functions like any other input where it can be included and customized in declarative forms. 

For example this Update AutoQuery Request DTO:

```csharp
// Customize Edit Forms with [Input] and [FieldCss] attributes 
public class UpdateContact : IPatchDb<Contact>, IReturn<Contact>
{
    public int Id { get; set; }

    [ValidateNotEmpty]
    public string? FirstName { get; set; }

    [ValidateNotEmpty]
    public string? LastName { get; set; }

    [Input(Type = "file"), UploadTo("profiles")]
    public string? ProfileUrl { get; set; }
    
    public int? SalaryExpectation { get; set; }

    [ValidateNotEmpty]
    public string? JobType { get; set; }

    public int? AvailabilityWeeks { get; set; }
    public EmploymentType? PreferredWorkType { get; set; }
    public string? PreferredLocation { get; set; }

    [ValidateNotEmpty]
    public string? Email { get; set; }
    public string? Phone { get; set; }
    
    [Input(Type = "tag"), FieldCss(Field = "col-span-12")]
    public List<string>? Skills { get; set; }}
 
    [Input(Type="textarea")]
    [FieldCss(Field="col-span-12 text-center", Input="h-48", Label="text-xl text-indigo-700")]
    public string? About { get; set; }
}
```

is all that's needed to render an instantly working API-enabled Form with validation binding using 
[Auto Form components](https://blazor-gallery.jamstacks.net/gallery/autoform):

```html
<AutoEditForm class=@Class Model="Contact" ApiType="typeof(UpdateContact)" Edit=@contact />
```

Which by default renders the form in a SlideOver dialog as seen when editing a row in the [Contacts AutoQueryGrid](https://blazor-gallery.jamstacks.net/grid/contacts-meta?edit=1) component:

<iframe src="https://blazor-gallery.jamstacks.net/grid/contacts-meta/embed?edit=1" class="mt-8 w-full border-none h-[970px]"></iframe>

Alternatively it can be rendered in a traditional **"card"** form layout with the new `FormStyle.Card` option:

```html
<AutoEditForm class=@Class FormStyle="FormStyle.Card" Model="Contact" ApiType="typeof(UpdateContact)" Edit=@contact />
```

<iframe src="https://blazor-gallery.jamstacks.net/gallery/inputs/tag?layout=ExampleLayout&class=max-w-screen-md+mx-auto" class="mt-8 w-full border-none h-[1570px]"></iframe>

Where it functions the same as other Input components where it can be bound directly to a `List<string>` Request DTO property:

```html
<form @onsubmit="submit" @onsubmit:preventDefault class=@Class>
<CascadingValue Value=@apiQuery.Error>
    <div class="shadow sm:rounded-md bg-white dark:bg-black">
        <div class="relative px-4 py-5 sm:p-6">
            <fieldset>
                <ErrorSummary Except=@VisibleFields />

                <div class="grid grid-cols-12 gap-6">
                    <div class="col-span-6">
                        <TextInput @bind-Value="request.FirstName" />
                    </div>

                    <div class="col-span-6">
                        <TextInput @bind-Value="request.LastName" />
                    </div>

                    <div class="col-span-12">
                        <TagInput @bind-Value="request.Skills" />
                    </div>
                </div>
            </fieldset>
        </div>
    </div>
</CascadingValue>
</form>
```

### NavList

The NavList component encapsulates Tailwind's beautiful List component which is used extensively in [Blazor Gallery's Navigation](https://blazor-gallery.jamstacks.net/grid):

```html
<div class="max-w-screen-sm">
    <NavList Title="Explore Blazor Components">
        <NavListItem Title="DataGrid" href="/gallery/datagrid" IconSvg=@Icons.DataGrid>
            DataGrid Component Examples for rendering tabular data
        </NavListItem>
        <NavListItem Title="AutoQuery Grid" href="/gallery/autoquerygrid" IconSvg=@Icons.AutoQueryGrid>
            Instant customizable UIs for calling AutoQuery CRUD APIs
        </NavListItem>
    </NavList>

    <h2 class="mt-8 text-base font-semibold text-gray-500 dark:text-gray-400 flex">
        <span title="Requires Auth"><Icon class="h-6 w-6 mr-2" Svg=@Icons.Padlock /></span>
        Booking APIs
    </h2>
    <NavList>
        <NavListItem Title="Bookings" href="/grid/bookings" Icon=@typeof(Booking).GetIcon()>
            Create and manage Bookings
        </NavListItem>
        <NavListItem Title="Coupons" href="/grid/coupons" Icon=@typeof(Coupon).GetIcon()>
            Create and manage discount Coupons
        </NavListItem>
    </NavList>
</div>
```

Where it will render a list of navigation links with descriptions and icons:

<div class="my-8 flex justify-center">
    <iframe src="https://blazor-gallery.jamstacks.net/gallery/navigation/navlist" class="my-8 w-full h-[510px] border-none"></iframe>
</div>

### Colored Buttons

The `ButtonStyle` on PrimaryButton component can be used to render buttons into Tailwind's different primary colors:

```csharp
<div class="grid gap-4 grid-cols-3">
    <PrimaryButton>Default</PrimaryButton>
    <PrimaryButton Style="ButtonStyle.Blue">Blue</PrimaryButton>
    <PrimaryButton Style="ButtonStyle.Purple">Purple</PrimaryButton>
    <PrimaryButton Style="ButtonStyle.Red">Red</PrimaryButton>
    <PrimaryButton Style="ButtonStyle.Green">Green</PrimaryButton>
    <PrimaryButton Style="ButtonStyle.Sky">Sky</PrimaryButton>
    <PrimaryButton Style="ButtonStyle.Cyan">Cyan</PrimaryButton>
</div>
```

<div class="my-8 flex justify-center">
    <iframe src="https://blazor-gallery.jamstacks.net/gallery/navigation/buttons/styles" class="my-8 w-full h-[160px] border-none"></iframe>
</div>

### Select Input

The `<SelectInput>` `Values` and `Entries` parameters can be used to populate options from an array of string's or KeyValuePair's, it also includes declarative features enabling more capable declarative forms which are typically restricted by the compile-time constant expression limitation of .NET attributes. 

The `EvalAllowableValues` and `EvalAllowableEntries` attribute properties overcomes this limitation by letting you define the Select options with a [#Script](https://sharpscript.net) Expression whose great [.NET scriptability](https://sharpscript.net/docs/script-net) lets you reference your App's .NET instances from a string expression. This feature can then be used to populate declarative Select options from a .NET Instance, e.g:

```csharp
public class CreateModifier : ICreateDb<Modifier>, IReturn<Modifier>
{
    [ValidateNotEmpty]
    public string Name { get; set; }

    [ValidateNotEmpty]
    [Input(Type="select", EvalAllowableValues = "AppData.Categories")]
    public string Category { get; set; }
 
    public string? Description { get; set; }
}
```

That we register as a global variable in our AppHost's `ScriptContext` which we can populate from a dynamic source like a DB Table, e.g:

```csharp
using var db = container.Resolve<IDbConnectionFactory>().Open();
ScriptContext.Args[nameof(AppData)] = new AppData
{
    Categories = db.Column<string>(db.From<Category>().Select(x => x.Name))
};
```

Where it will populate the Select input in all `CreateModifier` Auto Form components:

<div class="mt-8 flex justify-center">
    <img src="/img/pages/blazor/diffusion-CreateModifier.png" class="max-w-screen-md" style="border:1px solid #CACACA">
</div>

## PreviewFormat

The `<PreviewFormat>` component is useful for rendering Table Cell data into different customizable formats, e.g:

```html
<PreviewFormat Value="50" Format=Formats.Currency />

<PreviewFormat Value="1000000" Format=Formats.Bytes />

<PreviewFormat Value=@Url Format=Formats.Icon IconClass="w-40 h-40" />

<PreviewFormat Value=@Url Format=Formats.Icon IconClass="w-40 h-40 rounded-full" />

<PreviewFormat Value=@Url Format=Formats.Attachment />

<PreviewFormat Value=@Path Format=Formats.Attachment />

<PreviewFormat Value=@Url Format=Formats.Link />

<PreviewFormat Value=@Email Format=Formats.LinkEmail />

<PreviewFormat Value=@Phone Format=Formats.LinkPhone />
```

[![](/img/pages/blazor/PreviewFormat.png)](https://blazor-gallery.servicestack.net/gallery/formats)

## HtmlFormat

Whilst the versatile `<HtmlFormat>` component can be used to render any Serializable object into a human-friendly HTML Format, e.g:

### Single Model

```html
<div class="max-w-screen-sm">
    <HtmlFormat Value=@Track.Results[0] />
</div>
```

[![](/img/pages/blazor/HtmlFormat-single.png)](https://blazor-gallery.servicestack.net/gallery/formats)

### Item Collections

```html
<div class="max-w-screen-sm">
    <HtmlFormat Value=@Track.Results />
</div>
```

[![](/img/pages/blazor/HtmlFormat-collection.png)](https://blazor-gallery.servicestack.net/gallery/formats)

### Nested Complex Types

```html
<HtmlFormat Value=@Create.Players />
```

[![](/img/pages/blazor/HtmlFormat-complex.png)](https://blazor-gallery.servicestack.net/gallery/formats)

For more info about the Blazor Components available checkout the [Component Gallery](https://blazor-gallery.servicestack.net/gallery):

[![](/img/pages/blazor/component-gallery.png)](https://blazor-gallery.servicestack.net/gallery)

## Blazor Config

A lot of the default conventions used by the Blazor Components are overridable with [BlazorConfig](https://reference.servicestack.net/api/ServiceStack.Blazor/BlazorConfig) initialized in `Program.cs`, where Blazor WASM projects configured with something like:

```csharp
BlazorConfig.Set(new BlazorConfig
{
    IsWasm = true,
    Services = app.Services,
    FallbackAssetsBasePath = apiBaseUrl,
    EnableLogging = true,
    EnableVerboseLogging = builder.HostEnvironment.IsDevelopment(),
});
```

### Asset and Fallback Paths

Where `FallbackAssetsBasePath` allows you to specify a fallback path for Images which is useful when there's a delay for syncing uploaded assets to the CDN that the Blazor WASM client is deployed to, as it can fallback to referencing the asset from the .NET App Server that handled the file upload. 

Alternatively `AssetsBasePath` can be used for specifying a different primary CDN location that's different from the Blazor WASM App CDN or `AssetsPathResolver` and `FallbackPathResolver` can be used when more a advanced custom strategy is required.


# Blazor Diffusion
Source: https://docs.servicestack.net/blazor-diffusion

The goal of our increasing Blazor investments is to enable a highly productive and capable platform for rapidly developing a majority of internal Apps CRUD functionality as well as enabling a hybrid development model where the management of Back office supporting tables can be quickly implemented using custom AutoQueryGrid components freeing up developers to be able to focus a majority of their efforts where they add the most value - in the bespoke Blazor UI's optimized customer-facing UX.

To best demonstrate its potential we've embarked on development of a new project we're excited to announce that does exactly this!

<div class="not-prose my-8 flex justify-center">
    <a href="https://blazordiffusion.com" class="flex items-center hover:no-underline" title="blazordiffusion.com">
        <svg class="w-20 h-20 text-purple-600 mr-2" xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24"><path fill="currentColor" d="M23.834 8.101a13.912 13.912 0 0 1-13.643 11.72a10.105 10.105 0 0 1-1.994-.12a6.111 6.111 0 0 1-5.082-5.761a5.934 5.934 0 0 1 11.867-.084c.025.983-.401 1.846-1.277 1.871c-.936 0-1.374-.668-1.374-1.567v-2.5a1.531 1.531 0 0 0-1.52-1.533H8.715a3.648 3.648 0 1 0 2.695 6.08l.073-.11l.074.121a2.58 2.58 0 0 0 2.2 1.048a2.909 2.909 0 0 0 2.695-3.04a7.912 7.912 0 0 0-.217-1.933a7.404 7.404 0 0 0-14.64 1.603a7.497 7.497 0 0 0 7.308 7.405s.549.05 1.167.035a15.803 15.803 0 0 0 8.475-2.528c.036-.025.072.025.048.061a12.44 12.44 0 0 1-9.69 3.963a8.744 8.744 0 0 1-8.9-8.972a9.049 9.049 0 0 1 3.635-7.247a8.863 8.863 0 0 1 5.229-1.726h2.813a7.915 7.915 0 0 0 5.839-2.578a.11.11 0 0 1 .059-.034a.112.112 0 0 1 .12.053a.113.113 0 0 1 .015.067a7.934 7.934 0 0 1-1.227 3.549a.107.107 0 0 0-.014.06a.11.11 0 0 0 .073.095a.109.109 0 0 0 .062.004a8.505 8.505 0 0 0 5.913-4.876a.155.155 0 0 1 .055-.053a.15.15 0 0 1 .147 0a.153.153 0 0 1 .054.053A10.779 10.779 0 0 1 23.834 8.1zM8.895 11.628a2.188 2.188 0 1 0 2.188 2.188v-2.042a.158.158 0 0 0-.15-.15Z"/></svg>
        <h2 class="border-none text-4xl sm:text-5xl md:text-6xl tracking-tight font-extrabold">
            <span class="text-purple-600 mr-6">Diffusion</span>
        </h2>
    </a>
</div>

[![blazordiffusion.com](/img/pages/blazor/blazordiffusion.com_splash.png)](https://blazordiffusion.com)


[blazordiffusion.com](https://blazordiffusion.com) is a new ServiceStack.Blazor App front-end for [Stable Diffusion](https://en.wikipedia.org/wiki/Stable_Diffusion) - a deep learning text-to-image model that can generate quality images from a text prompt whose ability to run on commodity GPU hardware makes it 
one of the most exciting Open Source AI projects ever released. If you haven't experienced Stable Diffusion yet, we welcome you to create an account and start building your Stable Diffusion portfolio for FREE!

### Effortless Admin Pages

It's a great example of Hybrid Development in action where the entire user-facing UI is a bespoke Blazor App that's optimized for creating, searching, cataloging and discovering Stable Diffusion generated images, whilst all its supporting admin tasks to manage the back office tables that power the UI were effortlessly implemented with custom AutoQueryGrid components. 

To get a glimpse of this in action we've created a video showing how quick it was to build the first few Admin Pages:

<div class="my-8 flex justify-center">
    <lite-youtube class="w-full mx-4 my-4" width="560" height="315" videoid="tt0ytzVVjEY" style="background-image: url('https://img.youtube.com/vi/tt0ytzVVjEY/maxresdefault.jpg')"></lite-youtube>
</div>

Blazor Diffusion is an example of a real-world App leveraging a number of different ServiceStack features to achieve its functionality that we're using to ["dog food"](https://en.wikipedia.org/wiki/Eating_your_own_dog_food) new ServiceStack features to help identify any friction points or missing functionality that we can feedback into the design and improvements of new and existing features, which it has done for most of the new features in this release.

### Blazor Server or Blazor WASM

To ensure all new ServiceStack.Blazor features continue to work in both Blazor Server and Blazor WASM we're maintaining identical versions of Blazor Diffusion running in both of Blazor's hosting modes:

<div class="py-8 flex justify-center">
    <div class="flex flex-col">
    <a href="https://github.com/NetCoreApps/BlazorDiffusion" class="text-xl text-gray-800 flex">
        <svg class="w-6 h-6 mr-2 align-text-bottom" xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24"><path fill="currentColor" d="M12 .297c-6.63 0-12 5.373-12 12c0 5.303 3.438 9.8 8.205 11.385c.6.113.82-.258.82-.577c0-.285-.01-1.04-.015-2.04c-3.338.724-4.042-1.61-4.042-1.61C4.422 18.07 3.633 17.7 3.633 17.7c-1.087-.744.084-.729.084-.729c1.205.084 1.838 1.236 1.838 1.236c1.07 1.835 2.809 1.305 3.495.998c.108-.776.417-1.305.76-1.605c-2.665-.3-5.466-1.332-5.466-5.93c0-1.31.465-2.38 1.235-3.22c-.135-.303-.54-1.523.105-3.176c0 0 1.005-.322 3.3 1.23c.96-.267 1.98-.399 3-.405c1.02.006 2.04.138 3 .405c2.28-1.552 3.285-1.23 3.285-1.23c.645 1.653.24 2.873.12 3.176c.765.84 1.23 1.91 1.23 3.22c0 4.61-2.805 5.625-5.475 5.92c.42.36.81 1.096.81 2.22c0 1.606-.015 2.896-.015 3.286c0 .315.21.69.825.57C20.565 22.092 24 17.592 24 12.297c0-6.627-5.373-12-12-12"/></svg>
        <span>NetCoreApps/BlazorDiffusion</span>
    </a>
    <a href="https://github.com/NetCoreApps/BlazorDiffusionWasm" class="mt-2 text-xl text-gray-800 flex">
        <svg class="w-6 h-6 mr-2 align-text-bottom" xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24"><path fill="currentColor" d="M12 .297c-6.63 0-12 5.373-12 12c0 5.303 3.438 9.8 8.205 11.385c.6.113.82-.258.82-.577c0-.285-.01-1.04-.015-2.04c-3.338.724-4.042-1.61-4.042-1.61C4.422 18.07 3.633 17.7 3.633 17.7c-1.087-.744.084-.729.084-.729c1.205.084 1.838 1.236 1.838 1.236c1.07 1.835 2.809 1.305 3.495.998c.108-.776.417-1.305.76-1.605c-2.665-.3-5.466-1.332-5.466-5.93c0-1.31.465-2.38 1.235-3.22c-.135-.303-.54-1.523.105-3.176c0 0 1.005-.322 3.3 1.23c.96-.267 1.98-.399 3-.405c1.02.006 2.04.138 3 .405c2.28-1.552 3.285-1.23 3.285-1.23c.645 1.653.24 2.873.12 3.176c.765.84 1.23 1.91 1.23 3.22c0 4.61-2.805 5.625-5.475 5.92c.42.36.81 1.096.81 2.22c0 1.606-.015 2.896-.015 3.286c0 .315.21.69.825.57C20.565 22.092 24 17.592 24 12.297c0-6.627-5.373-12-12-12"/></svg>
        <span>NetCoreApps/BlazorDiffusionWasm</span>
    </a>
    </div>
</div>

Where it's initially developed from a Blazor Server project template to take advantage of its fast iterative dev model then uses a [script to export](https://github.com/NetCoreApps/BlazorDiffusionWasm/blob/main/sync.bat) all Pages and Server functionality to a Blazor WASM project template that's optimal for Internet deployments.

### Blazor Diffusion Features

To help discovery we'll link to where new features in this release are used.

<svg class="w-20 h-20 text-gray-800" xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24"><path fill="currentColor" d="M9.37 5.51A7.35 7.35 0 0 0 9.1 7.5c0 4.08 3.32 7.4 7.4 7.4c.68 0 1.35-.09 1.99-.27A7.014 7.014 0 0 1 12 19c-3.86 0-7-3.14-7-7c0-2.93 1.81-5.45 4.37-6.49zM12 3a9 9 0 1 0 9 9c0-.46-.04-.92-.1-1.36a5.389 5.389 0 0 1-4.4 2.26a5.403 5.403 0 0 1-3.14-9.8c-.44-.06-.9-.1-1.36-.1z"/></svg>

### Dark Mode

The decision to build [blazordiffusion.com](https://blazordiffusion.com) was in large part due to choosing an App that would look best in Dark Mode, as-is often preferred when viewing images and video. The public UI uses [JS.init() to force Dark Mode](https://github.com/NetCoreApps/BlazorDiffusion/blob/v0.1/BlazorDiffusion/Pages/_Layout.cshtml#L63) whilst the Admin Pages uses a different [AdminLayout.razor](https://github.com/NetCoreApps/BlazorDiffusion/blob/v0.1/BlazorDiffusion/Shared/AdminLayout.razor) that allows dark mode to be toggled on/off as seen in the [BlazorDiffusion Video](https://www.youtube.com/watch?v=tt0ytzVVjEY).

### AutoComplete

The [Create.razor](https://github.com/NetCoreApps/BlazorDiffusion/blob/v0.1/BlazorDiffusion/Pages/Create.razor) uses the new `<Autocomplete>` to quickly select Artists 
and Modifiers.

<div class="mt-8 flex justify-center">
    <a href="https://github.com/NetCoreApps/BlazorDiffusion/blob/main/BlazorDiffusion/Pages/Create.razor">
        <img src="/img/pages/blazor/blazordiffusion-Autocomplete.png" style="width:600px">
    </a>
</div>

### Admin Pages

The [/admin](https://github.com/NetCoreApps/BlazorDiffusion/tree/main/BlazorDiffusion/Pages/admin) pages we're all built using [AutoQueryGrid](https://blazor-gallery.jamstacks.net/grid) for its data management and uses [NavList and Breadcrumbs](https://blazor-gallery.jamstacks.net/gallery/navigation) for its navigation.

<div class="flex justify-center">
    <a href="https://github.com/NetCoreApps/BlazorDiffusion/blob/main/BlazorDiffusion/Pages/admin/Index.razor">
        <img src="/img/pages/blazor/blazordiffusion-admin-pages.png" style="width:600px">
    </a>
</div>

#### EditForm

The following components make use of `<EditForm>` AutoQueryGrid extensibility to display unique forms for their custom workflow requirements:

 - [Creatives.razor](https://github.com/NetCoreApps/BlazorDiffusion/blob/main/BlazorDiffusion/Pages/admin/Creatives.razor)
 - [ArtifactAutoQueryGrid.razor](https://github.com/NetCoreApps/BlazorDiffusion/blob/main/BlazorDiffusion/Shared/admin/ArtifactAutoQueryGrid.razor)
 - [ArtifactReportsAutoQueryGrid.razor](https://github.com/NetCoreApps/BlazorDiffusion/blob/main/BlazorDiffusion/Shared/admin/ArtifactReportsAutoQueryGrid.razor)

```csharp
<AutoQueryGrid @ref=@grid Model="Creative" Apis="Apis.AutoQuery<QueryCreatives,UpdateCreative,HardDeleteCreative>()"
               ConfigureQuery="ConfigureQuery">
    <EditForm>
        <div class="relative z-10" aria-labelledby="slide-over-title" role="dialog" aria-modal="true">
            <div class="pointer-events-none fixed inset-y-0 right-0 flex max-w-full pl-10 sm:pl-16">
                <CreativeEdit Creative="context" OnClose="grid!.OnEditDone" />
            </div>
        </div>
    </EditForm>
</AutoQueryGrid>
```

### SelectInput

The [Modifiers.razor](https://github.com/NetCoreApps/BlazorDiffusion/blob/main/BlazorDiffusion/Pages/admin/Modifiers.razor) admin page uses 
[SelectInput EvalAllowableValues](https://github.com/NetCoreApps/BlazorDiffusion/blob/v0.1/BlazorDiffusion.ServiceModel/Creative.cs#L168-L187) feature to populate its options from a C# [AppData](https://github.com/NetCoreApps/BlazorDiffusion/blob/v0.1/BlazorDiffusion.ServiceModel/AppData.cs) property:

```csharp
public class CreateModifier : ICreateDb<Modifier>, IReturn<Modifier>
{
    [ValidateNotEmpty, Required]
    public string Name { get; set; }
    [ValidateNotEmpty, Required]
    [Input(Type="select", EvalAllowableValues = "AppData.Categories")]
    public string Category { get; set; }
    public string? Description { get; set; }
}
```

<div class="mt-8 flex justify-center">
    <img src="/img/pages/blazor/diffusion-CreateModifier.png" class="max-w-screen-md" style="border:1px solid #CACACA">
</div>

### TagInput

The [Artists.razor](https://github.com/NetCoreApps/BlazorDiffusion/blob/main/BlazorDiffusion/Pages/admin/Artists.razor) admin page uses [declarative TagInput](https://github.com/NetCoreApps/BlazorDiffusion/blob/v0.1/BlazorDiffusion.ServiceModel/Creative.cs#L122-L141) to render its AutoQueryGrid Create and Edit Forms:

```csharp
public class UpdateArtist : IPatchDb<Artist>, IReturn<Artist>
{
    public int Id { get; set; }
    public string? FirstName { get; set; }
    public string? LastName { get; set; }
    public int? YearDied { get; set; }
    [Input(Type = "tag"), FieldCss(Field = "col-span-12")]
    public List<string>? Type { get; set; }
}
```

<div class="my-8 flex justify-center">
    <img src="/img/pages/blazor/blazordiffusion-TagInput.png" class="max-w-screen-md" style="border:1px solid #CACACA">
</div>

<h2 id="litestream" class="mx-auto max-w-screen-md text-center py-8 border-none">
    <a href="https://litestream.io">
        <img src="/img/pages/litestream/logo.svg">
    </a>
</h2>

We're excited to be able to leverage our [support for Litestream](/ormlite/litestream) and showcase an example of architecting a production App at minimal cost which avoids paying for expensive managed hosted RDBMS's by effortlessly replicating its SQLite databases to object storage.

<div class="mt-16 mx-auto max-w-7xl px-4">
    <div class="text-center">
        <h3 class="text-4xl tracking-tight font-extrabold text-gray-900 sm:text-5xl md:text-6xl">
            <span class="block xl:inline">Reduce Complexity &amp; Save Costs</span>
        </h3>
        <p class="mt-3 max-w-md mx-auto text-base text-gray-500 sm:text-lg md:mt-5 md:text-xl md:max-w-3xl">
            Avoid expensive managed RDBMS servers, reduce deployment complexity, eliminate 
            infrastructure dependencies & save order of magnitude costs vs production hosting
        </p>
    </div>
    <img src="/img/pages/litestream/litestream-costs.svg">
</div>

To make it easy for Blazor Tailwind projects to take advantage of our first-class [Litestream support](/ormlite/litestream), we've created a new video combining these ultimate developer experience & value combo solutions that walks through how to deploy a new Blazor Tailwind SQLite + Litestream App to any Linux server with SSH access, Docker and Docker Compose:

<lite-youtube class="w-full mx-4 my-4" width="560" height="315" videoid="fY50dWszpw4" style="background-image: url('https://img.youtube.com/vi/fY50dWszpw4/maxresdefault.jpg')"></lite-youtube>

### Useful Blazor Litestream Video Links

- [Blazor Litestream Tutorial](/blazor-litestream)
- [Blazor](https://servicestack.net/blazor)
- [Litestream](https://servicestack.net/litestream)
- [Docker Install](https://docs.docker.com/engine/install/ubuntu/)
- [Docker Compose Install](https://docs.docker.com/compose/install/linux/#install-using-the-repository)

### Custom SQLite functions

Using SQLite also gives us access to features not available in other RDBMS's, e.g. for the "Explore Similar Artifacts" feature we're using a custom registered C# function that we can use in SQL to find other Artifacts with the nearest background colors in [SearchService.cs](https://github.com/NetCoreApps/BlazorDiffusion/blob/v0.1/BlazorDiffusion.ServiceInterface/SearchService.cs):

```csharp
public static class DbFunctions
{
    public static void RegisterBgCompare(this IDbConnection db)
    {
        var sqliteConn = (SqliteConnection)db.ToDbConnection();
        sqliteConn.CreateFunction("bgcompare", (string a, string b) => ImageUtils.BackgroundCompare(a, b));
    }
}
```

After registering the function with the db connection we can reference it in our typed SQL Expression with OrmLite's `Sql.Custom()` API:

```csharp
db.RegisterBgCompare();
q.SelectDistinct<Artifact, Creative>((a, c) => new {
    a,
    c.UserPrompt,
    c.ArtistNames,
    c.ModifierNames,
    c.PrimaryArtifactId,
    Similarity = Sql.Custom($"bgcompare('{similarToArtifact.Background}',Background)"),
});
```

This same technique is also used for finding similar images by [PerceptualHash](https://www.hackerfactor.com/blog/index.php?/archives/432-Looks-Like-It.html), [AverageHash](https://www.hackerfactor.com/blog/index.php?/archives/432-Looks-Like-It.html) & [DifferenceHash](http://01101001.net/programming.php) functions provided by the [ImageHash](https://github.com/coenm/ImageHash) library.

The [SearchService.cs](https://github.com/NetCoreApps/BlazorDiffusion/blob/v0.1/BlazorDiffusion.ServiceInterface/SearchService.cs) itself is a great example of a complex [custom AutoQuery implementation](/autoquery/rdbms#custom-autoquery-implementations) which is solely responsible for providing the entire search functionality on the home page. 

### Hetzner US Cloud

Our analysis of [US Cloud Hosting Providers](https://servicestack.net/blog/finding-best-us-value-cloud-provider) led us to moving to [Hetzner Cloud](https://www.hetzner.com/cloud) for hosting where it costs vastly less than equivalent specs at a major cloud provider. But this also meant we also had to look elsewhere to also avoid AWS's expensive egress costs for S3 for image storage which can easily get out of control for a highly traffic image host. 

### R2 Virtual Files Provider

Fortunately we were in time to take advantage of Cloudflare's inexpensive [R2 Object Storage solution](https://www.cloudflare.com/products/r2/) with **$0 egress fees**, together with their generous free tier and ability to serve R2 assets behind their free CDN, we ended up with great value and performance managed cloud storage solution with the only cost expected in the near future to be R2's **$0.015 / GB storage** cost.

R2 is mostly S3 compatible however it needed a custom `S3VirtualFiles` provider to workaround missing features which is being maintained in the new `R2VirtualFiles` VFS provider.

### Files Upload Transformer

The [Managed Files Upload Feature](/locode/files-overview) is configured in [Configure.AppHost.cs](https://github.com/NetCoreApps/BlazorDiffusion/blob/main/BlazorDiffusion/Configure.AppHost.cs) and used for all website File Uploads:

```csharp
var appFs = VirtualFiles = new R2VirtualFiles(s3Client, appConfig.ArtifactBucket);
Plugins.Add(new FilesUploadFeature(
    new UploadLocation("artifacts", appFs,
        readAccessRole: RoleNames.AllowAnon,
        maxFileBytes: AppData.MaxArtifactSize),
    new UploadLocation("avatars", appFs, allowExtensions: FileExt.WebImages, 
        // Use unique URL to invalidate CDN caches
        resolvePath: ctx => X.Map((CustomUserSession)ctx.Session, x => $"/avatars/{x.RefIdStr[..2]}/{x.RefIdStr}/{ctx.FileName}")!,
        maxFileBytes: AppData.MaxAvatarSize,
        transformFile:ImageUtils.TransformAvatarAsync)
    ));
```

It utilizes the new **transformFile:** option to transform an uploaded file and save a reference to the transformed file instead. This is used to only save a reference to the **128x128** resized avatar used by the App, whilst still persisting the original uploaded image in a [Background MQ](/background-mq) task in case a higher resolution of their avatar is needed later.

```csharp
public class ImageDetails
{
    public static async Task<IHttpFile?> TransformAvatarAsync(FilesUploadContext ctx)
    {
        var originalMs = await ctx.File.InputStream.CopyToNewMemoryStreamAsync();

        // Offload persistance of original image to background task
        using var mqClient = HostContext.AppHost.GetMessageProducer(ctx.Request);
        mqClient.Publish(new DiskTasks {
            SaveFile = new() {
                FilePath = ctx.Location.ResolvePath(ctx),
                Stream = originalMs,
            }
        });

        var resizedMs = await CropAndResizeAsync(originalMs, 128, 128, PngFormat.Instance);

        return new HttpFile(ctx.File)
        {
            FileName = $"{ctx.FileName.LastLeftPart('.')}_128.{ctx.File.FileName.LastRightPart('.')}",
            ContentLength = resizedMs.Length,
            InputStream = resizedMs,
        };
    }

    public static async Task<MemoryStream> CropAndResizeAsync(Stream inStream, int width, int height, IImageFormat format)
    {
        var outStream = new MemoryStream();
        var image = await Image.LoadAsync(inStream);
        using (image)
        {
            var clone = image.Clone(context => context
                .Resize(new ResizeOptions {
                    Mode = ResizeMode.Crop,
                    Size = new Size(width, height),
                }));
            await clone.SaveAsync(outStream, format);
        }
        outStream.Position = 0;
        return outStream;
    }
}
```

### Background MQ

[Background MQ](/background-mq) is utilized to improve API response times by offloading a number of non-essential background tasks in [BackgroundMqServices.cs](https://github.com/NetCoreApps/BlazorDiffusion/blob/main/BlazorDiffusion.ServiceInterface/BackgroundMqServices.cs) to perform functions like:

 - Saving JSON metadata snapshot of Stable Diffusion generated images alongside the images themselves
 - Write Files to R2
 - Recalculating temporal scores and ranking of Artifacts and Albums
 - Recording Analytics


# Files Blazor
Source: https://docs.servicestack.net/locode/files-blazor

<main class="not-prose hide-title mt-8 mx-auto max-w-7xl px-4 sm:mt-12">
    <div class="text-center">
        <h1 class="text-4xl tracking-tight font-extrabold text-gray-900 sm:text-5xl md:text-6xl">
            <span class="block xl:inline">File Blazor </span>
            <span class="block text-indigo-600 xl:inline">Managed File Upload Example</span>
        </h1>
        <p class="mt-3 max-w-md mx-auto text-base text-gray-500 sm:text-lg md:mt-5 md:text-xl md:max-w-3xl">ServiceStack's 
            <code class="bg-blue-50 text-blue-500 py-1 px-2 rounded">FileUploadFeature</code>
            provides an easy and flexible way to create API services backed by either popular cloud solutions like AWS S3, Azure Blob Storage, or your own file system.
        </p>
    </div>
</main>
<div class="not-prose relative py-8 bg-white overflow-hidden">
    <div class="relative px-4 sm:px-6 lg:px-8">
        <div class="text-lg max-w-prose mx-auto">
            <h1>
                <span class="block text-base text-center text-indigo-600 font-semibold tracking-wide uppercase">Introducing</span>
                <span class="mt-2 block text-3xl text-center leading-8 font-extrabold tracking-tight text-gray-900 sm:text-4xl">
                    <a href="https://github.com/NetCoreApps/FileBlazor">NetCoreApps/FileBlazor</a>                    
                </span>
            </h1>
            <p class="mt-8 text-xl text-gray-500 leading-8">
                <a href="https://github.com/NetCoreApps/FileBlazor">NetCoreApps/FileBlazor</a> is a Blazor Demo utilizing the 
                <code class="bg-blue-50 text-blue-500 py-1 px-2 rounded">FileUploadFeature</code>
                plugin to provide an easy and flexible solution for quickly creating APIs services for uploading/downloading files to a variety of storage types.
            </p>
        </div>
    </div>
</div>

<figure class="m-2">
    <img src="/img/pages/locode/files/fileupload-config-plugin.png" alt="">
    <figcaption>Configuration of IVirtualFiles and FileUploadPlugin</figcaption>
</figure>

By utilizing **AutoQuery** and **Locode** features, you also get a generated UI to use for back office staff or to use for prototyping. In this demo we configure three different storage types which integrate directly with your own database tables.

- AWS S3 Bucket
- Azure Blob Storage Container
- Local Application File System

<figure class="m-2">
    <img src="/img/pages/locode/files/fileupload-datamodel.png" alt="">
    <figcaption>Define your database tables to store file metadata.</figcaption>
</figure>

The FileUploadFeature plugin uses the ServiceStack IVirtualFiles abstraction where multiple named providers can be used and referenced against your database model. Your own database stores metadata about each file including a reference to HTTP file path where the file where it can be downloaded.

## Driven by your request DTOs

Your table data for the files in this demo are then shared using **AutoQuery** services. AutoQuery provides the overridable service implementation to manage this data, this is where you can link your FileUploadFeature to specific table data using the `UploadTo` attribute.

<figure class="m-2">
    <img src="/img/pages/locode/files/fileupload-create-dto.png" alt="">
    <figcaption>Define your request Data Transfer Objects (DTOs) and use `UploadTo` with the related named UploadLocation.</figcaption>
</figure>

## Upload Files Using Locode

ServiceStack Locode App integrates with the FileUploadFeature plugin to enable a way to manage your files straight away.

<figure>
    <img src="/img/pages/locode/files/locode-app-create-s3.png" alt="">
    <figcaption>Instant upload form using Locode App.</figcaption>
</figure>

## Overridable filters in the plugin

The UploadFeaturePlugin provides overridable options to better control upload/download rules. In this demo, `Public`, `Team` and `Private` files are stored in single table for each upload location.

Access rules are configured for each of the upload locations independently using the following plugin options.

- **readAccessRole** - Can limit read access to specific user roles
- **resolvePath** - Control how the upload path is created
- **validateUpload** - Filter upload requests
- **validateDownload** - Filter download requests

## Integrate API services with a custom UI

Since AutoQuery services are ServiceStack services, they benefit from being highly interoperable. This FileBlazor demo uses native Blazor components to upload to the generated API services providing a user friendly drag and drop interface.

Navigate to the public [S3](/aws/public), [Azure](/azure/public) or [File System](/filesystem/public)
file galleries on the left to preview files without authenticating, or login to see the different file access types and upload files yourself.

<div class="not-prose my-8 flex justify-center">
    <a href="https://github.com/NetCoreApps/FileBlazor" 
        class="hover:text-black inline-flex no-underline hover:no-underline items-center px-6 py-3 border border-gray-300 shadow text-base font-medium rounded-md text-gray-700 bg-white hover:bg-gray-50 focus:outline-none focus:ring-2 focus:ring-offset-2 focus:ring-indigo-500">
        <svg class="w-6 h-6" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24">
            <g fill="none">
                <path fill-rule="evenodd" clip-rule="evenodd" d="M12 0C5.37 0 0 5.37 0 12c0 5.31 3.435 9.795 8.205 11.385c.6.105.825-.255.825-.57c0-.285-.015-1.23-.015-2.235c-3.015.555-3.795-.735-4.035-1.41c-.135-.345-.72-1.41-1.23-1.695c-.42-.225-1.02-.78-.015-.795c.945-.015 1.62.87 1.845 1.23c1.08 1.815 2.805 1.305 3.495.99c.105-.78.42-1.305.765-1.605c-2.67-.3-5.46-1.335-5.46-5.925c0-1.305.465-2.385 1.23-3.225c-.12-.3-.54-1.53.12-3.18c0 0 1.005-.315 3.3 1.23c.96-.27 1.98-.405 3-.405s2.04.135 3 .405c2.295-1.56 3.3-1.23 3.3-1.23c.66 1.65.24 2.88.12 3.18c.765.84 1.23 1.905 1.23 3.225c0 4.605-2.805 5.625-5.475 5.925c.435.375.81 1.095.81 2.22c0 1.605-.015 2.895-.015 3.3c0 .315.225.69.825.57A12.02 12.02 0 0 0 24 12c0-6.63-5.37-12-12-12z" fill="currentColor"></path>
            </g>
        </svg><span class="mx-2">FileBlazor on GitHub</span>
    </a>
</div>


# Java Resources
Source: https://docs.servicestack.net/java

- [Java Add ServiceStack Reference](/java-add-servicestack-reference)
 - [Release Notes for Java Support](/releases/v4_0_40#native-support-for-java-and-android-studio)

## Live Demos

 - [TechStacks Android App](https://github.com/ServiceStackApps/TechStacksAndroidApp)


# Swift Resources
Source: https://docs.servicestack.net/swift

- [Swift Add ServiceStack Reference](/swift-add-servicestack-reference)
 - [Release Notes for Swift Support](https://github.com/ServiceStack/ServiceStack/blob/master/docs/2015/release-notes.md#native-support-for-swift)

## Live Demos

 - [TechStacks iOS App](https://github.com/ServiceStackApps/TechStacksApp)
 - [TechStacks OSX Desktop App](https://github.com/ServiceStackApps/TechStacksDesktopApp)


# F# Resources
Source: https://docs.servicestack.net/fsharp

Thanks to the simplicity, elegance, strong typing and philosophy of both solutions, FSharp and ServiceStack are quickly becoming a popular choice for creating friction-less REST and message-based remote services.

### .NET Core F# Project

You can create a new .NET Core F# project in a new empty directory using the [x dotnet tool](/dotnet-tool) with:

```bash
$ dotnet tool install --global x 
$ mkdir ProjectName && cd ProjectName
$ x mix init-fsharp
$ dotnet run
```


Which will download the [init-fsharp Gist](https://gist.github.com/gistlyn/4802ba22b665e68c7257aef9f57c1934) to your local directory 
where you can use its dep-free [/index.html](https://gist.github.com/gistlyn/4802ba22b665e68c7257aef9f57c1934#file-wwwroot-index-html) and its
`JsonServiceClient` to call its **/hello** API:

![](/img/pages/release-notes/v5.9/init.png)

### [Complete F# Console Self-Host Example](https://github.com/ServiceStack/Test/blob/713f1e2c9fce2351446b168d39fe8b0248f252fc/src/VS.FSharp.SelfHost/Program.fs)

For .NET Framework you can use the `AppSelfHostBase` to create a stand-alone self-hosted Console App:

```fsharp
open System
open ServiceStack

type Hello = { mutable Name: string; }
type HelloResponse = { mutable Result: string; }
type HelloService() =
    interface IService
    member this.Any (req:Hello) = { Result = "Hello, " + req.Name }

//Define the Web Services AppHost
type AppHost =
    inherit AppSelfHostBase
    new() = { inherit AppSelfHostBase("Hi F#!", typeof<HelloService>.Assembly) }
    override this.Configure container =
        base.Routes
            .Add<Hello>("/hello")
            .Add<Hello>("/hello/{Name}") |> ignore

//Run it!
[<EntryPoint>]
let main args =
    let host = if args.Length = 0 then "http://*:1337/" else args.[0]
    printfn "listening on %s ..." host
    let appHost = new AppHost()
    appHost.Init() |> ignore
    appHost.Start host |> ignore
    Console.ReadLine() |> ignore
    0
```

# Community Resources

  - [SignalR + Servciestack with F# hosted on Azure](http://kunjan.in/2014/06/signalr-servicestack-azure-with-fsharp/) by [@kunjee](https://twitter.com/kunjee)
  - [Servicestack F# template. Starting from the Start](http://kunjan.in/2014/02/servicestack-fsharp-template-starting-from-start/) by [@kunjee](https://twitter.com/kunjee)
  - [Simple.Web and ServiceStack F# Templates](http://bloggemdano.blogspot.co.uk/2013/12/simpleweb-and-servicestack-templates.html) by [@dmohl](https://twitter.com/dmohl)
  - [Web services using ServiceStack framework in F#](https://github.com/chirdeeptomar/ServiceStackFSharpSample) by [@chirdeeptomar](https://twitter.com/chirdeeptomar)
  - [Last-Fi (F#, Raspberry Pi, Last.Fm, FunScript and ServiceStack)](http://pinksquirrellabs.com/post/2013/07/04/Last-Fi.aspx) by [@pezi_pink](https://twitter.com/pezi_pink)
  - [ServiceStack, With F# on Linux (inc Vagrant / Puppet)](http://saxonmatt.co.uk/2013/07/service-stack-fsharp-mono-fastcgi-nginx.html) by [@mattdrivendev](https://twitter.com/MattDrivenDev)
  - [Declarative authorization in REST services in SharePoint with F#](http://sergeytihon.wordpress.com/2013/06/28/declarative-authorization-in-rest-services-in-sharepoint-with-f-and-servicestack/) by [@sergey_tihon](https://twitter.com/sergey_tihon)
  - [ServiceStack and F# on Heroku (GitHub)](https://github.com/kunjee17/ServiceStackHeroku) by [@kunjee](https://twitter.com/kunjee)
  - [First hand experience with F#](http://d4dilip.wordpress.com/2013/04/09/first-hand-experience-with-f/) by [@d4dilip](https://twitter.com/d4dilip)
  - [ServiceStack: New API – F# Sample](http://sergeytihon.wordpress.com/2013/02/28/servicestack-new-api-f-sample-web-service-out-of-a-web-server/) by [@sergey_tihon](https://twitter.com/sergey_tihon)
  - [Async, Cached Twitter API Proxy in F#](http://www.servicestack.net/mythz_blog/?p=811) by [@demisbellot](https://twitter.com/demisbellot)
  - [F# Web Services on any platform in and out of a web server!](http://www.servicestack.net/mythz_blog/?p=785) by [@demisbellot](https://twitter.com/demisbellot)


# VB.NET Resources
Source: https://docs.servicestack.net/vbnet

There are some nostalgic developers who prefer not to leave their VB.NET days behind them, luckily they blog so other VB.NET developers can easily follow in their footsteps:

### VB .NET Core Project

You can create a new VB .NET Core project in a new empty directory using the [x dotnet tool](/dotnet-tool) with:

```bash
$ dotnet tool install --global x 
$ mkdir ProjectName && cd ProjectName
$ x mix init-vb
$ dotnet run
```

Which will download the [init-vb Gist](https://gist.github.com/gistlyn/88f2792fc4820de7dc4e68c0c5d76126) to your local directory 
where you can use its dep-free [/index.html](https://gist.github.com/gistlyn/88f2792fc4820de7dc4e68c0c5d76126#file-wwwroot-index-html) and its
`JsonServiceClient` to call its **/hello** API:

![](/img/pages/release-notes/v5.9/init.png)

### VB .NET Core Auth + File Uploads Example

The [vb-auth](https://github.com/NetCoreApps/vb-auth) VB.NET .NET Core project created with [x dotnet tool](/dotnet-tool):

```bash
$ mkdir ProjectName && cd ProjectName
$ x mix init-vb
```

Configured with [OrmLite + SQL Server](https://github.com/ServiceStack/ServiceStack.OrmLite), 
[ServiceStack Auth](/auth/authentication-and-authorization) including Login & Registration UIs
& integrated [JWT Auth](/auth/jwt-authprovider) showing how to manage file uploads for authenticated users.

![](https://raw.githubusercontent.com/NetCoreApps/vb-auth/master/screenshot.png)

### Plain static HTML Pages + JavaScript UI

No client or server UI Frameworks or external dependencies were used in this example which uses only Vanilla JS and functionality in the 
[Embedded UMD @servicestack/client](/servicestack-client-umd).

E.g. the client HTML UI & Backend Service implementation for the Authenticated HTTP File Upload Management functionality is in:

 - [/wwwroot/files.html](https://github.com/NetCoreApps/vb-auth/blob/master/wwwroot/files.html) - static HTML UI
 - [/ServiceInterface/UploadServices.vb](https://github.com/NetCoreApps/vb-auth/blob/master/ServiceInterface/UploadServices.vb) - back-end Service

### JWT Auth

JWT Authentication is [enabled at authentication](/auth/jwt-authprovider#switching-existing-sites-to-jwt) where
the `UseTokenCookie` parameter directs ServiceStack to capture the Authenticated Session in a stateless JWT Session Cookie:

```html
<form action="/auth/credentials" method="post">
    <input type="hidden" name="UseTokenCookie" value="true" />
    ...
</form>
```

### TypeScript Generated DTOs

[TypeScript Add ServiceStack Reference](/typescript-add-servicestack-reference) were used to generate the 
Typed DTOs which can be re-generated with:

```bash
$ cd wwwroot
$ x ts && tsc dtos.ts
```

# Community Resources

<!-- Commenting out as all links are crusty and no longer working.
  - [How to set up a VB.Net REST service on ServiceStack](http://fafx.wordpress.com/2013/02/09/how-to-set-up-a-vb-net-rest-service-on-servicestack/) by [The FAfx Project](http://fafx.wordpress.com/)
  - [Servicestack, VB.Net and some easyhttp](http://blogs.lessthandot.com/index.php/DesktopDev/MSTech/VBNET/servicestack-vb-net-and-some) by [@chrissie1](https://twitter.com/chrissie1)
  - [Redis and VB.Net](http://blogs.lessthandot.com/index.php/DataMgmt/DBProgramming/redis-and-vb-net) by [@chrissie1](https://twitter.com/chrissie1)

-->


# Deploy Multiple Sites to a single AWS EC2 instance
Source: https://docs.servicestack.net/deploy-multiple-sites-to-aws

### Why deploy multiple sites to a single AWS instance?

Deploying to **Cloud** and [PaaS](http://en.wikipedia.org/wiki/Platform_as_a_service) providers can provide a lot of utility by taking advantage of their integration, elasticity and autoscaling benefits. In a lot of cases Cloud providers are catered towards supporting popular flagship applications requiring very high levels of traffic. However, there are many times where your website only needs to cater for a specific use-case serving a niche audience, which would benefit from the simplicity and control of deploying and hosting multiple Websites on a single AWS instance. 

Amazon’s current tools for AWS, like [AWSDeploy](http://docs.aws.amazon.com/elasticbeanstalk/latest/dg/deploy_NET_standalone_tool.html) is designed around one application per VM instance. Whilst this makes autoscaling easier for them to manage, it also ends up being a lot more costly and wastes a lot of overhead for when your servers have the additional headroom that can easily support having multiple sites: 

![](https://github.com/ServiceStack/Assets/raw/master/img/wikis/octopus-deploy/ec2_monitor_1_week.png)

## Simple deployments with [TeamCity](http://www.jetbrains.com/teamcity/) and [Octopus Deploy](https://octopusdeploy.com/)

The optimal setup we found to automate ASP .NET deployments to [AWS](http://aws.amazon.com/) were to use [TeamCity](http://www.jetbrains.com/teamcity/) for the Build and Continuous Integration and [Octopus Deploy](https://octopusdeploy.com/) for automating deployments. If you are not familiar with them, both TeamCity and Octopus Deploy are best-in-class commercial tools with generous free-usage quotas, providing a flexible and hassle-free experience. TeamCity specializes in supporting a vast number of different development environments whilst Octopus Deploy is highly specialized in providing a flexible deployments for .NET applications centered around NuGet packages, with automatic versioning and backups as well as rich insights into the deployment process.

Both these tools work well together thanks to [Octopus Deploy's integration with TeamCity](http://docs.octopusdeploy.com/display/OD/TeamCity) which offers a TeamCity plugin containing custom build tasks to integrate with Octopus Deploy.

## TeamCity Installation and Setup

TeamCity can be [downloaded from here](http://www.jetbrains.com/teamcity/download/). The only requirement is that it's able to access your version control system and the Octopus Deploy server. The Install wizard walks you through the installation which also has [Installation instructions](http://confluence.jetbrains.com/display/TCD8/Installing+and+Configuring+the+TeamCity+Server?_ga=1.3492344.976140721.1404279443) that you can refer to.

Once installed, there are a few steps to add to ensure it is configured and ready to use with Octopus Deploy.

  1. Setup TeamCity as a [native NuGet server](http://blog.jetbrains.com/teamcity/2011/12/setting-up-teamcity-as-a-native-nuget-server/)
  2. Install [Octopus Deploy TeamCity plugin](http://octopusdeploy.com/downloads) ([How to install a Plugin, download Octopus Deploy TeamCity plugin](http://confluence.jetbrains.com/display/TCD8/Installing+Additional+Plugins))

For this tutorial I’ve used TeamCity 8.1 and Octopus Deploy 2.5.6.

To turn on TeamCity’s native NuGet server, go to **Administration** at the top right, select **NuGet Settings** on the left menu and click the **Enable** button.

![](https://github.com/ServiceStack/Assets/raw/master/img/wikis/octopus-deploy/nuget-settings-1.png)

If you are missing the public feed and want Octopus Deploy to not have to use authentication, you have to enable the use of Guest users. Under **Server Administration**, select **Authentication** and Allow login as `guest` user under **General Settings**. 

![](https://github.com/ServiceStack/Assets/raw/master/img/wikis/octopus-deploy/tc-authentication-settings.png)

You will also need to enable the use of NuGet.exe in your restore and build steps, select the **NuGet.exe** tab from the NuGet Settings screen and either Fetch or **Upload NuGet**.

![](https://github.com/ServiceStack/Assets/raw/master/img/wikis/octopus-deploy/tc-nuget-exe-version.png)

If you are using TeamCity version 8 or greater, you can use the **Plugin List** menu under Server Administration to help you upload a plugin. 

![](https://github.com/ServiceStack/Assets/raw/master/img/wikis/octopus-deploy/tc-plugins.png)

Once installed, restart the TeamCity server by restarting its windows service, the plugin should now appear in the Plugin List.

## Team City project build configurations

Now that we have TeamCity configured, we can create a project and build configurations that will produce our NuGet packages for Octopus Deploy to consume.

An overview of the setup we’re using is for every web application, we are going to have a project with at least 2 build configurations. One for building the application NuGet package and one for deploying it to Octopus Deploy. The simplest Build Application build configuration will itself, have two steps, **Restore NuGet Packages** and **Build Package**. Restore from NuGet is used under the assumption that we want to automatically restore our application dependencies using NuGet 2.7+ and pull them in at build time if they aren’t already cached. 

As a quick guide, this is using the following configuration:

 - Runner type: 		
   - **NuGet Installer**
 - NuGet.exe: 			
   - **2.8.2 (anything above 2.7 should be fine)**
 - Package sources:	
   - **NuGet V2 API url (include your own if needed here)**
 - Restore Mode: 	
   - **Restore (required NuGet 2.7+)**

Everything else is left as default or application specific like Path to solution file.
Here is a screen shot of this configuration used for the [StackApis](https://github.com/ServiceStackApps/StackApis) example application.

![](https://github.com/ServiceStack/Assets/raw/master/img/wikis/octopus-deploy/tc-nuget-restore-step.png)

The next step in the first build configuration is to package the application into a NuGet package. The configuration for this step is as follows.

 - Runner type:			
  - **Visual Studio**
 - Visual Studio:			
  - **Microsoft Visual Studio 2013**
 - Targets:			
  - **Rebuild;**
 - Run OctoPack:			
  - **true**
 - OctoPack package version:	
  - **1.0.%build.number%**

The rest of the settings are project specific or defaults. Here's a screenshot of the StackApis configuration: 

![](https://github.com/ServiceStack/Assets/raw/master/img/wikis/octopus-deploy/tc-nuget-build-package-step.png)

To make it more automated, a "Trigger" should be added so that every time a checkin occurs on the configured VCS, a build is queued. Select **Triggers** from within the Build Configuration screen to add a **VCS Trigger**.

> If you are missing the Octopus Packing section seen in the screenshot above, it means you don’t have the Octopus Deploy TeamCity plugin installed or it isn’t working. &lt;Insert troubleshooting TC plugins&gt;

Another requirement is that the application you want to package will require a new NuGet dependency on **OctoPack**. OctoPack is a package for Octopus Deploy which adds a new build target to your application to be used with the TeamCity plugin. 

You can add it to your application with the following NuGet command in Visual Studio:

:::copy
`<PackageReference Include="OctoPack" Version="3.*" />`
:::

Once added, the TeamCity plugin will do the rest if the checkbox is ticked. It is worth mentioning that because OctoPack is running as a new target, it can be manually incorporated into an existing building configuration using MSBuild by just adding the target. It’s also an open source project so more information can be found on the [OctoPack Github page](https://github.com/OctopusDeploy/OctoPack).

The next build configuration has a single step which is responsible for notifying Octopus Deploy to proceed with the deployment of a specific project to a specific environment. The reason we have these steps has two different build configurations is due to the requirement of having the NuGet packages published on the TeamCity NuGet feed. These packages will not appear until the build configuration that produces the package has completed. By separating them, we’re ensuring that TeamCity will have published the latest package version ready for Octopus Deploy.

Due to use of API keys and specific values that need to exist in Octopus Deploy first, we need to leave this next TeamCity step until after Octopus Deploy is setup. Once you have Octopus Deploy setup, skip to the **TeamCity integration** section.

## Octopus Deploy installation and initial setup ##

Octopus Deploy is a NuGet package centric continuous deployment system for .NET applications that is extremely flexible when it comes to deployment configurations. It has a strong focus on user experience, installation and setup is very quick intuitive. They even have a great set of [introduction videos](http://octopusdeploy.wistia.com/projects/gguvhmqn6b) that take you through getting up and running with Octopus Deploy. Also well maintained [documentation](http://docs.octopusdeploy.com/display/OD/Home) and active [forums](http://help.octopusdeploy.com/discussions) if you get stuck.

See this [Installation Video Guide](http://octopusdeploy.wistia.com/medias/fr2k2ademq) to walk you through Installing Octopus Deploy, once Installed you’ll be able to access its web interface to manage your Environments, Projects and Libraries. For the moment, we’ll want to [Create an Environment](http://octopusdeploy.wistia.com/medias/psanqpbi21) for our AWS instance. Create an environment for your applications, e.g. Production.

We’ll also need to add TeamCity as a NuGet feed. To do this, navigate to **Library** and select **External Feeds**: 

![](https://github.com/ServiceStack/Assets/raw/master/img/wikis/octopus-deploy/od-add-nuget-feed.png)

Like most of the UIs in Octopus Deploy, it’s pretty intuitive and self-explanatory. The URL for the feed can be retrieved from the TeamCity Administration page on **NuGet Settings**. Select the public feed, or private feed and provide a valid TeamCity user credentials.

Octopus Deploy needs somewhere to deploy too so we need to create an Environment and add our AWS instance as a `Tentacle`. A ‘Tentacle’ is just a machine that can be deployed too from Octopus Deploy. To do this, we need to be able to remotely access the AWS instance to [install the tentacle client](http://octopusdeploy.wistia.com/medias/qp12uky9qy), the easiest way to do this is [using RDP](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/LaunchingAndUsingInstancesWindows.html).

Once installed, the remote machine will appear in your host Octopus Deploy server under the environment is was added too.

![](https://github.com/ServiceStack/Assets/raw/master/img/wikis/octopus-deploy/od-add-machine-to-environment.png)

You’ll want to add this machine to a **Role**, in this example, the machine has just one role, `ServiceStackExamples`. Roles are "tags" that are used to target deployments steps which will look at soon.

## Setting up Octopus Deploy Projects

The project is where specific “Process Steps” can be added as a part of your automated deployment process. These can include one or more NuGet Packages as well as PowerShell steps, email, Deploy to Azure, FTP or even a manual intervention step. For our simple project we will need the Deploy NuGet Package step as well as an additional PowerShell step which we’ll look at later.

To create a new project, first view all projects under the `Projects->All` menu and then select **Add Project** at the top right. In this example, the project is called `StackApis`.

![](https://github.com/ServiceStack/Assets/raw/master/img/wikis/octopus-deploy/od-add-project.png)

Now that we have created an environment and a project, we need to add some steps. Add a **Deploy NuGet Package** step to your project.

![](https://github.com/ServiceStack/Assets/raw/master/img/wikis/octopus-deploy/od-add-step.png)

Process steps are extremely configurable pieces that can do as little or as much as you’ll need. The first thing we need to do is pick a target role/roles. In our example, this is `ServiceStackExamples`. This configures this deployment step to target machines with the “ServiceStackExamples” role attached to it. 

We will also have to tell the step where to access our application via a NuGet feed. If you added TeamCity’s NuGet feed as an External Feed in the previous instructions, it should be available from the NuGet feed drop down list. You will also need to specify the name of the package. If you are using OctoPack to package up your application, this should be the same name as your application. 

OctoPack has created a `.nuspec` file that includes all your application files and configured the ID of your package also, this was what this option is referring too.

At the very bottom we can also restrict the step to only be used in a limited set of environments. We will be adding `Production` here as we only want this step to be process for the Production environment.

Each process step can also have additional features added, for the deployment step, we get the following list.

![](https://github.com/ServiceStack/Assets/raw/master/img/wikis/octopus-deploy/od-process-step-features.png)

For this example, we are deploying an ASP.NET application, so one additional 'Feature' we will need, is an **IIS web site and application pool** for the application. This will handle things like bindings, application pool identity, SSL and other aspects of managing IIS. We don’t need SSL in this instance, so we’ll just go with a basic configuration. 

![](https://github.com/ServiceStack/Assets/raw/master/img/wikis/octopus-deploy/od-iis-configuration.png)

Octopus Deploy has an introduction [video for setting an ASP.NET deployment here](http://octopusdeploy.wistia.com/medias/7wfdk4vtge).

#### AWS Performance issues with Elastic Block Store

One issue that was discovered during this process was high latency on the applications we have deployed when compared to applications deployed by the AWSDeploy tool. This was due to permissions of the folder being deployed too by Octopus Deploy. To fix this issue, we added an additional step and PowerShell script to add the appropriate permissions to the folders where the latest version of the application was deployed.

Add a new step that runs after the deployment step created in the section above. Select **Run a PowerShell script** as the process step template. Add the same machine role as deployment step and add the following PowerShell script:

```shell
	$Acl = Get-Acl "C:\inetpub"
	$ArIIS = New-Object  system.security.accesscontrol.filesystemaccessrule("IIS_IUSRS","ReadAndExecute","Allow")
	$appPoolName = $OctopusParameters['Octopus.Action[Deploy Package].IISWebSite.ApplicationPoolName']
	Write-Output $appPoolName
	$Acl.SetAccessRule($ArIIS)
	$appPath = $OctopusParameters['Octopus.Action[Deploy Package].Output.Package.InstallationDirectoryPath'] 
	Set-Acl $appPath $Acl
	$appPoolAclParam = "IIS AppPool\$appPoolName`:(OI)(CI)M"
	cmd /c icacls "$appPath" /grant "$appPoolAclParam"
```

Most of the script above is generic except for 2 parts where the exact name of the previous deployment step is used to access an Octopus Deploy variable. `Octopus.Action[&lt;insert name of your process step&gt;]` can be updated to target the correct step. The "Insert a variable" menu on the right of the script input box can help when trying to find the right variable you need to use in your scripts.

This script updated the permissions and gives Modify access to folder where your application is deployed and to the application pool identity that is running your application. 

## TeamCity Integration

Now that our project is setup in Octopus Deploy, we will need an API key from Octopus Deploy to be used by TeamCity to fire off the deployment step. To get the API key, access your user profile from the top right of the Octopus Deploy dashboard and select the API keys tab.

![](https://github.com/ServiceStack/Assets/raw/master/img/wikis/octopus-deploy/od-add-apikey.png)

Note, make sure you save the API key somewhere as we will need to paste it into TeamCity build configuration.

Now navigate to your TeamCity build server and create a new build configuration that runs after the initial Build Package step in your TeamCity project. This build configuration does not need a VCS source, but it does need a single build step and a trigger. 

Create a new build step with the following configuration.

 - Runner type:			
  - **Octopus Deploy: Create release**
 - Octopus URL:			
  - **&lt;URL to your Octopus Deploy web portal&gt;**
 - API key:			
  - **The API key you just created**
 - Octopus version:		
  - **2.0+**
 - Release number:		
  - **1.0.%dep.&lt;previousBuildStepId&gt;.system.build.number%**
 - Deploy to:			
  - **&lt;Octopus Deploy environment name, eg Production&gt;**

Below is a screenshot of the StackApis Deploy step in TeamCity:

![](https://github.com/ServiceStack/Assets/raw/master/img/wikis/octopus-deploy/tc-add-deploy-build-step.png)

Notes on Release number, by using the method shown above, running the deploy step manually even with correct snapshot and artifact dependencies will not work due to Octopus Deploy failing as the version from a previous build would already exist. This might be a matter of preference, but since Octopus Deploy as very nice ways of doing re-releases and rollbacks, it makes sense to only fire the deployment of a new version of the package from Octopus Deploy itself and not from TeamCity. If you want to have this control from TeamCity, the Release number can be changed to `x.x.%build.number%`, this will get automatically incremented even if run manually. If you are having issues with build and release numbers, it can be left blank for Octopus Deploy to increment, however this might make it harder to related TeamCity build numbers with release numbers.

You will also need to add a trigger to this step so it is fired on the completion of a successful build of the previous build configuration which produced the NuGet package. One way to achieve this is to first add a snapshot and artifact dependency on the Build package step.

![](https://github.com/ServiceStack/Assets/raw/master/img/wikis/octopus-deploy/tc-add-artifact-dep.png)

![](https://github.com/ServiceStack/Assets/raw/master/img/wikis/octopus-deploy/tc-add-snapshot-dep.png)

Once these dependencies are setup, add a trigger.

![](https://github.com/ServiceStack/Assets/raw/master/img/wikis/octopus-deploy/tc-finish-build-trigger.png)

This means the build configuration will run after a successful build of the package.

If you now navigate to your project in TeamCity, you should see two build configurations. Here is an example of StackApis:

![](https://github.com/ServiceStack/Assets/raw/master/img/wikis/octopus-deploy/tc-project-result.png)

Now if we **Run** the **Build** step above from TeamCity, the Deploy step should also fire. If they are successful, we should be able to navigate to our Octopus Deploy Projects dashboard to hopefully see the following.

![](https://github.com/ServiceStack/Assets/raw/master/img/wikis/octopus-deploy/od-release-result.png)

This means your TeamCity deploy step successfully kicked off your Octopus Deploy step. This may take a while as it requires your application package to be transferred to your AWS instance and this will vary based on bandwidth available and size of your application.

With any luck, your deployment will be a success, however Octopus deploy does log quite a lot of information about the tasks being performed so the best place to look for troubleshooting is the Task Log. Click on your latest release and select the Task Log tab. To see more information, select **Verbose** at the top right of the Task Log. This will show you information like remote paths, machines, versions etc etc.

## Adding more applications ##
Since TeamCity and Octopus Deploy are setup, adding additional applications becomes easier. Getting multiple applications onto the one AWS instance, or any other Octopus Deploy Tentacle, is a matter of creating new projects for both TeamCity and Octopus Deploy targeting the same environment.


# Deploy multiple ASP.NET Websites to AWS with WebDeploy
Source: https://docs.servicestack.net/simple-deployments-to-aws

We've [previously discussed](/deploy-multiple-sites-to-aws#why-deploy-multiple-sites-to-a-single-aws-instance) the cost and automation benefits of **deploying multiple websites to a single AWS instance** using [TeamCity and Octopus Deploy](/deploy-multiple-sites-to-aws) which is a great combination for managing production website deployments, taking advantage of the automation capabilities of TeamCity and the release management features of Octopus Deploy.

There's an even simpler option for deploying multiple ASP.NET Websites to a single AWS instance which can be initiated directly from within VS.NET (i.e. without needing any external TeamCity and OctopusDeploy services) by using VS.NET's built-in **Web Deploy** tool. In this tutorial we'll walkthrough 2 different approaches for deploying websites using either VS.NET's **Publish Web Deploy wizard** or alternatively using a **Gulp Task** which is better suited for deploying Single Page Apps requiring any necessary pre and post processing packaging and deployment steps.

## Setting up the instance

For a concrete example, we're going to be using an [AWS EC2 instance](http://aws.amazon.com/ec2/) running Windows Server 2012 with IIS installed. To enable Web Deploy, a package needs to be installed on the server so you will need a few things to get started.

-   Remote access to the instance
-   [Web platform installer](http://www.microsoft.com/web/downloads/platform.aspx)
-   An IIS application to deploy too

By default, you should have remote access to your EC2 instance, however, if you don’t, you will need to add an inbound network rule to the security group that your instance is running under:

![RDP port](https://github.com/ServiceStack/Assets/raw/master/img/wikis/web-deploy/open-aws-ports-1.png)

This can be done by locating your instance in AWS, and clicking on the currently assigned security group:

![View security group](https://github.com/ServiceStack/Assets/raw/master/img/wikis/web-deploy/aws-security-group.png)

While here, you will also need to add a new security rule for Web Deploy to work. It uses port **8172** by default. 

![WebDeploy and HTTP/S ports](https://github.com/ServiceStack/Assets/raw/master/img/wikis/web-deploy/open-aws-ports-2.png)

::: info
It is good practice to restrict inbound ports to RDP and other ports related to administrative tasks to a subnet or even specific IP address to improve security. See AWS's "[Recommended Network ACL Rules for Your VPC](http://docs.aws.amazon.com/AmazonVPC/latest/UserGuide/VPC_Appendix_NACLs.html)"
:::

If you are missing HTTP and HTTPS, ensure these have been added as well.

Now we can remote into your instance via RDP. [Amazon has some detailed documentation](https://docs.aws.amazon.com/AWSEC2/latest/WindowsGuide/connecting_to_windows_instance.html) about how to go about this, but basically you will need the address of the server, username and password.

Once connected, you’ll want to copy across the Web Platform Installer to enable the Web Deploy feature to work on IIS. Run the web platform installer and search up the top right for **Web Deploy** and one of the results should be **Web Deploy 3.5 for Hosting Servers**. 

![Install web deploy hosting](https://github.com/ServiceStack/Assets/raw/master/img/wikis/web-deploy/install-webdeploy-hosting.png)

Click **Add** and then **Install** at the bottom right.

Once installed, we now have to create an IIS web site as our deployment target.

![Create IIS application](https://github.com/ServiceStack/Assets/raw/master/img/wikis/web-deploy/create-iis-application.png)

Open the IIS Manager, right click on **Sites**, select **Add Website...** and provide the appropriate information for your web site such as the domain name. Record the name of your website as we will need this later.
 
## Deploy using Publish from Visual Studio

With the remote server setup to accept Web Deployed applications, we can create an application to deploy. For this example, we are going to use the **ServiceStack ASP.NET with Bootstrap** template from [ServiceStackVS](/create-your-first-webservice). This will create a simple HelloWorld application that we can use to test our deployment.

![Bootstrap template selection](https://github.com/ServiceStack/Assets/raw/master/img/wikis/web-deploy/bootstrap-app-template-select.png)
 
Once created, we can use the Visual Studio publish wizard by right-clicking on the main project at the top and selecting `Publish...`:

![Create publish profile](https://github.com/ServiceStack/Assets/raw/master/img/wikis/web-deploy/publish-wizard-1.png)
 
At the first screen, select a **Custom** publish target and give your profile a name like **AWS**:

![Name publish profile](https://github.com/ServiceStack/Assets/raw/master/img/wikis/web-deploy/publish-name-profile.png)
 
The next screen will require your EC2 **Public DNS** name that can be obtained via the AWS management portal for your instance. Also, the site name we created earlier needs to match. You will also be required to provide a username and password of an account that has sufficient permissions to publish your application. 

> An administration account has sufficient permissions, alternatively, there is an article on **[Installing and Configuring Web Deploy on IIS 8](http://www.iis.net/learn/install/installing-publishing-technologies/installing-and-configuring-web-deploy-on-iis-80-or-later)** that explains this in the section titled **Configuring a Site for Delegated Non-Administrator Deployment**.

![Web deploy profile settings](https://github.com/ServiceStack/Assets/raw/master/img/wikis/web-deploy/publish-wizard-2.png)

>You may get the following warning about certificate presented by the server, if you haven’t setup the server with the appropriate certificates you can still continue.
> ![Certificate warning](https://github.com/ServiceStack/Assets/raw/master/img/wikis/web-deploy/publish-cert-warning.png)
 
Once **Publish** has started, this will build your application and push the files using Web Deploy.
The first deployment might take some time due to having to copy all files required by the application to run, but subsequent copies only update the files that are different, making this a very quick way to update and present the progress of an application on a development server.

![Publish wizard demo](https://github.com/ServiceStack/Assets/raw/master/img/wikis/web-deploy/webdeploy_bootstrap.gif)

## Deploy using Gulp

Although the Publish wizard is a great tool, by default, it doesn't work well with single page applications like AngularJS where the client side of the application that requires pre/post processing of client side scripts and assets. Another way to publish still using Web Deploy (msdeploy) is by using a Gulp task. The Gulp task simply wraps msdeploy using the [gulp-msdeploy Gulp package](https://github.com/ServiceStack/gulp-msdeploy) ([base on grunt-msdeploy written by Jack Davis](https://www.npmjs.org/~mrjackdavis)). If we create a new project using the **AngularJS App** template from ServiceStackVS, we can modify what is already there very quickly to get our application to deploy to our AWS instance.
 
Once the project is created, we will fill out the same details given to the Publish wizard, but in a configuration file located at `/wwwroot_build/publish/config.json`. By default, it has placeholder values shown below:

```json
{
    "iisApp": "ExampleAngularJSApp1",
    "serverAddress": "deploy-server.example.com",
    "userName": "{WebDeployUserName}",
    "password" : "{WebDeployPassword}"
}
```

Where the `iisApp` value is the name of your project. Below is the filled in example details as shown in the publish wizard:

```json
{
    "iisApp": "ExampleApplication",
    "serverAddress": "ec2-XXX-XXX-XXX-XXX.ap-southeast-2.compute.amazonaws.com",
    "userName": "Administrator",
    "password" : "MyPassword123"
}
```

Once filled in, we can run the provided tasks 2 and 3 to package our application and task 4 to deploy it. If you are running Visual Studio 2015 (or 2013 with extension), these Gulp tasks can be very simply from Task Runner Explorer UI.

::: info
Even though by using GitHub's default Visual Studio .gitignore the config will not turn up in source control, the password is still **stored in plain text**. This should be taken into account when deciding if this method of deployment is suitable for your development/deployment environment
:::

### Bundling ###

This template is also taking care of optimizations like CSS and JS minification in the packaging steps. Package of the server files and client files separately enable us to update and deploy an optimized client side version of our application quickly as only our client side resources will have to be updated.


# Advanced Deployments with Octopus Deploy
Source: https://docs.servicestack.net/advanced-deployment-octopus-deploy

## Deploying and Installing SSL certificates with Octopus Deploy

There's a good chance at some stage you're going to want to have sensitive environment specific information that you don't to want to store in source control, especially if your project is open source. This could be SSL certificates, license information or Production AppSettings like private database passwords, production connection strings or anything else you need to run your application.

One solution is to package all application settings and other dependencies on the build server. Using [TeamCity](http://www.jetbrains.com/teamcity/) and [Octopus Deploy](https://octopusdeploy.com/), packaging these settings up and deploying along with the application is easy to manage, flexible process that can streamline and automate even complicated application deployments.

Whilst the installation of SSL certificates, IIS bindings and other tasks here aren't time consuming to do manually, being able to get a new server up and running quickly by automating as much as possible has many benefits including consistent, replay-able deployments and not being tied to a particular infrastructure provider allowing you to easily switch to better valued hosting providers like [Hetzner](http://www.hetzner.de/en/) should you wish to in future.

## Getting started

This example is going to be an extension on the pattern used in the [Deploy multiple sites to a single AWS instance deployment guide](/deploy-multiple-sites-to-aws), but with an additional TeamCity step and a few extra process steps for Octopus Deploy to deploy an application with additional components and configuration.

1. **Settings** file read by ServiceStack application
2. ServiceStack **license file**
3. **SSL certificate** for HTTPs binding

As an overview, the TeamCity steps for building and deploying a **simple application** goes something like:

### [TeamCity Steps](/deploy-multiple-sites-to-aws#teamcity-installation-and-setup)

#### Build application

1. Restore NuGet dependencies 
2. Package application into .nupkg

#### Deploy application

1. Notify Octopus Deploy of new version available from TeamCity NuGet feed

With the added settings package, we are adding an additional step to the Build application list above.

1. **Package settings and other required environment files into .nupkg**
2. Restore NuGet dependencies 
3. Package application into .nupkg

#### Creating the NuGet package

To package the files into a NuGet package we will need to create a **nuspec** file. A .nuspec file is a [package specification](http://docs.nuget.org/docs/reference/nuspec-reference) that contains a list of files to include in the package, and this is where we have to specify the 3 files above, e.g:

```xml
<?xml version="1.0"?>
<package xmlns="http://schemas.microsoft.com/packaging/2010/07/nuspec.xsd">
    <metadata>
        <id>BenchmarkAnalyzerSettings</id>
        <version>1.0.0</version>
        <authors>ServiceStack</authors>
        <requireLicenseAcceptance>false</requireLicenseAcceptance>
        <description>Settings for the Benchmark Analyzer project</description>
    </metadata>
    <files>
      <file src="appsettings.license.txt" />
      <file src="appsettings.txt" />
      <file src="httpbenchmarks.pfx" />
    </files>
</package>
```

Once we have created a valid .nuspec file, we can get TeamCity to create a NuGet package using the **NuGet Pack runner type**. The main settings you will need for this configuration is the path where TeamCity can find the .nuspec file.

If you are hosting your own TeamCity instance, this is just a local directory. However, if you are hosting a TeamCity instance separately, eg on a dedicated build server, you will need to copy these files local to the build server to package them or use another VCS that is secure for application settings.

In this example, we will be packing the files from a known path on build server.

::: info
If you are having issues with this step, check the file/folder permissions to the .nuspec and included files
:::

![](https://github.com/ServiceStack/Assets/raw/master/img/wikis/octopus-deploy-ssl/tc-nuget-pack.png)

**Output directory** is the same as the **Artifact paths** in the **General Settings** of the build configuration for building the application package:

![](https://github.com/ServiceStack/Assets/raw/master/img/wikis/octopus-deploy-ssl/tc-build-config-paths.png)

So now our build steps for our application build and packaging steps looks like:

![](https://github.com/ServiceStack/Assets/raw/master/img/wikis/octopus-deploy-ssl/tc-build-config.png)

If everything is building correctly, you should get two **nupkg** files as artifacts from the build configuration, your application and settings package:

![](https://github.com/ServiceStack/Assets/raw/master/img/wikis/octopus-deploy-ssl/tc-project-output.png)

If you are using TeamCity’s built in NuGet server, these packages are published are available to use from Octopus Deploy.

## [Octopus Deploy process steps](/deploy-multiple-sites-to-aws#octopus-deploy-installation-and-initial-setup)

For a [simple application](/deploy-multiple-sites-to-aws#setting-up-octopus-deploy-projects) with no application settings or SSL certificate to install we only have 2 steps for Octopus Deploy.

![](https://github.com/ServiceStack/Assets/raw/master/img/wikis/octopus-deploy-ssl/od-simple-example.png)

However, due to the need to automate the installation of all the projects dependencies, we have to add at least another 3 steps. We will need the following list of steps to happen before our newly published application is being hosted with the right settings, license and SSL binding.

1. **Publish settings package**
2. **Install SSL if required**
3. Deploy Application Package
4. **Copy Production Settings and License**
5. Update permissions

## Publish settings package

Publish settings is a "**Deploy Package**" process step looking at the TeamCity NuGet feed and using the new "BenchmarkAnalyzerSettings" package.

![Publish settings configuration](https://github.com/ServiceStack/Assets/raw/master/img/wikis/octopus-deploy-ssl/od-publish-settings.png)

>If you can’t see the [NuGet feed from TeamCity](/deploy-multiple-sites-to-aws#octopus-deploy-installation-and-initial-setup), you need to [set up a new NuGet feed](http://docs.octopusdeploy.com/display/OD/Package+repositories) under Library in Octopus Deploy.

## Install SSL If Required

Next we will need to install the SSL certificate if it is not already installed. To do this, we can add some PowerShell within the Octopus Deploy Library under **Script Modules**. A script module can be included in a process step, this gives you the chance to reuse some of the more common PowerShell between steps or projects. In this example, we are going to write some PowerShell to help us **install the certificate**.

```powershell
function Add-SSLCertificateToIIS{
    param([string]$certPath,[string]$pfxPassword)
    Write-Output "Importing certificate into ISS from $certPath"
    $certMgr = New-Object -ComObject IIS.CertObj -ErrorAction SilentlyContinue    
    $certMgr.ImportToCertStore($certPath,$pfxPassword,$true,$true)
}
```

This PowerShell function takes a path of a pfx file, a password and installs it to IIS to be used in a HTTPS binding.

Once we’ve added this script to a new Script module, we can **call the function from a process step**. If we add a new process step of "Install SSL If Required" and run another script that utilizes our new function, we can install the certificate that was packaged in our settings NuGet package.

![](https://github.com/ServiceStack/Assets/raw/master/img/wikis/octopus-deploy-ssl/od-ssl-step.png)

The script in the screenshot above uses a couple of Octopus Deploy variables, as well as results from previous "Publish settings" step.

```powershell
Write-Output "Checking SSL certificate"
$cert = ( Get-ChildItem -Path cert:\LocalMachine\My| ? { $_.subject -like "*cn=$CertCn*" })
if(!$cert) {
    Write-Output "SSL certificate missing, installing..."
    $certDirPath = $OctopusParameters['Octopus.Action[Publish settings].Output.Package.InstallationDirectoryPath']
    Add-SSLCertificateToIIS "$certDirPath\$CertFileName" $SSLKey
} else {
    Write-Output "SSL present, skipping installation..."
}
```

`$SSLKey`, `$CertFileName` and `$CertCn` are all **Octopus Deploy variables** we have declared in the project variables section, we access them just like any declared PowerShell object.

The script itself is simply checking the `LocalMachine\My certificate` store that contains a specific string in the **subject** property, if no certificate that matches the CN value is present, it installs the certificate from where it was published using an encrypted password stored within Octopus Deploy.

Generally, this will only install the certificate once on first install of the new virtual machine, but will reinstall it if for whatever reason it has to be manually removed.

## Copy Production Settings and License

The last new process step that is included is a straight forward copy from source location to a destination. This step happens **after** the deployment of the application as the destination is not yet known until this step has completed. 

```powershell
$src = $OctopusParameters['Octopus.Action[Publish settings].Output.Package.InstallationDirectoryPath']
$dst = $OctopusParameters['Octopus.Action[Deploy Package].Output.Package.InstallationDirectoryPath']
Write-Output "Copying environment files from $src to $dst"
Get-ChildItem $src | Copy-Item -Destination $dst -Exclude "*.pfx"
```

The script also **excludes copying the pfx certificate** as this is not something we want to host in IIS application. Another step that can be added is one to delete the SSL certificate after step installation so this exclusion wouldn’t be required. Thankfully, there are some templates for common tasks like deleting files are available to add to your Octopus Deploy instance from an [open source project](https://github.com/OctopusDeploy/Library). 

Here is an example of the File System – Clean Directory template installed and used to clean pfx files from the output directory.

![View of template once installed](https://github.com/ServiceStack/Assets/raw/master/img/wikis/octopus-deploy-ssl/od-clean-directory.png)

## Using the SSL binding

We can now set which binding to use in IIS in the Deploy Package step which deploys the main application. To use a specific SSL certificate you will need to provide the **SSL Thumbprint**. An easy way to find the Thumbprint of the certificate is to open the original **.crt** file, select the **Details** tab and select **Properties Only** from the **Show** drop down.

One you have this value, you will need to provide it in the Add binding menu when adding an IIS binding.

![Add HTTPS IIS binding in deployment step](https://github.com/ServiceStack/Assets/raw/master/img/wikis/octopus-deploy-ssl/od-add-binding-https.png)

This thumbprint associates the binding with the newly installed certificate. Once installed, the certificate will show up in the IIS Management window under Server Certificates and the specified website will have the HTTPS binding associated with the installed certificate.

![IIS Manager after deployment](https://github.com/ServiceStack/Assets/raw/master/img/wikis/octopus-deploy-ssl/iis-certificates.png)

## HTTP binding redirect

So far we have setup all we need for the HTTPS binding, but since the default protocol when navigating to a site directly is HTTP, we want to setup a URL rewrite so that any requested resource on HTTP is redirected to HTTPS. To so this we will need to add some configuration in the Web.Config.Release transformation. 

```xml
<system.webServer>

  <rewrite xdt:Transform="Insert">
    <rules>
      <rule name="Redirect to HTTPS" stopProcessing="true">
        <match url="(.*)" />
        <conditions>
          <add input="{HTTPS}" pattern="^OFF$" />
        </conditions>
        <action type="Redirect" url="https://{HTTP_HOST}/{R:1}" redirectType="SeeOther" />
      </rule>
    </rules>
  </rewrite>

</system.webServer>
```

This configuration uses an IIS module that may or may not be installed on your server. It can be installed via the [Web Platform Installer](http://www.microsoft.com/web/downloads/platform.aspx) or installed separately, see the [IIS site for more details](http://www.iis.net/downloads/microsoft/url-rewrite).

We will **also need a HTTP binding** so the redirects can take place. IIS configuration in Octopus Deploy allows multiple IIS bindings for a deployed package. To add a HTTP binding, it is the same the same as step above, but selecting HTTP from the Protocol drop down.

### Managing settings files yourself vs Octopus Deploy variables

In this example we are storing both the application SSL certificate (.pfx file) for use with IIS, application settings and license in text files we are managing ourselves. To import a certificate and install it onto a new virtual machine we can’t get around the need to deploy the pfx file. However, there are many ways to handle application settings including the ServiceStack license.

Octopus Deploy has some really useful features when it comes to handling applications settings, even environment specific passwords etc. You could use this for storing the ServiceStack license itself as well as database credentials and other [sensitive information](http://docs.octopusdeploy.com/display/OD/Security+and+encryption). 

![Octopus Deploy Variables](https://github.com/ServiceStack/Assets/raw/master/img/wikis/octopus-deploy-ssl/od-variables.png)

Although not used in this example, Octopus Deploy variables can replace web.config `appSettings` values and then can feed to [ServiceStack’s AppSettings and its more useful data-structures](/appsettings#example-usage).

To enable this functionality, remember to enable it in your application's deploy step.

![](https://github.com/ServiceStack/Assets/raw/master/img/wikis/octopus-deploy-ssl/od-replace-app-settings.png)


# ServiceStack.Aws
Source: https://docs.servicestack.net/aws

![](/img/pages/aws/servicestack-aws-banner-420.png)

## .NET before Cloud Services

One thing we've missed from being based on .NET is its predisposition towards Windows-only technologies, missing out on
all the industrial strength server solutions that are being primarily developed for hosting on Linux. This puts .NET 
at a disadvantage to other platforms which have first-class support for using the best technologies at their discretion, 
which outside of .NET, are primarily running on Linux servers. 

## AWS's servicified platform and polyglot ecosystem

By building their managed platform behind platform-agnostic web services, Amazon have largely eroded this barrier. We
can finally tap into the same ecosystem [innovative Startups are using](https://techstacks.io/tech/amazon-ec2) with
nothing more than the complexity cost of a service call - the required effort even further reduced with native clients. 
Designing its services behind message-based APIs made it much easier for Amazon to enable a new polyglot world with 
[native clients for most popular platforms](https://aws.amazon.com/dynamodb/developer-resources/#SDK), putting .NET
on a level playing field with other platforms thanks to [AWS SDK for .NET's](http://aws.amazon.com/sdk-for-net/) 
well-maintained typed native clients. By providing its functionality behind well-defined services, for the first time 
we've seen in a long time, .NET developers are able to benefit from this new polyglot world where solutions and app 
logic written in other languages can be easily translated into .NET languages - a trait which has been invaluable whilst 
developing ServiceStack's integration support for AWS.

This also means features and improvements to reliability, performance and scalability added to its back-end servers benefit 
every language and ecosystem using them. .NET developers are no longer at a disadvantage and can now leverage the same 
platform Hacker Communities and next wave of technology leading Startups are built on, benefiting from the Tech Startup 
culture of sharing their knowledge and experiences and pushing the limits of what's possible today.

AWS offers unprecedented productivity for back-end developers, its servicified hardware and infrastructure encapsulates 
the complexity of managing servers at a high-level programmatic abstraction that's effortless to consume and automate. 
These productivity gains is why we've been running our public servers on AWS for more than 2 years. The vast array of 
services on offer means we have everything our solutions need within the AWS Console, our RDS managed PostgreSQL databases 
takes care of automated backups and software updates, ease of snapshots means we can encapsulate and backup the 
configuration of our servers and easily spawn new instances. AWS has made software developers more capable than ever, 
and with its first-class native client support leveling the playing field for .NET, there's no reason why 
[the next Instagram](http://highscalability.com/blog/2012/4/9/the-instagram-architecture-facebook-bought-for-a-cool-billio.html)
couldn't be built by a small team of talented .NET developers.

## ServiceStack + Amazon Web Services

We're excited to participate in AWS's vibrant ecosystem and provide first-class support and deep integration with AWS where 
ServiceStack's decoupled substitutable functionality now seamlessly integrates with popular AWS back-end technologies. 
It's now more productive than ever to develop and host ServiceStack solutions entirely on the managed AWS platform!

## ServiceStack.Aws

All of ServiceStack's support for AWS is encapsulated within the single **ServiceStack.Aws** NuGet package which 
references the latest modular AWSSDK **v3.1x** dependencies **.NET 4.5+** projects can install from NuGet with:

:::copy
`<PackageReference Include="ServiceStack.Aws" Version="8.*" />`
:::

This **ServiceStack.Aws** NuGet package includes implementations for the following ServiceStack providers:

  - **[PocoDynamo](/aws-pocodynamo)** - Declarative, code-first POCO client for DynamoDB with LINQ support
  - **[SqsMqServer](/aws#sqsmqserver)** - [MQ Server](/messaging) for invoking ServiceStack Services via Amazon SQS MQ Service
  - **[S3VirtualFiles](/aws#s3virtualfiles)** - A read/write [Virtual FileSystem](/virtual-file-system) around Amazon's S3 Simple Storage Service
  - **[DynamoDbAuthRepository](/aws#dynamodbauthrepository)** - A [UserAuth repository](/auth/authentication-and-authorization) storing UserAuth info in DynamoDB
  - **[DynamoDbAppSettings](/aws#dynamodbappsettings)** - An [AppSettings provider](/appsettings) storing App configuration in DynamoDB
  - **[DynamoDbCacheClient](/aws#managed-dynamodb-client)** - A [Caching Provider](/caching) for DynamoDB

## [AWS Live Examples](https://github.com/ServiceStackApps/AwsApps)

To demonstrate the ease of which you can build AWS-powered solutions with ServiceStack we've rewritten 6 of our existing 
[Live Demos](https://github.com/ServiceStackApps/LiveDemos) to use a pure AWS managed backend using:

 - [Amazon DynamoDB](https://aws.amazon.com/dynamodb/) for data persistance
 - [Amazon S3](https://aws.amazon.com/s3/) for file storage
 - [Amazon SQS](https://aws.amazon.com/sqs/) for background processing of MQ requests 
 - [Amazon SES](https://aws.amazon.com/ses/) for sending emails
 
[![](https://raw.githubusercontent.com/ServiceStack/Assets/master/img/aws/apps/screenshots/awsapps.png)](https://github.com/ServiceStackApps/AwsApps)

### Simple AppHost Configuration

A good indication showing how simple it is to build ServiceStack + AWS solutions is the size of the 
[AppHost](https://github.com/ServiceStackApps/AwsApps/blob/master/src/AwsApps/AppHost.cs) which contains all the 
configuration for **5 different Apps** below utilizing all the AWS technologies listed above contained within a **single** 
ASP.NET Web Application where each application's UI and back-end Service implementation are encapsulated under 
their respective sub directories:

  - [/awsath](https://github.com/ServiceStackApps/AwsApps/tree/master/src/AwsApps/awsauth)
  - [/emailcontacts](https://github.com/ServiceStackApps/AwsApps/tree/master/src/AwsApps/emailcontacts)
  - [/imgur](https://github.com/ServiceStackApps/AwsApps/tree/master/src/AwsApps/imgur)
  - [/restfiles](https://github.com/ServiceStackApps/AwsApps/tree/master/src/AwsApps/restfiles)
  - [/todo](https://github.com/ServiceStackApps/AwsApps/tree/master/src/AwsApps/todo)

## [AWS Razor Rockstars](http://awsrazor.netcore.io/)

[![](https://raw.githubusercontent.com/ServiceStack/Assets/master/img/aws/apps/screenshots/awsrazor.png)](http://awsrazor.netcore.io/)

### Maintain Website Content in S3

The 
[implementation for AWS Razor Rockstars](https://github.com/ServiceStackApps/RazorRockstars/tree/master/src/RazorRockstars.S3) 
is kept with all the other ports of Razor Rockstars in the [RazorRockstars repository](https://github.com/ServiceStackApps/RazorRockstars).
The main difference that stands out with [RazorRockstars.S3](https://github.com/ServiceStackApps/RazorRockstars/tree/master/src/RazorRockstars.S3)
is that all the content for the App is **not** contained within project as all its Razor Views, Markdown Content, imgs, 
js, css, etc. are instead being served **directly from an S3 Bucket** :) 

This is simply enabled by overriding `GetVirtualFileSources()` and adding the new 
`S3VirtualFiles` to the list of file sources:

```csharp
public class AppHost : AppHostBase
{
    public override void Configure(Container container)
    {
        //All Razor Views, Markdown Content, imgs, js, css, etc are served from an S3 Bucket
        var s3 = new AmazonS3Client(AwsConfig.AwsAccessKey, AwsConfig.AwsSecretKey, RegionEndpoint.USEast1);
        VirtualFiles = new S3VirtualFiles(s3, AwsConfig.S3BucketName);
    }
    
    public override List<IVirtualPathProvider> GetVirtualFileSources()
    {
        //Add S3 Bucket as lowest priority Virtual Path Provider 
        var pathProviders = base.GetVirtualFileSources();
        pathProviders.Add(VirtualFiles);
        return pathProviders;
    }
}
```

The code to import RazorRockstars content into an S3 bucket is trivial: we just use a local FileSystem provider to get 
all the files we're interested in from the main ASP.NET RazorRockstars projects folder, then write them to the configured 
S3 VirtualFiles Provider:

```csharp
var s3Client = new AmazonS3Client(AwsConfig.AwsAccessKey, AwsConfig.AwsSecretKey, RegionEndpoint.USEast1);
var s3 = new S3VirtualFiles(s3Client, AwsConfig.S3BucketName, appHost);
            
var fs = new FileSystemVirtualPathProvider(appHost, "~/../RazorRockstars.WebHost".MapHostAbsolutePath());

var skipDirs = new[] { "bin", "obj" };
var matchingFileTypes = new[] { "cshtml", "md", "css", "js", "png", "jpg" };
//Update links to reference the new S3 AppHost.cs + RockstarsService.cs source code
var replaceHtmlTokens = new Dictionary<string, string> {  
    { "title-bg.png", "title-bg-aws.png" }, //S3 Title Background
    { "https://gist.github.com/3617557.js", "https://gist.github.com/mythz/396dbf54ce6079cc8b2d.js" },
    { "https://gist.github.com/3616766.js", "https://gist.github.com/mythz/ca524426715191b8059d.js" },
    { "RazorRockstars.WebHost/RockstarsService.cs", "RazorRockstars.S3/RockstarsService.cs" },        
};

foreach (var file in fs.GetAllFiles())
{
    if (skipDirs.Any(x => file.VirtualPath.StartsWith(x))) continue;
    if (!matchingFileTypes.Contains(file.Extension)) continue;

    if (file.Extension == "cshtml")
    {
        var html = file.ReadAllText();
        replaceHtmlTokens.Each(x => html = html.Replace(x.Key, x.Value));
        s3.WriteFile(file.VirtualPath, html);
    }
    else
    {
        s3.WriteFile(file);
    }
}
```

During the import we also update the links in the Razor `*.cshtml` pages to reference the new RazorRockstars.S3 content.

### Update S3 Bucket to enable LiveReload of Razor Views and Markdown

Another nice feature of having all content maintained in an S3 Bucket is that you can just change files in the S3 Bucket 
directly and have all App Servers immediately reload the Razor Views, Markdown content and static resources without redeploying. 

#### CheckLastModifiedForChanges

To enable this feature we just tell the Razor and Markdown plugins to check the source file for changes before displaying each page:

```csharp
GetPlugin<MarkdownFormat>().CheckLastModifiedForChanges = true;
Plugins.Add(new RazorFormat { CheckLastModifiedForChanges = true });
```

When this is enabled the View Engines checks the ETag of the source file to find out if it's changed, if it did,
it will rebuild and replace it with the new view before rendering it. 
Given [S3 supports object versioning](http://docs.aws.amazon.com/AmazonS3/latest/dev/Versioning.html) this feature
should enable a new class of use-cases for developing Content Heavy management sites with ServiceStack.

#### Explicit RefreshPage

One drawback of enabling `CheckLastModifiedForChanges` is that it forces a remote S3 call for each view before rendering it.
A more efficient approach is to instead notify the App Servers which files have changed so they can reload them once,
alleviating the need for multiple ETag checks at runtime, which is the approach we've taken with the 
[UpdateS3 Service](https://github.com/ServiceStackApps/RazorRockstars/blob/e159bb9d2e27eba7fc1a9ce1822b479602de8e0f/src/RazorRockstars.S3/RockstarsService.cs#L139):

```csharp
if (request.Razor)
{
    var kurtRazor = VirtualFiles.GetFile("stars/dead/cobain/default.cshtml");
    VirtualFiles.WriteFile(kurtRazor.VirtualPath, 
        UpdateContent("UPDATED RAZOR", kurtRazor.ReadAllText(), request.Clear));
    HostContext.GetPlugin<RazorFormat>().RefreshPage(kurtRazor.VirtualPath); //Force reload of Razor View
}

var kurtMarkdown = VirtualFiles.GetFile("stars/dead/cobain/Content.md");
VirtualFiles.WriteFile(kurtMarkdown.VirtualPath, 
    UpdateContent("UPDATED MARKDOWN", kurtMarkdown.ReadAllText(), request.Clear));
HostContext.GetPlugin<MarkdownFormat>().RefreshPage(kurtMarkdown.VirtualPath); //Force reload of Markdown
```

#### Live Reload Demo

You can test live reloading of the above Service with the routes below which modify Markdown and Razor views with the
current time:

  - [/updateS3](http://awsrazor.netcore.io/updateS3) - Update Markdown Content
  - [/updateS3?razor=true](http://awsrazor.netcore.io/updateS3?razor=true) - Update Razor View
  - [/updateS3?razor=true&clear=true](http://awsrazor.netcore.io/updateS3?razor=true&clear=true) - Revert changes
  
::: info
This forces a recompile of the modified views which greatly benefits from a fast CPU and is a bit slow on our 
Live Demos server that's running on a **m1.small** instance shared with 25 other ASP.NET Web Applications
:::

## AWS Imgur

![](https://raw.githubusercontent.com/ServiceStack/Assets/master/img/aws/apps/screenshots/imgur.png)

### S3VirtualFiles 

The backend 
[ImageService.cs](https://github.com/ServiceStackApps/AwsApps/blob/master/src/AwsApps/imgur/ImageService.cs) 
implementation for AWS Imgur has been rewritten to use the Virtual FileSystem instead of 
[accessing the FileSystem directly](https://github.com/ServiceStackApps/Imgur/blob/master/src/Imgur/Global.asax.cs).
The benefits of this approach is that with 
[2 lines of configuration](https://github.com/ServiceStackApps/AwsApps/blob/4817f5c6ad69defd74d528403bfdb03e5958b0b3/src/AwsApps/AppHost.cs#L44-L45)
we can have files written to an S3 Bucket instead:

```csharp
var s3Client = new AmazonS3Client(AwsConfig.AwsAccessKey, AwsConfig.AwsSecretKey, RegionEndpoint.USEast1);
VirtualFiles = new S3VirtualFiles(s3Client, AwsConfig.S3BucketName);
```
If we comment out the above configuration any saved files are instead written to the local FileSystem (default).

The benefit of using managed S3 File Storage is better scalability as your App Servers can remain stateless, improved
performance as overhead of serving static assets can be offloaded by referencing the S3 Bucket directly and for even 
better responsiveness you can connect the S3 bucket to a CDN.

### Using S3VirtualFiles with S3 Compatible services

To use `S3VirtualFiles` with another service provider with an S3 compatible service, the configuration of the `AmazonS3Client` will be different.
For example, if we want to connect to [DigitalOcean Spaces](https://www.digitalocean.com/products/spaces) with `S3VirtualFiles` we would configure the `AmazonS3Client` with the following constructor.

```csharp
var doSpacesClient = new AmazonS3Client("my-spaces-key", "my-spaces-secret", 
    new AmazonS3Config
    {
        ServiceURL = "https://sfo3.digitaloceanspaces.com",
    });
var doSpacesVfs = new S3VirtualFiles(doSpacesClient, "my-spaces-name");
```

The `ServiceURL` is a region specific URL rather than the URL to your Space directly, and your Space name is provided as a bucket name in the `S3VirtualFiles`.

Other services might use the `AmazonS3Config` differently, but as long as the `AmazonS3Client` is configured correctly for the service you are using, the `S3VirtualFiles` can be used the same way.

## REST Files

![](https://raw.githubusercontent.com/ServiceStack/Assets/master/img/aws/apps/screenshots/restfiles.png)

REST Files GitHub-like explorer is another example that was 
[rewritten to use ServiceStack's Virtual File System](https://github.com/ServiceStackApps/AwsApps/blob/master/src/AwsApps/restfiles/FilesService.cs)
and now provides remote file management of an S3 Bucket behind a REST-ful API.

## AWS Email Contacts

![](https://raw.githubusercontent.com/ServiceStack/Assets/master/img/aws/apps/screenshots/emailcontacts.png)

### SqsMqServer

The AWS Email Contacts example shows the same long-running 
[EmailContact Service](https://github.com/ServiceStackApps/AwsApps/blob/4817f5c6ad69defd74d528403bfdb03e5958b0b3/src/AwsApps/emailcontacts/EmailContactServices.cs#L81)
being executed from both HTTP and MQ Server by just 
[changing which url the HTML Form is posted to](https://github.com/ServiceStackApps/AwsApps/blob/4817f5c6ad69defd74d528403bfdb03e5958b0b3/src/AwsApps/emailcontacts/default.cshtml#L203):

```html
//html
<form id="form-emailcontact" method="POST"
    action="@(new EmailContact().ToPostUrl())" 
    data-action-alt="@(new EmailContact().ToOneWayUrl())">
    ...
    <div>
        <input type="checkbox" id="chkAction" data-click="toggleAction" />
        <label for="chkAction">Email via MQ</label>
    </div>
    ...   
</form>
```

> The urls are populated from a typed Request DTO using the [Reverse Routing Extension methods](/routing#reverse-routing)

Checking the **Email via MQ** checkbox fires the JavaScript handler below that's registered as [declarative event in ss-utils.js](/ss-utils-js#declarative-events):

```js
$(document).bindHandlers({
    toggleAction: function() {
        var $form = $(this).closest("form"), action = $form.attr("action");
        $form.attr("action", $form.data("action-alt"))
                .data("action-alt", action);
    }
});
```

The code to configure and start an SQS MQ Server is similar to [other MQ Servers](/messaging): 

```csharp
container.Register<IMessageService>(c => new SqsMqServer(
    AwsConfig.AwsAccessKey, AwsConfig.AwsSecretKey, RegionEndpoint.USEast1) {
    DisableBuffering = true, // Trade-off latency vs efficiency
});

var mqServer = container.Resolve<IMessageService>();
mqServer.RegisterHandler<EmailContacts.EmailContact>(ExecuteMessage);
mqServer.Start();
```

When an MQ Server is registered, ServiceStack automatically publishes Requests accepted on the "One Way" [pre-defined route](/routing#pre-defined-routes) to the registered MQ broker. The message is later picked up and executed by a Message Handler on a background Thread.

## AWS Auth

![](https://raw.githubusercontent.com/ServiceStack/Assets/master/img/aws/apps/screenshots/awsauth.png)

### DynamoDbAuthRepository

AWS Auth is an example showing how easy it is to enable multiple Auth Providers within the same App which allows Sign-Ins from 
Twitter, Facebook, GitHub, Google, Yahoo and LinkedIn OAuth providers, as well as HTTP Basic and Digest Auth and 
normal Registered User logins and Custom User Roles validation, all managed in DynamoDB Tables using 
the registered `DynamoDbAuthRepository` below: 

```csharp
container.Register<IAuthRepository>(new DynamoDbAuthRepository(db, initSchema:true));
```

Standard registration code is used to configure the `AuthFeature` with all the different Auth Providers AWS Auth wants 
to support:

```csharp
return new AuthFeature(() => new AuthUserSession(),
    new IAuthProvider[]
    {
        new CredentialsAuthProvider(),              //HTML Form post of UserName/Password credentials
        new BasicAuthProvider(),                    //Sign-in with HTTP Basic Auth
        new DigestAuthProvider(AppSettings),        //Sign-in with HTTP Digest Auth
        new TwitterAuthProvider(AppSettings),       //Sign-in with Twitter
        new FacebookAuthProvider(AppSettings),      //Sign-in with Facebook
        new YahooOpenIdOAuthProvider(AppSettings),  //Sign-in with Yahoo OpenId
        new OpenIdOAuthProvider(AppSettings),       //Sign-in with Custom OpenId
        new GoogleOAuth2Provider(AppSettings),      //Sign-in with Google OAuth2 Provider
        new LinkedInOAuth2Provider(AppSettings),    //Sign-in with LinkedIn OAuth2 Provider
        new GithubAuthProvider(AppSettings),        //Sign-in with GitHub OAuth Provider
    })
{
    HtmlRedirect = "/awsauth/",                     //Redirect back to AWS Auth app after OAuth sign in
    IncludeRegistrationService = true,              //Include ServiceStack's built-in RegisterService
};
```

### DynamoDbAppSettings

The AuthFeature looks for the OAuth settings for each AuthProvider in the registered [AppSettings](/appsettings), which for deployed **Release** builds 
gets them from multiple sources. Since `DynamoDbAppSettings` is registered first in a `MultiAppSettings` collection
it checks entries in the DynamoDB `ConfigSetting` Table first before falling back to local 
[Web.config appSettings](https://github.com/ServiceStackApps/AwsApps/blob/4817f5c6ad69defd74d528403bfdb03e5958b0b3/src/AwsApps/Web.config#L15): 

```csharp
#if !DEBUG
    AppSettings = new MultiAppSettings(
        new DynamoDbAppSettings(new PocoDynamo(AwsConfig.CreateAmazonDynamoDb()), initSchema:true),
        new AppSettings()); // fallback to Web.confg
#endif
```

Storing production config in DynamoDB reduces the effort for maintaining production settings decoupled from source code. 
The App Settings were populated in DynamoDB using
[this simple script](https://github.com/ServiceStackApps/AwsApps/blob/9d4d3c3dfbf127ce0890d0984c264e8b440abd3f/src/AwsApps/AdminTasks.cs#L58)
which imports its settings from a local [appsettings.txt file](/appsettings#textfilesettings):

```csharp
var fileSettings = new TextFileSettings("~/../../deploy/appsettings.txt".MapHostAbsolutePath());
var dynamoSettings = new DynamoDbAppSettings(AwsConfig.CreatePocoDynamo());
dynamoSettings.InitSchema();

//dynamoSettings.Set("SmtpConfig", "{Username:REPLACE_USER,Password:REPLACE_PASS,Host:AWS_HOST,Port:587}");
foreach (var config in fileSettings.GetAll())
{
    dynamoSettings.Set(config.Key, config.Value);
}
```

#### ConfigSettings Table in DynamoDB

![](https://raw.githubusercontent.com/ServiceStack/Assets/master/img/release-notes/aws-configsettings.png)

## AWS Todos

![](https://raw.githubusercontent.com/ServiceStack/Assets/master/img/aws/apps/screenshots/todos.png)

The [Backbone TODO App](http://todomvc.com/examples/backbone/) is a famous minimal example used as a "Hello, World" 
example to showcase and compare JavaScript client frameworks. The example also serves as a good illustration of the 
clean and minimal code it takes to build a simple CRUD Service utilizing a DynamoDB back-end with the new PocoDynamo client:

```csharp
public class TodoService : Service
{
    public IPocoDynamo Dynamo { get; set; }

    public object Get(Todo todo)
    {
        if (todo.Id != default(long))
            return Dynamo.GetItem<Todo>(todo.Id);

        return Dynamo.GetAll<Todo>();
    }

    public Todo Post(Todo todo)
    {
        Dynamo.PutItem(todo);
        return todo;
    }

    public Todo Put(Todo todo)
    {
        return Post(todo);
    }

    public void Delete(Todo todo)
    {
        Dynamo.DeleteItem<Todo>(todo.Id);
    }
}
```

As it's a clean POCO, the `Todo` model can be also reused as-is throughout ServiceStack in Redis, OrmLite, Caching, Config, DTO's, etc:

```csharp
public class Todo
{
    [AutoIncrement]
    public long Id { get; set; }
    public string Content { get; set; }
    public int Order { get; set; }
    public bool Done { get; set; }
}
```

## [PocoDynamo](/aws-pocodynamo)

PocoDynamo is a highly productive, feature-rich, typed .NET client which extends 
[ServiceStack's Simple POCO life](http://stackoverflow.com/a/32940275/85785) 
by enabling re-use of your code-first data models with Amazon's industrial strength and highly-scalable 
NoSQL [DynamoDB](https://aws.amazon.com/dynamodb/).

![](https://raw.githubusercontent.com/ServiceStack/Assets/master/img/aws/pocodynamo/related-customer.png)

#### First class support for reusable, code-first POCOs

It works conceptually similar to ServiceStack's other code-first
[OrmLite](https://github.com/ServiceStack/ServiceStack.OrmLite) and 
[Redis](https://github.com/ServiceStack/ServiceStack.Redis) clients by providing a high-fidelity, managed client that enhances
AWSSDK's low-level [IAmazonDynamoDB client](http://docs.aws.amazon.com/amazondynamodb/latest/developerguide/UsingAWSsdkForDotNet.html), 
with rich, native support for intuitively mapping your re-usable code-first POCO Data models into 
[DynamoDB Data Types](http://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_Types.html). 

#### [AutoQuery DynamoDB](/aws-pocodynamo)

Built on top of PocoDynamo, [AutoQuery Data's](/autoquery/data) `DynamoDbSource` provides the most productive development experience for effortlessly creating rich, queryable and optimized Services for DynamoDB data stores using only a typed Request DTO.

### PocoDynamo Features

#### Advanced idiomatic .NET client

PocoDynamo provides an idiomatic API that leverages .NET advanced language features with streaming API's returning
`IEnumerable<T>` lazily evaluated responses that transparently performs multi-paged requests behind-the-scenes as the 
result set is iterated. It high-level API's provides a clean lightweight adapter to
transparently map between .NET built-in data types and DynamoDB's low-level attribute values. Its efficient batched 
API's take advantage of DynamoDB's `BatchWriteItem` and `BatchGetItem` batch operations to perform the minimum number 
of requests required to implement each API.

#### Typed, LINQ provider for Query and Scan Operations

PocoDynamo also provides rich, typed LINQ-like querying support for constructing DynamoDB Query and Scan operations, 
dramatically reducing the effort to query DynamoDB, enhancing readability whilst benefiting from Type safety in .NET. 

#### Declarative Tables and Indexes

Behind the scenes DynamoDB is built on a dynamic schema which whilst open and flexible, can be cumbersome to work with 
directly in typed languages like C#. PocoDynamo bridges the gap and lets your app bind to impl-free and declarative POCO 
data models that provide an ideal high-level abstraction for your business logic, hiding a lot of the complexity of 
working with DynamoDB - dramatically reducing the code and effort required whilst increasing the readability and 
maintainability of your Apps business logic.

It includes optimal support for defining simple local indexes which only require declaratively annotating properties 
to index with an `[Index]` attribute.

Typed POCO Data Models can be used to define more complex Local and Global DynamoDB Indexes by implementing 
`IGlobalIndex<Poco>` or `ILocalIndex<Poco>` interfaces which PocoDynamo uses along with the POCOs class structure 
to construct Table indexes at the same time it creates the tables.

In this way the Type is used as a DSL to define DynamoDB indexes where the definition of the index is decoupled from 
the imperative code required to create and query it, reducing the effort to create them whilst improving the 
visualization and understanding of your DynamoDB architecture which can be inferred at a glance from the POCO's 
Type definition. PocoDynamo also includes first-class support for constructing and querying Global and Local Indexes 
using a familiar, typed LINQ provider.

#### Resilient

Each operation is called within a managed execution which transparently absorbs the variance in cloud services 
reliability with automatic retries of temporary errors, using an exponential backoff as recommended by Amazon. 

#### Enhances existing APIs

PocoDynamo API's are a lightweight layer modeled after DynamoDB API's making it predictable the DynamoDB operations 
each API calls under the hood, retaining your existing knowledge investment in DynamoDB. 
When more flexibility is needed you can access the low-level `AmazonDynamoDBClient` from the `IPocoDynamo.DynamoDb` 
property and talk with it directly.

Whilst PocoDynamo doesn't save you for needing to learn DynamoDB, its deep integration with .NET and rich support for 
POCO's smoothes out the impedance mismatches to enable an type-safe, idiomatic, productive development experience.

#### High-level features

PocoDynamo includes its own high-level features to improve the re-usability of your POCO models and the development 
experience of working with DynamoDB with support for Auto Incrementing sequences, Query expression builders, 
auto escaping and converting of Reserved Words to placeholder values, configurable converters, scoped client 
configurations, related items, conventions, aliases, dep-free data annotation attributes and more.

### Download

PocoDynamo is contained in ServiceStack's AWS NuGet package:

:::copy
`<PackageReference Include="ServiceStack.Aws" Version="8.*" />`
:::
   
> PocoDynamo has a 10 Tables [free-quota usage](https://servicestack.net/download#free-quotas) limit which is unlocked with a [license key](https://servicestack.net/pricing).
    
To get started we'll need to create an instance of `AmazonDynamoDBClient` with your AWS credentials and Region info:

```csharp
var awsDb = new AmazonDynamoDBClient(AWS_ACCESS_KEY, AWS_SECRET_KEY, RegionEndpoint.USEast1);
```

Then to create a PocoDynamo client pass the configured AmazonDynamoDBClient instance above:

```csharp
var db = new PocoDynamo(awsDb);
```

::: info
Clients are Thread-Safe so you can register them as a singleton and share the same instance throughout your App
:::

### Creating a Table with PocoDynamo

PocoDynamo enables a declarative code-first approach where it's able to create DynamoDB Table schemas from just your 
POCO class definition. Whilst you could call `db.CreateTable<Todo>()` API and create the Table directly, the recommended 
approach is instead to register all the tables your App uses with PocoDynamo on Startup, then just call `InitSchema()` 
which will go through and create all missing tables:

```csharp
//PocoDynamo
var db = new PocoDynamo(awsDb)
    .RegisterTable<Todo>();

db.InitSchema();

db.GetTableNames().PrintDump();
```

In this way your App ends up in the same state with all tables created if it was started with **no tables**, **all tables** 
or only a **partial list** of tables. After the tables are created we query DynamoDB to dump its entire list of Tables, 
which if you started with an empty DynamoDB instance would print the single **Todo** table name to the Console:

```js
[
    Todo
]
```

### Managed DynamoDB Client

Every request in PocoDynamo is invoked inside a managed execution where any temporary errors are retried using the 
[AWS recommended retries exponential backoff](http://docs.aws.amazon.com/amazondynamodb/latest/developerguide/ErrorHandling.html#APIRetries).

All PocoDynamo API's returning `IEnumerable<T>` returns a lazy evaluated stream which behind-the-scenes sends multiple
paged requests as needed whilst the sequence is being iterated. As LINQ APIs are also lazily evaluated you could use 
`Take()` to only download however the exact number results you need. So you can query the first 100 table names with:

```csharp
//PocoDynamo
var first100TableNames = db.GetTableNames().Take(100).ToList();
```

and PocoDynamo will only make the minimum number of requests required to fetch the first 100 results.

## PocoDynamo Examples

### [DynamoDbCacheClient](/aws#managed-dynamodb-client)

We've been quick to benefit from the productivity advantages of PocoDynamo ourselves where we've used it to rewrite
[DynamoDbCacheClient](https://github.com/ServiceStack/ServiceStack/blob/main/ServiceStack.Aws/src/ServiceStack.Aws/DynamoDb/DynamoDbCacheClient.cs)
which is now just 2/3 the size and much easier to maintain than the existing 
[Community-contributed version](https://github.com/ServiceStack/ServiceStack/blob/22aca105d39997a8ea4c9dc20b242f78e07f36e0/src/ServiceStack.Caching.AwsDynamoDb/DynamoDbCacheClient.cs)
whilst at the same time extending it with even more functionality where it now implements the `ICacheClientExtended` API.

### [DynamoDbAuthRepository](https://github.com/ServiceStack/ServiceStack/blob/main/ServiceStack.Aws/src/ServiceStack.Aws/DynamoDb/DynamoDbAuthRepository.cs)

PocoDynamo's code-first Typed API made it much easier to implement value-added DynamoDB functionality like the 
[DynamoDbAuthRepository](https://github.com/ServiceStack/ServiceStack/blob/main/ServiceStack.Aws/src/ServiceStack.Aws/DynamoDb/DynamoDbAuthRepository.cs)
which due sharing a similar code-first POCO approach to OrmLite, ended up being a straight-forward port of the existing
[OrmLiteAuthRepository](https://github.com/ServiceStack/ServiceStack/blob/master/src/ServiceStack.Server/Auth/OrmLiteAuthRepository.cs)
where it was able to reuse the existing `UserAuth` and `UserAuthDetails` POCO data models.

### [DynamoDbTests](https://github.com/ServiceStack/ServiceStack/tree/main/ServiceStack.Aws/tests/ServiceStack.Aws.DynamoDbTests)

Despite its young age we've added a comprehensive test suite behind PocoDynamo which has become our exclusive client
for developing DynamoDB-powered Apps.

### [PocoDynamo Docs](/aws-pocodynamo)

This only scratches the surface of what PocoDynamo can do, comprehensive documentation is available in the 
[PocoDynamo project](/aws-pocodynamo) explaining how it compares to DynamoDB's AWSSDK client,
how to use it to store related data, how to query indexes and how to use its rich LINQ querying functionality to query
DynamoDB.

## [Getting started with AWS + ServiceStack Guides](https://github.com/ServiceStackApps/AwsGettingStarted)

Amazon offers managed hosting for a number of RDBMS and Caching servers which ServiceStack provides first-class
clients for. We've provided a number of guides to walk through setting up these services from your AWS account 
and connect to them with ServiceStack's typed .NET clients.

### [AWS RDS PostgreSQL and OrmLite](https://github.com/ServiceStackApps/AwsGettingStarted/blob/master/docs/postgres-guide.md)

[![](https://github.com/ServiceStack/Assets/raw/master/img/aws/rds-postgres-powered-by-aws.png)](https://github.com/ServiceStackApps/AwsGettingStarted/blob/master/docs/postgres-guide.md)

### [AWS RDS Aurora and OrmLite](https://github.com/ServiceStackApps/AwsGettingStarted/blob/master/docs/aurora-guide.md)

[![](https://github.com/ServiceStack/Assets/raw/master/img/aws/rds-aurora-powered-by-aws.png)](https://github.com/ServiceStackApps/AwsGettingStarted/blob/master/docs/aurora-guide.md)

### [AWS RDS MySQL and OrmLite](https://github.com/ServiceStackApps/AwsGettingStarted/blob/master/docs/mysql-guide.md)

[![](https://github.com/ServiceStack/Assets/raw/master/img/aws/rds-mysql-powered-by-aws.png)](https://github.com/ServiceStackApps/AwsGettingStarted/blob/master/docs/mssql-guide.md)

### [AWS RDS MariaDB and OrmLite](https://github.com/ServiceStackApps/AwsGettingStarted/blob/master/docs/mariadb-guide.md)

[![](https://github.com/ServiceStack/Assets/raw/master/img/aws/rds-mariadb-powered-by-aws.png)](https://github.com/ServiceStackApps/AwsGettingStarted/blob/master/docs/mariadb-guide.md)

### [AWS RDS SQL Server and OrmLite](https://github.com/ServiceStackApps/AwsGettingStarted/blob/master/docs/mssql-guide.md)

[![](https://github.com/ServiceStack/Assets/raw/master/img/aws/rds-sqlserver-powered-by-aws.png)](https://github.com/ServiceStackApps/AwsGettingStarted/blob/master/docs/mssql-guide.md)

### [AWS ElastiCache Redis and ServiceStack](https://github.com/ServiceStackApps/AwsGettingStarted/blob/master/docs/redis-guide.md)

[![](https://github.com/ServiceStack/Assets/raw/master/img/aws/elasticache-redis-powered-by-aws.png)](https://github.com/ServiceStackApps/AwsGettingStarted/blob/master/docs/redis-guide.md)

### [AWS ElastiCache Redis and ServiceStack](https://github.com/ServiceStackApps/AwsGettingStarted/blob/master/docs/memcached-guide.md)

[![](https://github.com/ServiceStack/Assets/raw/master/img/aws/elasticache-memcached-powered-by-aws.png)](https://github.com/ServiceStackApps/AwsGettingStarted/blob/master/docs/memcached-guide.md)

The source code used in each guide is also available in the [AwsGettingStarted](https://github.com/ServiceStackApps/AwsGettingStarted) repo.


# PocoDynamo
Source: https://docs.servicestack.net/aws-pocodynamo

is a highly productive, feature-rich, typed .NET client which extends 
[ServiceStack's Simple POCO life](http://stackoverflow.com/a/32940275/85785) 
by enabling re-use of your code-first data models with Amazon's industrial strength and highly-scalable 
NoSQL [DynamoDB](https://aws.amazon.com/dynamodb/).

## First class support for reusable, code-first POCOs

PocoDynamo is conceptually similar to ServiceStack's other code-first
[OrmLite](https://github.com/ServiceStack/ServiceStack.OrmLite) and 
[Redis](https://github.com/ServiceStack/ServiceStack.Redis) clients by providing a high-fidelity, managed client that enhances
AWSSDK's low-level [IAmazonDynamoDB client](http://docs.aws.amazon.com/amazondynamodb/latest/developerguide/UsingAWSsdkForDotNet.html), 
with rich, native support for intuitively mapping your re-usable code-first POCO Data models into 
[DynamoDB Data Types](http://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_Types.html). 

![](https://raw.githubusercontent.com/ServiceStack/Assets/master/img/aws/pocodynamo/related-customer.png)

### [AutoQuery DynamoDB](/aws-pocodynamo)

Built on top of PocoDynamo, [AutoQuery Data's](/autoquery/data) `DynamoDbSource` provides the most productive development experience 
for effortlessly creating rich, queryable and optimized Services for DynamoDB data stores using only a typed Request DTO.

### Quick Preview

A quick CRUD preview of **PocoDynamo** feature-rich high-level Typed client:

```csharp
using System;
using Amazon;
using Amazon.DynamoDBv2;
using ServiceStack;
using ServiceStack.Text;
using ServiceStack.Aws.DynamoDb;
using ServiceStack.DataAnnotations;

var awsDb = new AmazonDynamoDBClient("keyId","key",
    new AmazonDynamoDBConfig { ServiceURL="http://localhost:8000"});
var db = new PocoDynamo(awsDb);

public class Todo
{
    [AutoIncrement]
    public long Id { get; set; }
    public string Content { get; set; }
    public int Order { get; set; }
    public bool Done { get; set; }
}

db.RegisterTable<Todo>();

db.DeleteTable<Todo>();  // Delete existing Todo Table (if any)
db.InitSchema();         // Creates Todo DynamoDB Table

var newTodo = new Todo {
    Content = "Learn PocoDynamo",
    Order = 1
};
db.PutItem(newTodo);

var savedTodo = db.GetItem<Todo>(newTodo.Id);
"Saved Todo: {0}".Print(savedTodo.Dump());

savedTodo.Done = true;
db.PutItem(savedTodo);

var updatedTodo = db.GetItem<Todo>(newTodo.Id);
"Updated Todo: {0}".Print(updatedTodo.Dump());

db.DeleteItem<Todo>(newTodo.Id);

var remainingTodos = db.GetAll<Todo>();
"No more Todos: {0}".Print(remainingTodos.Dump());
```

## Features

#### Advanced idiomatic .NET client

PocoDynamo provides an idiomatic API that leverages .NET advanced language features with streaming API's returning
`IEnumerable<T>` lazily evaluated responses that transparently performs multi-paged requests 
behind-the-scenes whilst the resultset is iterated. It high-level API's provides a clean lightweight adapter to
transparently map between .NET built-in data types and DynamoDB's low-level attribute values. Its efficient batched 
API's take advantage of DynamoDB's `BatchWriteItem` and `BatchGetItem` batch operations to perform the minimum number 
of requests required to implement each API.

#### Typed, LINQ provider for Query and Scan Operations

PocoDynamo also provides rich, typed LINQ-like querying support for constructing DynamoDB Query and Scan operations, 
dramatically reducing the effort to query DynamoDB, enhancing readability whilst benefiting from Type safety in .NET. 

#### Declarative Tables and Indexes

Behind the scenes DynamoDB is built on a dynamic schema which whilst open and flexible, can be cumbersome to work with 
directly in typed languages like C#. PocoDynamo bridges the gap and lets your app bind to impl-free and declarative POCO 
data models that provide an ideal high-level abstraction for your business logic, hiding a lot of the complexity of 
working with DynamoDB - dramatically reducing the code and effort required whilst increasing the readability and 
maintainability of your Apps business logic.

It includes optimal support for defining simple local indexes which only require declaratively annotating properties 
to index with an `[Index]` attribute.

Typed POCO Data Models can be used to define more complex Local and Global DynamoDB Indexes by implementing 
`IGlobalIndex<Poco>` or `ILocalIndex<Poco>` interfaces which PocoDynamo uses along with the POCOs class structure 
to construct Table indexes at the same time it creates the tables.

In this way the Type is used as a DSL to define DynamoDB indexes where the definition of the index is decoupled from 
the imperative code required to create and query it, reducing the effort to create them whilst improving the 
visualization and understanding of your DynamoDB architecture which can be inferred at a glance from the POCO's 
Type definition. PocoDynamo also includes first-class support for constructing and querying Global and Local Indexes 
using a familiar, typed LINQ provider.

#### Resilient

Each operation is called within a managed execution which transparently absorbs the variance in cloud services 
reliability with automatic retries of temporary errors, using an exponential backoff as recommended by Amazon. 

#### Enhances existing APIs

PocoDynamo API's are a lightweight layer modeled after DynamoDB API's making it predictable the DynamoDB operations 
each API calls under the hood, retaining your existing knowledge investment in DynamoDB. 
When more flexibility is needed you can access the low-level `AmazonDynamoDBclient from the `IPocoDynamo.DynamoDb` 
property and talk with it directly.

Whilst PocoDynamo doesn't save you for needing to learn DynamoDB, its deep integration with .NET and rich support for 
POCO's smoothes out the impedance mismatches to enable an type-safe, idiomatic, productive development experience.

#### High-level features

PocoDynamo includes its own high-level features to improve the re-usability of your POCO models and the development 
experience of working with DynamoDB with support for Auto Incrementing sequences, Query expression builders, 
auto escaping and converting of Reserved Words to placeholder values, configurable converters, scoped client 
configurations, related items, conventions, aliases, dep-free data annotation attributes and more.

## Download

PocoDynamo is contained in ServiceStack's AWS NuGet package:

:::copy
`<PackageReference Include="ServiceStack.Aws" Version="8.*" />`
:::
 
> PocoDynamo has a 10 Tables [free-quota usage](https://servicestack.net/download#free-quotas) limit which can be unlocked with a [commercial license key](https://servicestack.net/pricing).
    
To get started we'll need to create an instance of `AmazonDynamoDBClient` with your AWS credentials and Region info:

```csharp
var awsDb = new AmazonDynamoDBClient(AWS_ACCESS_KEY, AWS_SECRET_KEY, RegionEndpoint.USEast1);
```

Then to create a PocoDynamo client pass the configured AmazonDynamoDBClient instance above:

```csharp
var db = new PocoDynamo(awsDb);
```

::: info
Clients are Thread-Safe so you can register them as a singleton and share the same instance throughout your App
:::

### [Source Code](https://github.com/ServiceStack/ServiceStack/tree/main/ServiceStack.Aws/src/ServiceStack.Aws/DynamoDb)

The Source Code for PocoDynamo is maintained in [ServiceStack.Aws](https://github.com/ServiceStack/ServiceStack/tree/main/ServiceStack.Aws) repository.

### Download Local DynamoDB

It's recommended to download [local DynamoDB](http://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Tools.DynamoDBLocal.html#Tools.DynamoDBLocal.DownloadingAndRunning)
as it lets you develop against a local DynamoDB instance, saving you needing a network connection or AWS account.

You can connect to your local DynamoDB instance by configuring the `AmazonDynamoDBClient` to point to the default url
where Local DynamoDB instance is running:

```csharp
var awsDb = new AmazonDynamoDBClient("keyId", "key", new AmazonDynamoDBConfig {
    ServiceURL = "http://localhost:8000",
});

var db = new PocoDynamo(awsDb);
```

We've found the latest version of Local DynamoDB to be a robust and fast substitute for AWS, that eliminates waiting 
times for things like creating and dropping tables whilst only slightly deviating from the capabilities of AWS where 
it doesn't always include the additional limitations imposed when hosted on AWS.

## Usage

To illustrate how PocoDynamo simplifies working with DynamoDB, we'll walk-through creating and retrieving the Simple 
[Todo model](https://github.com/ServiceStackApps/AwsApps/blob/04dea6472fd73ea2e55f1aa748fff6e8784b339c/src/AwsApps/todo/TodoService.cs#L9)
used in the DynamoDB-powered AWS Todo Example and compare it against the code
required when using AWSSDK's `IAmazonDynamoDB` client directly.

The simple `Todo` POCO is the same data model used to store TODO's in every major RDBMS's with 
[OrmLite](/ormlite/), in Redis with [ServiceStack.Redis](/redis/) as well as every supported [Caching provider](/caching). 

PocoDynamo increases the re-use of `Todo` again which can now be used to store TODO's in DynamoDB as well: 

```csharp
public class Todo
{
    [AutoIncrement]
    public long Id { get; set; }
    public string Content { get; set; }
    public int Order { get; set; }
    public bool Done { get; set; }
}
```

### Creating a Table with PocoDynamo

PocoDynamo enables a declarative code-first approach where it's able to create DynamoDB Table schemas from just your 
POCO class definition. Whilst you could call `db.CreateTable<Todo>()` API and create the Table directly, the recommended 
approach is instead to register all the tables your App uses with PocoDynamo on Startup, then just call `InitSchema()` 
which will go through and create all missing tables:

```csharp
//PocoDynamo
var db = new PocoDynamo(awsDb)
    .RegisterTable<Todo>();

db.InitSchema();

db.GetTableNames().PrintDump();
```

In this way your App ends up in the same state with all tables created if it was started with **no tables**, **all tables** 
or only a **partial list** of tables. After the tables are created we query DynamoDB to dump its entire list of Tables, 
which if you started with an empty DynamoDB instance would print the single **Todo** table name to the Console:

```js
[
    Todo
]
```

### Complete PocoDynamo TODO example

Before going through the details of how it all works under-the-hood, here's a quick overview of what it looks likes to 
use PocoDynamo for developing a simple CRUD App. The ServiceStack 
[TodoService](https://github.com/ServiceStackApps/AwsApps/blob/master/src/AwsApps/todo/TodoService.cs) 
below contains the full server implementation required to implement the REST API to power 
[Backbone's famous TODO App](http://todomvc.com/examples/backbone/), rewritten to store all TODO items in DynamoDB:

```csharp
//PocoDynamo
public class TodoService : Service
{
    public IPocoDynamo Dynamo { get; set; }

    public object Get(Todo todo)
    {
        if (todo.Id != default(long))
            return Dynamo.GetItem<Todo>(todo.Id);

        return Dynamo.GetAll<Todo>();
    }

    public Todo Post(Todo todo)
    {
        Dynamo.PutItem(todo);
        return todo;
    }

    public Todo Put(Todo todo)
    {
        return Post(todo);
    }

    public void Delete(Todo todo)
    {
        Dynamo.DeleteItem<Todo>(todo.Id);
    }
}
```

We can see `IPocoDynamo` is just a normal IOC dependency that provides high-level API's that work directly with POCO's 
and built-in .NET data types, enabling the minimum effort to store, get and delete data from DynamoDB.

### Creating a DynamoDB Table using AmazonDynamoDBClient

The equivalent imperative code to create the Todo DynamoDB table above would require creating executing the 
`CreateTableRequest` below:

```csharp
//AWSSDK
var request = new CreateTableRequest
{
    TableName = "Todo",
    KeySchema = new List<KeySchemaElement>
    {
        new KeySchemaElement("Id", KeyType.HASH),
    },
    AttributeDefinitions = new List<AttributeDefinition>
    {
        new AttributeDefinition("Id", ScalarAttributeType.N),
    },
    ProvisionedThroughput = new ProvisionedThroughput
    {
        ReadCapacityUnits = 10,
        WriteCapacityUnits = 5,
    }
};
awsDb.CreateTable(request);
```

DynamoDB Tables take a little while to create in AWS so we can't use it immediately, instead you'll need to 
periodically poll to check the status for when it's ready:

```csharp
//AWSSDK
var startAt = DateTime.UtcNow;
var timeout = TimeSpan.FromSeconds(60);
do
{
    try
    {
        var descResponse = awsDb.DescribeTable("Todo");
        if (descResponse.Table.TableStatus == DynamoStatus.Active)
            break;

        Thread.Sleep(TimeSpan.FromSeconds(2));
    }
    catch (ResourceNotFoundException)
    {
        // DescribeTable is eventually consistent. So you might get resource not found.
    }

    if (DateTime.UtcNow - startAt > timeout)
        throw new TimeoutException("Exceeded timeout of {0}".Fmt(timeout));

} while (true);
```

Once the table is Active we can start using it, to get the list of table names we send a `ListTablesRequest`:

```csharp
//AWSSDK
var listResponse = awsDb.ListTables(new ListTablesRequest());
var tableNames = listResponse.TableNames;
tableNames.PrintDump();
```

## Managed DynamoDB Client

As we can see using the `AmazonDynamoDBClient` directly requires a lot more imperative code, but it also ends up doing 
a lot less. We've not included the logic to query existing tables so only the missing tables are created, we've not 
implemented any error handling or Retry logic (important for Cloud Services) and we're not checking to make sure we've 
collected the entire list of results (implementing paging when necessary).

Whereas every request in PocoDynamo is invoked inside a managed execution where any temporary errors are retried using the 
[AWS recommended retries exponential backoff](http://docs.aws.amazon.com/amazondynamodb/latest/developerguide/ErrorHandling.html#APIRetries).

All PocoDynamo API's returning `IEnumerable<T>` returns a lazy evaluated stream which behind-the-scenes sends multiple
paged requests as needed whilst the sequence is being iterated. As LINQ API's are also lazily evaluated you could use 
`Take()` to only download the exact number results you need. So you can query the first 100 table names with:

```csharp
//PocoDynamo
var first100TableNames = db.GetTableNames().Take(100).ToList();
```

and PocoDynamo will only make the minimum number of requests required to fetch the first 100 results.

## AutoIncrement Primary Keys

Once the `Todo` table is created we can start adding TODOs to it. If we were using OrmLite. the `[AutoIncrement]` 
attribute lets us use the RDBMS's native support for auto incrementing sequences to populate the Id primary key. 
Unfortunately DynamoDB lacks an auto increment feature and instead recommends the user to supply a unique key as shown
in their [DynamoDB Forum example](http://docs.aws.amazon.com/amazondynamodb/latest/developerguide/DataModel.html)
where they've chosen a Forum Name as the Hash Key of the Forum and Thread tables, whilst the Reply comment uses a
concatenation of `ForumName` + `#` + `ThreadSubject` as its Hash Key and the `ReplyDateTime` for the Range Key. 

However auto incrementing Ids have a number of useful properties making it ideal for identifying data:

  - **Unique** - Each new item is guaranteed to have a unique Id that's higher than all Ids before it
  - **Sequential** - A useful property to ensure consistent results when paging or ordering
  - **Never change** - To ensure a constant key that never changes, Ids shouldn't contain data it references
  - **Easy to read** - Humans have a better chance to read and remember a number than a concatenated string
  - **Easy to reference** - It's easier to reference a predictable numeric field than a concatenated string

They're also more re-usable as most data stores have native support for integer primary keys. For these reasons we've
added support for Auto-Incrementing integer primary keys in PocoDynamo where Ids annotated with `[AutoIncrement]` 
attribute are automatically populated with the next id in its sequence.

#### ISequenceSource

The Auto Incrementing functionality is provided by the
[ISequenceSource](https://github.com/ServiceStack/ServiceStack/blob/master/src/ServiceStack.Interfaces/ISequenceSource.cs) 
interface:

```csharp
public interface ISequenceSource : IRequiresSchema
{
    long Increment(string key, int amount = 1);
    void Reset(string key, int startingAt = 0);
}
```
#### DynamoDbSequenceGenerator

The default implementation uses 
[DynamoDbSequenceGenerator](https://github.com/ServiceStack/ServiceStack/blob/main/ServiceStack.Aws/src/ServiceStack.Aws/DynamoDb/DynamoDbSequenceGenerator.cs)
which stores sequences for each table in the `Seq` DynamoDB Table so no additional services are required. To ensure
unique incrementing sequences in DynamoDB, PocoDynamo uses UpdateItemRequest's `AttributeValueUpdate` feature to perform
atomic value updates. PocoDynamo sequences are also very efficient and only require a single DynamoDB call to populate a 
batch of Primary Key Ids which are also guaranteed to be in order (and without gaps) for batches that are stored together. 

#### RedisSequenceSource

If preferred you can instead instruct PocoDynamo to maintain sequences in Redis using 
[RedisSequenceSource](https://github.com/ServiceStack/ServiceStack/blob/master/src/ServiceStack.Server/RedisSequenceSource.cs)
or alternatively inject your own implementation which can be configured in PocoDynamo with:

```csharp
var db = new PocoDynamo(awsDb) {
    Sequences = new RedisSequenceSource(redisManager),
};
```

## Putting items with PocoDynamo

As we can take advantage of Auto Incrementing Id's, storing Items becomes as simple as creating a number of POCO's and
calling PutItems:

```csharp
//PocoDynamo
var todos = 100.Times(i => new Todo { Content = "TODO " + i, Order = i });
db.PutItems(todos);
```

## Putting items with AmazonDynamoDBClient

To do this manually with `AmazonDynamoDBClient` you'd need to create and `UpdateItemRequest` to update the counter
maintaining your TODO sequences:

```csharp
//AWSSDK
var incrRequest = new UpdateItemRequest
{
    TableName = "Seq",
    Key = new Dictionary<string, AttributeValue> {
        {"Id", new AttributeValue { S = "Todo" } }
    },
    AttributeUpdates = new Dictionary<string, AttributeValueUpdate> {
        {
            "Counter",
            new AttributeValueUpdate {
                Action = AttributeAction.ADD,
                Value = new AttributeValue { N = "100" }
            }
        }
    },
    ReturnValues = ReturnValue.ALL_NEW,
};

var response = awsDb.UpdateItem(incrRequest);
var nextSequences = Convert.ToInt64(response.Attributes["Counter"].N);
```

After you know which sequence to start with you can start putting items using a Dictionary of Attribute Values:

```csharp
//AWSSDK
for (int i = 0; i < 100; i++)
{
    var putRequest = new PutItemRequest("Todo",
        new Dictionary<string, AttributeValue> {
            { "Id", new AttributeValue { N = (nextSequences - 100 + i).ToString() } },
            { "Content", new AttributeValue("TODO " + i) },
            { "Order", new AttributeValue { N = i.ToString() } },
            { "Done", new AttributeValue { BOOL = false } },
        });

    awsDb.PutItem(putRequest);
}
```

Although even without the managed execution this still isn't equivalent to PocoDynamo's example above as to store 
multiple items efficiently PocoDynamo `PutItems()` API batches multiple Items in 4x `BatchWriteItemRequest` 
behind-the-scenes, the minimum number needed due to DynamoDB's maximum Write Batch size limit of 25 requests.

## Getting Items with PocoDynamo

Getting an item just requires the Generic Type and the primary key of the item to fetch:

```csharp
var todo = db.GetItem<Todo>(1);
todo.PrintDump();
```

Which returns the Todo item if it exists, or `null` if it doesn't.

Fetching all table items is where an understanding of DynamoDB's architecture and its limits become important. DynamoDB 
achieves its scalability by partitioning your data across multiple partitions based on its hash Key (aka Primary Key). 
This means that the only way to efficiently query across data containing multiple primary keys is to either explicitly 
create a [Global Secondary Index](http://docs.aws.amazon.com/amazondynamodb/latest/developerguide/GSI.html) or perform a 
full-table Scan. 

However table scans in DynamoDB are more inefficient than full table scans in RDBMS's since it has to scan across
multiple partitions which can quickly use up your table's provisioned throughput, as such scans should be limited 
to low usage areas. 

With that said, you can do Table Scans in PocoDynamo using API's starting with `Scan*` prefix, e.g. to return
all Todo items:

```csharp
//PocoDynamo
IEnumerable<Todo> todos = db.ScanAll<Todo>();
```

As IEnumerable's are lazily executed, it only starts sending `ScanRequest` to fetch all Items once the IEnumerable is 
iterated, which it does in **batches of 1000** (configurable with `PocoDynamo.PagingLimit`). 

To fetch all items you can just call `ToList()`:

```csharp
var allTodos = todos.ToList();
allTodos.PrintDump();
```

Which incidentally is also just what `db.GetAll<Todo>()` does. 

## Getting Items with AWSSDK

To fetch the same single item with the AWSSDK client you'd construct and send a `GetItemRequest`, e.g:

```csharp
//AWSSDK
var request = new GetItemRequest
{
    TableName = "Todo",
    Key = new Dictionary<string, AttributeValue> {
        { "Id", new AttributeValue { N = "1"} }
    },
    ConsistentRead = true,
};

var response = awsDb.GetItem(request);
var todo = new Todo
{
    Id = Convert.ToInt64(response.Item["Id"].N),
    Content = response.Item["Content"].S,
    Order = Convert.ToInt32(response.Item["Order"].N),
    Done = response.Item["Done"].BOOL,
};
```

Although this is a little fragile as it doesn't handle the case when attributes (aka Properties) or the item doesn't exist.

Doing a full-table scan is pretty straight-forward although as you're scanning the entire table you'll want to implement
the paging to scan through all items, which looks like:

```csharp
//AWSSDK
var request = new ScanRequest
{
    TableName = "Todo",
    Limit = 1000,
};

var allTodos = new List<Todo>();
ScanResponse response = null;
do
{
    if (response != null)
        request.ExclusiveStartKey = response.LastEvaluatedKey;

    response = awsDb.Scan(request);

    foreach (var item in response.Items)
    {
        var todo = new Todo
        {
            Id = Convert.ToInt64(item["Id"].N),
            Content = item["Content"].S,
            Order = Convert.ToInt32(item["Order"].N),
            Done = item["Done"].BOOL,
        };
        allTodos.Add(todo);
    }
    
} while (response.LastEvaluatedKey != null && response.LastEvaluatedKey.Count > 0);

allTodos.PrintDump();
```

## Deleting an Item with PocoDynamo

Deleting an item is similar to getting an item which just needs the generic type and primary key:

```csharp
//PocoDynamo
db.DeleteItem<Todo>(1);
```

## Deleting an Item with AWSSDK

Which just sends a `DeleteItemRequest` to delete the Item:

```csharp
//AWSSDK
var request = new DeleteItemRequest
{
    TableName = "Todo",
    Key = new Dictionary<string, AttributeValue> {
        { "Id", new AttributeValue { N = "1"} }
    },
};

awsDb.DeleteItem(request);
```

## Updating an Item with PocoDynamo

The simplest usage is to pass in a partially populated POCO where any Hash or Range Keys are added to the 
Key Condition and any non-default values are replaced. E.g the query below updates the Customer's Age to **42**:

```csharp
db.UpdateItemNonDefaults(new Customer { Id = customer.Id, Age = 42 });
```

DynamoDB's UpdateItem supports 3 different operation types: 

 - `PUT` to replace an Attribute Value
 - `ADD` to add to an existing Attribute Value
 - `DELETE` to delete the specified Attributes

Examples of all 3 are contained in the examples below which changes the Customer's `Nationality` to 
**Australian**, reduces their `Age` by **1** and deletes their `Name` and `Orders`:

```csharp
db.UpdateItem(customer.Id, 
    put: () => new Customer {
        Nationality = "Australian"
    },
    add: () => new Customer {
        Age = -1
    },
    delete: x => new { x.Name, x.Orders });
```

The same Typed API above is also available in the more flexible and untyped form below:

```csharp
db.UpdateItem<Customer>(new DynamoUpdateItem
{
    Hash = customer.Id,
    Put = new Dictionary<string, object>
    {
        { "Nationality", "Australian" },
    },
    Add = new Dictionary<string, object>
    {
        { "Age", -1 }
    },
    Delete = new[] { "Name", "Orders" },
});
```

### Update with Conditional Expressions

PocoDynamo also has Typed API support for 
[DynamoDB Conitional Expressions](http://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_PutItem.html#API_PutItem_RequestSyntax)
by using the `Condition()` API, e.g:

```csharp
var q = db.UpdateExpression<Customer>(customer.Id)
    .Set(() => new Customer { Nationality = "Australian" })
    .Add(() => new Customer { Age = decrBy })
    .Remove(x => new { x.Name, x.Orders })
    .Condition(x => x.Age == 27);

var succeeded = db.UpdateItem(q);
```

## Querying

The simple Todo example should give you a feel for using PocoDynamo to handle basic CRUD operations. 
Another area where PocoDynamo adds a lot of value which can be fairly cumbersome to do without, is in creating
[Query and Scan](http://docs.aws.amazon.com/amazondynamodb/latest/developerguide/QueryAndScan.html) 
requests to query data in DynamoDB Tables.

### QueryExpressions are QueryRequests

The query functionality in PocoDynamo is available on the `QueryExpression<T>` class which is used as a typed query 
builder to construct your Query request. An important attribute about QueryExpression's are that they inherit AWSSDK's 
[QueryRequest](http://docs.aws.amazon.com/amazondynamodb/latest/developerguide/LowLevelDotNetQuerying.html) Request DTO. 

This provides a number of benefits, they're easy to use and highly introspectable since each API just populates 
different fields in the Request DTO. They're also highly reusable as QueryExpressions can be executed as-is in AWSSDK 
DynamoDB client and vice-versa with PocoDynamo's `Query` API's executing both `QueryExpression<T>` and `QueryRequest` 
DTOs. The difference with PocoDynamo's Query API is that they provide managed exeuction, lazy evaluation, paged queries 
and auto-conversion of dynamic results into typed POCOs.

### Query Usage

[DynamoDB Query's](http://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_Query.html) enable efficient 
querying of data in DynamoDB as it's limited to querying the indexed Hash and Range Keys on your Tables or Table Indexes. 
Although it has the major limitation that it always needs to specify a Hash condition, essentially forcing the query 
to be scoped to a single partition. This makes it fairly useless for Tables with only a single Hash Primary Key like 
`Todo` as the query condition will always limit to a maximum of 1 result.

Nevertheless we can still use it to show how to perform server-side queries with PocoDynamo. To create a 
QueryExpression use the `FromQuery*` API's. It accepts a `KeyConditionExpression` as the first argument given it's a 
mandatory requirement for Query Requests which uses it to identify the partition the query should be executed on:

```csharp
var q = db.FromQuery<Todo>(x => x.Id == 1);
```

#### Key Condition and Filter Expressions

PocoDynamo parses this lambda expression to return a populated `QueryExpression<Todo>` which you can inspect to find 
the `TableName` set to **Todo** and the `KeyConditionExpression` set to **(Id = :k0)** with the 
`ExpressionAttributeValues` Dictionary containing a Numeric value of **1** for the key **:k0**.

From here you can continue constructing the QueryRequest DTO by populating its properties directly or by calling 
`QueryExpression` high-level methods (modeled after the properties they populate), e.g. the `KeyCondition()` method
populates the `KeyConditionExpression` property, `Filter()` populates the `FilterExpression` property and any arguments 
used in any expression are automatically parameterized and added to the `ExpressionAttributeValues` collection:

```csharp
var q = db.FromQuery<Todo>()
    .KeyCondition(x => x.Id == 1) //Equivalent to: db.FromQuery<Todo>(x => x.Id == 1)
    .Filter(x => x.Done);

q.TableName                 // Todo
q.KeyConditionExpression    // (Id = :k0)
q.FilterExpression          // Done = :true
q.ExpressionAttributeValues // :k0 = AttributeValue {N=1}, :true = AttributeValue {BOOL=true}
```

Filter expressions are applied after the query is executed which enable more flexible querying as they're not just 
limited to key fields and can be used to query any field to further filter the returned resultset.

### Executing Queries

After you've finished populating the Request DTO it can be executed with PocoDynamo's `Query()`. This returns a lazily 
evaluated resultset which you can use LINQ methods on to fetch the results. Given the primary key condition we know this 
will only return 0 or 1 rows based on whether or not the TODO has been completed which we can check with by calling 
LINQ's `FirstOrDefault()` method:

```csharp
var todo1Done = db.Query(q).FirstOrDefault();
```

Where `todo1Done` will hold the populated `Todo` if it was marked done, otherwise it will be `null`.

#### Expression Chaining

Most `QueryExpression` methods returns itself and an alternative to calling `Query` on PocoDynamo (or AWSSDK) to execute 
the Query, you can instead call the `Exec()` alias. This allows you to create and execute your DynamoDb Query in a 
single expression which can instead be rewritten as:

```csharp
var todo1Done = db.FromQuery<Todo>(x => x.Id == 1)
    .Filter(x => x.Done)
    .Exec()
    .FirstOrDefault();
```

### Scan Operations

Scan Operations work very similar to Query Operations but instead of using a `QueryExpression<T>` you would instead use a `ScanExpression<T>` which as it inherits from AWSSDK's `ScanRequest` Request DTO, provides the same reuse benefits as QueryExpression's. 

To create a Scan Request you would use the `FromScan<T>` API, e.g:

```csharp
var q = db.FromScan<Todo>();
```

More examples of how to use typed LINQ expressions for creating and executing Query and Scan requests are described later.

### Related Items

DynamoDB Queries are ideally suited for when the dataset is naturally isolated, e.g. multi-tenant Apps that are 
centered around Customer data so any related records are able to share the same `CustomerId` Hash Key. 

PocoDynamo has good support for maintaining related data which can re-use the same Data Annotations used to define 
POCO relationships in OrmLite, often letting you reuse your existing OrmLite RDBMS data models in DynamoDB as well.

To illustrate how to use PocoDynamo to maintain related data we'll walk through a typical Customer and Orders example:

```csharp
public class Customer
{
    [AutoIncrement]
    public int Id { get; set; }
    public string Name { get; set; }
    public CustomerAddress PrimaryAddress { get; set; }
}

public class CustomerAddress
{
    [AutoIncrement]
    public int Id { get; set; }
    public string Address { get; set; }
    public string State { get; set; }
    public string Country { get; set; }
}

[Alias("CustomerOrder")]
public class Order
{
    [AutoIncrement]
    public int Id { get; set; }

    [References(typeof(Customer))]
    public int CustomerId { get; set; }

    public string Product { get; set; }
    public int Qty { get; set; }

    [Index]
    public virtual decimal Cost { get; set; }
}
```

In order to use them we need to tell PocoDynamo which of the Types are Tables that it should create in DynamoDB which
we can do by registering them with PocoDynamo then calling `InitSchema()` which will go through and create any
of the tables that don't yet exist in DynamoDB: 

```csharp
db = new PocoDynamo(awsDb)
    .RegisterTable<Customer>()
    .RegisterTable<Order>();

db.InitSchema();
```

`InitSchema()` will also wait until the tables have been created so they're immediately accessible afterwards. 
As creating DynamoDB tables can take upwards of a minute in AWS you can use the 
[alternative Async APIs](https://github.com/ServiceStack/ServiceStack/blob/main/ServiceStack.Aws/src/ServiceStack.Aws/DynamoDb/IPocoDynamoAsync.cs)
if you wanted to continue to doing other stuff whilst the tables are being created in AWS, e.g:

```csharp
var task = db.InitSchemaAsync();

// do other stuff...

await task;
```

## Related Data

After the tables are created we can insert the top-level Customer record as normal:

```csharp
var customer = new Customer
{
    Name = "Customer",
    PrimaryAddress = new CustomerAddress
    {
        Address = "1 road",
        State = "NT",
        Country = "Australia",
    }
};

db.PutItem(customer);
```

Before adding the record, PocoDynamo also populates any `[AutoIncrement]` properties with the next number in the 
sequence for that Type. Any complex types stored on the `Customer` POCO like `CustomerAddress` gets persisted along
with the containing `Customer` entry and converted into a **Map** of DynamoDB Attribute Value pairs. We can view the 
[DynamoDB Web Console](http://docs.aws.amazon.com/amazondynamodb/latest/developerguide/ConsoleDynamoDB.html) 
to see how this is stored in DynamoDB:

![](https://raw.githubusercontent.com/ServiceStack/Assets/master/img/aws/pocodynamo/related-customer.png)

### Related Tables

You can define a related table using the `[References]` attribute to tell PocoDynamo what the parent table is, e.g:

```csharp
[Alias("CustomerOrder")]
public class Order
{
    [AutoIncrement]
    public int Id { get; set; }
    
    [References(typeof(Customer))]
    public int CustomerId { get; set; }   
    //...
}
```

Which PocoDynamo infers to create the table using the parent's `CustomerId` as its Hash Key, relegating its `Id` as
the Range Key for the table. This ensures the Order is kept in the same partition as all other related Customer Data, 
necessary in order to efficiently query a Customer's Orders. When both the Hash and Range Key are defined they're treated 
as the Composite Key for that table which needs to be unique for each item - guaranteed when using `[AutoIncrement]` Id's.

#### Inserting Related Data

After the table is created we can generate and insert random orders like any other table, e.g:

```csharp
var orders = 10.Times(i => new Order
{
    CustomerId = customer.Id,
    Product = "Item " + (i % 2 == 0 ? "A" : "B"),
    Qty = i + 2,
    Cost = (i + 2) * 2
});

db.PutItems(orders);
```

You can also use the alternative `PutRelatedItems()` API and get PocoDynamo to take care of populating the `CustomerId`:

```csharp
var orders = 10.Times(i => new Order
{
    Product = "Item " + (i % 2 == 0 ? "A" : "B"),
    Qty = i + 2,
    Cost = (i + 2) * 2
});

db.PutRelatedItems(customer.Id, orders);
```

Both examples results in the same data being inserted into the **CustomerOrder** DynamoDB table:

![](https://raw.githubusercontent.com/ServiceStack/Assets/master/img/aws/pocodynamo/related-customer-orders.png)

This also shows how the `[Alias]` attribute can be used to rename the `Order` Type as **CustomerOrder** in DynamoDB.

### Querying Related Tables

Now we have related data we can start querying it, something you may want to do is fetch all Customer Orders:

```csharp
var q = db.FromQuery<Order>(x => x.CustomerId == customer.Id);
var dbOrders = db.Query(q);
```

As getting related Items for a Hash Key is a popular query, it has an explicit API:

```csharp
var dbOrders = db.GetRelatedItems<Order>(customer.Id);
```

We can refine the query further by specifying a `FilterExpression` to limit the results DynamoDB returns:

```csharp
var expensiveOrders = q.Clone()
    .Filter(x => x.Cost > 10)
    .Exec();
```

> Using `Clone()` will create and modify a copy of the query, leaving the original one intact.

### [Local Secondary Indexes](http://docs.aws.amazon.com/amazondynamodb/latest/developerguide/LSI.html)

But filters aren't performed on an Index and can be inefficient if your table has millions of customer rows. By default 
only the Hash and Range Key are indexed, in order to efficiently query any other field you will need to create
a [Local Secondary Index](http://docs.aws.amazon.com/amazondynamodb/latest/developerguide/LSI.html) for it.

This is easily done in PocoDynamo by annotating the properties you want indexed with the `[Index]` attribute:

```csharp
public class Order
{
    //...    
    [Index]
    public decimal Cost { get; set; }
}
```

Which tells PocoDynamo to create a Local Secondary Index for the `Cost` property when it creates the table.

When one exists, you can query a Local Index with `LocalIndex()`:

```csharp
var expensiveOrders = q
    .LocalIndex(x => x.Cost > 10)
    .Exec();    
```

Which now performs the Cost query on an index. Although this only returns a partially populated Order, specifically
with just the Hash Key (CustomerId), Range Key (Id) and the field that's indexed (Cost):

```cs
expensiveOrders.PrintDump();
```

```js
[
    {
        Id: 5,
        CustomerId: 1,
        Qty: 0,
        Cost: 12
    },
    //...
]
```

This is due to [Local Secondary Indexes](http://docs.aws.amazon.com/amazondynamodb/latest/developerguide/LSI.html)
being just denormalized tables behind the scenes which by default only returns re-projected fields that were defined
when the Index was created. 

One way to return populated orders is to specify a custom `ProjectionExpression` with the fields you want returned.
E.g. You can create a request with a populated `ProjectionExpression` that returns all Order fields with:

```csharp
var expensiveOrders = q
    .LocalIndex(x => x.Cost > 10)
    .Select<Order>()              //Equivalent to: SelectTableFields()
    .Exec();
```

Which now returns:

```cs
expensiveOrders.PrintDump();
```

```js
[
    {
        Id: 5,
        CustomerId: 1,
        Product: Item A,
        Qty: 6,
        Cost: 12
    },
    //...
]
```

### Typed Local Indexes

Using a custom `ProjectionExpression` is an easy work-around, although for it to work DynamoDB needs to consult the
primary table to fetch the missing fields for each item. For large tables that are frequently accessed, the query
can be made more efficient by projecting the fields you want returned when the Index is created. 

You can can tell PocoDynamo which additional fields it should reproject by creating a **Typed Local Index** which is 
just a POCO implementing `ILocalIndex<T>` containing all the fields the index should contain, e.g:

```csharp
public class OrderCostLocalIndex : ILocalIndex<Order>
{
    [Index]
    public decimal Cost { get; set; }
    public int CustomerId { get; set; }

    public int Id { get; set; }
    public int Qty { get; set; }
}

[References(typeof(OrderCostLocalIndex))]
public class Order { ... }
```

Then use the `[References]` attribute to register the Typed Index so PocoDynamo knows which additional indexes needs 
to be created with the table. The `[Index]` attribute is used to specify which field is indexed (Range Key) whilst 
the `CustomerId` is automatically used the Hash Key for the Local Index Table.

#### Querying Typed Indexes

To query a typed Index, use `FromQueryIndex<T>()` which returns a populated Query Request with the Table and Index Name.
As `Cost` is now the Range Key of the Local Index table it can be queried together with the `CustomerId` Hash Key in 
the Key Condition expression:

```csharp
List<OrderCostLocalIndex> expensiveOrderIndexes = db.FromQueryIndex<OrderCostLocalIndex>(x => 
        x.CustomerId == customer.Id && x.Cost > 10)
    .Exec();
```

This returns a list of populated indexes that now includes the `Qty` field:

```cs
expensiveOrderIndexes.PrintDump();
```

```js
[
    {
        Cost: 12,
        CustomerId: 1,
        Id: 5,
        Qty: 6
    },
    //...
]
```

If preferred you can easily convert Typed Index into Orders by using ServiceStack's [built-in Auto-Mapping](/auto-mapping), e.g:

```csharp
List<Order> expensiveOrders = expensiveOrderIndexes
    .Map(x => x.ConvertTo<Order>());
```

### [Global Secondary Indexes](http://docs.aws.amazon.com/amazondynamodb/latest/developerguide/GSI.html)

The major limitation of Local Indexes is that they're limited to querying data in the same partition (Hash Key). 
To efficiently query an index spanning the entire dataset, you need to instead use a 
[Global Secondary Index](http://docs.aws.amazon.com/amazondynamodb/latest/developerguide/GSI.html).

Support for Global Indexes in PocoDynamo is similar to Typed Local Indexes, but instead implements `IGlobalIndex<T>`.
They also free you to choose a new Hash Key, letting you create an Index spanning all Customers. 

For example we can create a global index that lets us search the cost across all orders containing a particular product:

```csharp
public class OrderCostGlobalIndex : IGlobalIndex<Order>
{
    [HashKey]
    public string Product { get; set; }
    [Index]
    public decimal Cost { get; set; }

    public int CustomerId { get; set; }
    public int Qty { get; set; }
    public int Id { get; set; }
}

[References(typeof(OrderCostGlobalIndex))]
public class Order { ... }
```

Our Key Condition can now instead query Product and Cost fields across all Customer Orders:

```csharp
var expensiveItemAOrders = db.FromQueryIndex<OrderCostGlobalIndex>(x => 
        x.Product == "Item A" && x.Cost > 10)
    .Exec();
```

Which will print all **Item A** Orders with a **Cost > 10**:

```cs
expensiveItemAOrders.PrintDump();
```

```js
[
    {
        Product: Item A,
        Cost: 12,
        CustomerId: 1,
        Qty: 6,
        Id: 5
    },
    //...
]
```

## Scan Requests

You'll want to just use queries for any frequently accessed code running in production, although the full querying 
flexibility available in full table scan requests can be useful for ad hoc querying and to speed up development cycles
by initially starting with Scan queries then when the data requirements for your App's have been finalized, rewrite 
them to use indexes and queries.

To create Scan Requests you instead call the `FromScan*` API's, e.g:

```csharp
var allOrders = db.ScanAll<Order>();

var expensiveOrders = db.FromScan<Order>(x => x.Cost > 10)
    .Exec();
```

You can also perform scans on Global Indexes, but unlike queries they don't need to be limited to the Hash Key:

```csharp
var expensiveOrderIndexes = db
    .FromScanIndex<OrderCostGlobalIndex>(x => x.Cost > 10)
    .Exec();
```

Just like `QueryExpression<T>` the populated `ScanExpression<T>` inherits from AWSSDK's `ScanRequest` enabling the same
re-use benefits for `ScanRequest` as they do for QueryRequest's.

## Query and Scan Expressions

Both Scans and Query expressions benefit from a Typed LINQ-like expression API which can be used to populate the DTO's

 - **KeyConditionExpression** - for specifying conditions on tables Hash and Range keys (only: QueryRequest)
 - **FilterExpression** - for specifying conditions to filter results on other fields
 - **ProjectionExpression** - to specify any custom fields (default: all fields)

Each `QueryRequest` needs to provide a key condition which can be done when creating the QueryExpression:

```csharp
var orders = db.FromQuery<Order>(x => x.CustomerId == 1).Exec();

// Alternative explicit API
var expensiveOrders = db.FromQuery<Order>().KeyCondition(x => x.CustomerId == 1).Exec();
```

Whilst every condition on a `ScanRequest` is added to the FilterExpression: 

```csharp
var expensiveOrders = db.FromScan<Order>(x => x.Cost > 10).Exec();

// Alternative explicit API
var expensiveOrders = db.FromScan<Order>().Filter(x => x.Cost > 10).Exec();
```

Calling `Exec()` returns a lazily executed response which transparently sends multiple paged requests to fetch the 
results as needed, e.g calling LINQ's `.FirstOrDefault()` only makes a single request whilst `.ToList()` fetches the 
entire resultset. All streaming `IEnumerable<T>` requests are sent with the configured `PagingLimit` (default: 1000).

#### Custom Limits

Several of PocoDynamo API's have overloads that let you specify a custom limit. API's with limits are instead 
executed immediately with the limit specified and returned in a concrete List:

```csharp
List<Order> expensiveOrders = db.FromScan<Order>().Filter(x => x.Cost > 10).Exec(limit:5);
```

### Custom Filter Expressions

There are also custom overloads that can be used to execute a custom expression when more flexibility is needed:

```csharp
// Querying by Custom Filter Condition with anon args
var expensiveOrders = db.FromScan<Order>().Filter("Cost > :amount", new { amount = 10 }).Exec();

// Querying by Custom Filter Condition with loose-typed Dictionary
var expensiveOrders = db.FromScan<Order>().Filter("Cost > :amount", 
        new Dictionary<string, object> { { "amount", 10 } })
    .Exec();
```

### Custom Select Projections

By default queries return all fields defined on the POCO model. You can also customize the projected fields that are 
returned with the `Select*` and `Exec*` APIs:

```csharp
// Return partial fields from anon object
var partialOrders = db.FromScan<Order>().Select(x => new { x.CustomerId, x.Cost }).Exec();

// Return partial fields from array
var partialOrders = db.FromScan<Order>().Select(x => new[] { "CustomerId", "Cost" }).Exec();

// Return partial fields defined in a custom Poco
class CustomerCost
{
    public int CustomerId { get; set; }
    public virtual decimal Cost { get; set; }
}

var custCosts = db.FromScan<Order>().Select<CustomerCost>()
    .Exec()
    .Map(x => x.ConvertTo<CustomerCost>());

// Alternative shorter version of above
var custCosts = db.FromScan<Order>().ExecInto<CustomerCost>().ToList();

// Useful when querying and index and returing results in primary Order Poco 
List<Order> expensiveOrders = db.FromScanIndex<OrderCostGlobalIndex>(x => x.Cost > 10)
    .ExecInto<Order>();

// Return a single column of fields
List<int> orderIds = db.FromScan<Order>().ExecColumn(x => x.Id).ToList();
```

### Advanced LINQ Expressions

In addition to basic predicate conditions, DynamoDB also includes support for 
[additional built-in functions](http://docs.aws.amazon.com/amazondynamodb/latest/developerguide/Expressions.SpecifyingConditions.html)
which PocoDynamo also provides typed LINQ support for:

#### begins_with

Return items where string fields starts with a particular substring:

```csharp
var orders = db.FromScan<Order>(x => x.Product.StartsWith("Item A")).Exec();

// Equivalent to
var orders = db.FromScan<Order>(x => Dynamo.BeginsWith(x.Product, "Item A")).Exec();

var orders = db.FromScan<Order>().Filter("begins_with(Product, :s)", new { s = "Item A" }).Exec();
```

#### contains

Return items where string fields contains a particular substring:

```csharp
var orders = db.FromScan<Order>(x => x.Product.Contains("em A")).Exec();

// Equivalent to
var orders = db.FromScan<Order>(x => Dynamo.Contains(x.Product, "em A")).Exec();

var orders = db.FromScan<Order>().Filter("contains(Product, :s)", new { s = "em A" }).Exec();
```

#### in

Returns items where fields exist in a particular collection:

```csharp
var qtys = new[] { 5, 10 };

var orders = db.FromScan<Order>(x => qtys.Contains(x.Qty)).Exec();

// Equivalent to
var orders = db.FromScan<Order>(x => Dynamo.In(x.Qty, qtys)).Exec();

var orders = db.FromScan<Order>().Filter("Qty in(:q1,:q2)", new { q1 = 5, q2 = 10 }).Exec();
```

#### size

Returns items where the string length equals a particular size:

```csharp
var orders = db.FromScan<Order>(x => x.Product.Length == 6).Exec();

// Equivalent to
var orders = db.FromScan<Order>(x => Dynamo.Size(x.Product) == 6).Exec();

var orders = db.FromScan<Order>().Filter("size(Product) = :n", new { n = 6 }).Exec();
```

Size also works for querying the size of different native DynamoDB collections, e.g:

```csharp
public class IntCollections
{
    public int Id { get; set; }

    public int[] ArrayInts { get; set; }
    public HashSet<int> SetInts { get; set; }
    public List<int> ListInts { get; set; }
    public Dictionary<int, int> DictionaryInts { get; set; }
}

var results = db.FromScan<IntCollections>(x =>
        x.ArrayInts.Length == 10 &&
        x.SetInts.Count == 10 &&
        x.ListInts.Count == 10 &&
        x.DictionaryInts.Count == 10)
    .Exec();
```

#### between

Returns items where field values fall within a particular range (inclusive):

```csharp
var orders = db.FromScan<Order>(x => Dynamo.Between(x.Qty, 3, 5)).Exec();

// Equivalent to
var orders = db.FromScan<Order>(x => x.Qty >= 3 && x.Qty <= 5).Exec();

var orders = db.FromScan<Order>().Filter("Qty between :from and :to", new { from = 3, to = 5 }).Exec();
```

#### attribute_type

Return items where field is of a particular type:

```csharp
var orders = db.FromScan<Order>(x => 
        Dynamo.AttributeType(x.Qty, DynamoType.Number) &&
        Dynamo.AttributeType(x.Product, DynamoType.String))
    .Exec();

// Equivalent to
var orders = db.FromScan<Order>().Filter(
        "attribute_type(Qty, :n) and attribute_type(Product, :s)", new { n = "N", s = "S"})
    .Exec();
```

Valid Types: L (List), M (Map), S (String), SS (StringSet), N (Number), NS (NumberSet), B (Binary), BS, BOOL, NULL

#### attribute_exists

Return items where a particular field exists. As the schema of your data models evolve you can use this to determine
whether items are of an old or new schema:

```csharp
var newOrderTypes = db.FromScan<Order>(x => Dynamo.AttributeExists(x.NewlyAddedField)).Exec();

// Equivalent to
var newOrderTypes = db.FromScan<Order>().Filter("attribute_exists(NewlyAddedField)").Exec();
```

#### attribute_not_exists

Return items where a particular field does not exist:

```csharp
var oldOrderTypes = db.FromScan<Order>(x => Dynamo.AttributeNotExists(x.NewlyAddedField)).Exec();

// Equivalent to
var oldOrderTypes = db.FromScan<Order>().Filter("attribute_not_exists(NewlyAddedField)").Exec();
```

### Defaults and Custom Behavior

PocoDynamo is configured with the defaults below which it uses throughout its various API's when used in creating and 
querying tables:

```csharp
//Defaults:
var db = new PocoDynamo(awsDb) {
    PollTableStatus = TimeSpan.FromSeconds(2),
    MaxRetryOnExceptionTimeout = TimeSpan.FromSeconds(60),
    ReadCapacityUnits = 10,
    WriteCapacityUnits = 5,
    ConsistentRead = true,
    ScanIndexForward = true,
    PagingLimit = 1000,
};
```

If you wanted to query with different behavior you can create a clone of the client with the custom settings you want,
e.g. you can create a client that performs eventually consistent queries with:

```csharp
IPocoDynamo eventuallyConsistentDb = db.ClientWith(consistentRead:false);
```

## Table definition

To support different coding styles, readability/dependency preferences and levels of data model reuse, PocoDynamo 
enables a wide array of options for specifying a table's Hash and Range Keys, in the following order or precedence:

**Note: Hash and Range keys cannot be read-only calculated properties.

### Specifying a Hash Key

Using the AWSSDK's `[DynamoDBHashKey]` attribute:

```csharp
public class Table
{
    [DynamoDBHashKey]
    public int CustomId { get; set; }
}
```

This requires your models to have a dependency to the **AWSSDK.DynamoDBv2** NuGet package which can be avoided by using 
**ServiceStack.Interfaces** `[HashKey]` attribute instead which your models already likely have a reference to:

```csharp
public class Table
{
    [HashKey]
    public int CustomId { get; set; }
}
```

You can instead avoid any attributes using the explicit **HashKey** Naming convention:

```csharp
public class Table
{
    public int HashKey { get; set; }
}
```

For improved re-usability of your models you can instead use the generic annotations for defining a model's primary key:

```csharp
public class Table
{
    [PrimaryKey]
    public int CustomId { get; set; }
}
```

```csharp
public class Table
{
    [AutoIncrement]
    public int CustomId { get; set; }
}
```

Alternative using the Universal `Id` naming convention:

```csharp
public class Table
{
    public int Id { get; set; }
}
```

If preferred both Hash and Range Keys can be defined together with the class-level `[CompositeKey]` attribute:

```csharp
[CompositeKey("CustomHash", "CustomRange")]
public class Table
{
    public int CustomHash { get; set; }
    public int CustomRange { get; set; }
}
```

### Specifying a Range Key

For specifying the Range Key use can use the **AWSSDK.DynamoDBv2** Attribute:

```csharp
public class Table
{
    [DynamoDBRangeKey]
    public int CustomId { get; set; }
}
```

The **ServiceStack.Interfaces** attribute:

```csharp
public class Table
{
    [RangeKey]
    public int CustomId { get; set; }
}
```

Or without attributes, using the explicit `RangeKey` property name:

```csharp
public class Table
{
    public int RangeKey { get; set; }
}
```

## Examples

### [DynamoDbCacheClient](https://github.com/ServiceStack/ServiceStack/blob/main/ServiceStack.Aws/src/ServiceStack.Aws/DynamoDb/DynamoDbCacheClient.cs)

We've been quick to benefit from the productivity advantages of PocoDynamo ourselves where we've used it to rewrite
[DynamoDbCacheClient](https://github.com/ServiceStack/ServiceStack/blob/main/ServiceStack.Aws/src/ServiceStack.Aws/DynamoDb/DynamoDbCacheClient.cs)
which is now just 2/3 the size and much easier to maintain than the existing 
[Community-contributed version](https://github.com/ServiceStack/ServiceStack/blob/22aca105d39997a8ea4c9dc20b242f78e07f36e0/src/ServiceStack.Caching.AwsDynamoDb/DynamoDbCacheClient.cs)
whilst at the same time extending it with even more functionality where it now implements the `ICacheClientExtended` API.

### [DynamoDbAuthRepository](https://github.com/ServiceStack/ServiceStack/blob/main/ServiceStack.Aws/src/ServiceStack.Aws/DynamoDb/DynamoDbAuthRepository.cs)

PocoDynamo's code-first Typed API made it much easier to implement value-added DynamoDB functionality like the new
[DynamoDbAuthRepository](https://github.com/ServiceStack/ServiceStack/blob/main/ServiceStack.Aws/src/ServiceStack.Aws/DynamoDb/DynamoDbAuthRepository.cs)
which due sharing a similar code-first POCO approach to OrmLite, ended up being a straight-forward port of the existing
[OrmLiteAuthRepository](https://github.com/ServiceStack/ServiceStack/blob/master/src/ServiceStack.Server/Auth/OrmLiteAuthRepository.cs)
where it was able to reuse the existing `UserAuth` and `UserAuthDetails` data models.

### [DynamoDbTests](https://github.com/ServiceStack/ServiceStack/tree/main/ServiceStack.Aws/tests/ServiceStack.Aws.DynamoDbTests)

Despite its young age we've added a comprehensive test suite behind PocoDynamo which has become our exclusive client
for developing DynamoDB-powered Apps.

### AWS Apps

The [Live Demos](https://github.com/ServiceStackApps/LiveDemos) below were rewritten from their original RDBMS and OrmLite
backends to utilize a completely managed AWS Stack that now uses PocoDynamo and a DynamoDB-backend:

![](https://raw.githubusercontent.com/ServiceStack/Assets/master/img/aws/pocodynamo/examples-razor-rockstars.png)

![](https://raw.githubusercontent.com/ServiceStack/Assets/master/img/aws/pocodynamo/examples-email-contacts.png)

![](https://raw.githubusercontent.com/ServiceStack/Assets/master/img/aws/pocodynamo/examples-todos.png)

![](https://raw.githubusercontent.com/ServiceStack/Assets/master/img/aws/pocodynamo/examples-awsauth.png)

## IPocoClient API

```csharp
// Interface for the code-first PocoDynamo client
public interface IPocoDynamo : IPocoDynamoAsync, IRequiresSchema
{
    // Get the underlying AWS DynamoDB low-level client
    IAmazonDynamoDB DynamoDb { get; }

    // Get the numeric unique Sequence generator configured with this client
    ISequenceSource Sequences { get; }

    // Access the converters that converts POCO's into DynamoDB data types
    DynamoConverters Converters { get; }

    // How long should PocoDynamo keep retrying failed operations in an exponential backoff (default 60s)
    TimeSpan MaxRetryOnExceptionTimeout { get; }

    // Get the AWSSDK DocumentModel schema for this Table
    Table GetTableSchema(Type table);

    // Get PocoDynamo Table metadata for this table
    DynamoMetadataType GetTableMetadata(Type table);

    // Calls 'ListTables' to return all Table Names in DynamoDB
    IEnumerable<string> GetTableNames();

    // Creates any tables missing in DynamoDB from the Tables registered with PocoDynamo
    bool CreateMissingTables(IEnumerable<DynamoMetadataType> tables, TimeSpan? timeout = null);

    // Creates any tables missing from the specified list of tables
    bool CreateTables(IEnumerable<DynamoMetadataType> tables, TimeSpan? timeout = null);

    // Deletes all DynamoDB Tables
    bool DeleteAllTables(TimeSpan? timeout = null);

    // Deletes the tables in DynamoDB with the specified table names
    bool DeleteTables(IEnumerable<string> tableNames, TimeSpan? timeout = null);

    // Gets the POCO instance with the specified hash
    T GetItem<T>(object hash);

    // Gets the POCO instance with the specified hash and range value
    T GetItem<T>(object hash, object range);

    // Calls 'BatchGetItem' in the min number of batch requests to return POCOs with the specified hashes 
    List<T> GetItems<T>(IEnumerable<object> hashes);

    // Calls 'PutItem' to store instance in DynamoDB
    T PutItem<T>(T value, bool returnOld = false);

    // Calls 'BatchWriteItem' to efficiently store items in min number of batched requests
    void PutItems<T>(IEnumerable<T> items);

    // Deletes the instance at the specified hash
    T DeleteItem<T>(object hash, ReturnItem returnItem = ReturnItem.None);

    // Calls 'BatchWriteItem' to efficiently delete all items with the specified hashes
    void DeleteItems<T>(IEnumerable<object> hashes);

    // Calls 'BatchWriteItem' to efficiently delete all items with the specified hash and range pairs
    void DeleteItems<T>(IEnumerable<DynamoId> hashes);

    // Calls 'UpdateItem' with ADD AttributeUpdate to atomically increment specific field numeric value
    long Increment<T>(object hash, string fieldName, long amount = 1);

    // Polls 'DescribeTable' until all Tables have an ACTIVE TableStatus
    bool WaitForTablesToBeReady(IEnumerable<string> tableNames, TimeSpan? timeout = null);

    // Polls 'ListTables' until all specified tables have been deleted
    bool WaitForTablesToBeDeleted(IEnumerable<string> tableNames, TimeSpan? timeout = null);

    // Updates item Hash field with hash value then calls 'PutItem' to store the related instance
    void PutRelatedItem<T>(object hash, T item);

    // Updates all item Hash fields with hash value then calls 'PutItems' to store all related instances
    void PutRelatedItems<T>(object hash, IEnumerable<T> items);

    // Calls 'Query' to return all related Items containing the specified hash value
    IEnumerable<T> GetRelatedItems<T>(object hash);

    // Deletes all items with the specified hash and ranges
    void DeleteRelatedItems<T>(object hash, IEnumerable<object> ranges);


    // Calls 'Scan' to return lazy enumerated results that's transparently paged across multiple queries
    IEnumerable<T> ScanAll<T>();

    // Creates a Typed `ScanExpression` for the specified table
    ScanExpression<T> FromScan<T>(Expression<Func<T, bool>> filterExpression = null);

    // Creates a Typed `ScanExpression` for the specified Global Index
    ScanExpression<T> FromScanIndex<T>(Expression<Func<T, bool>> filterExpression = null);

    // Executes the `ScanExpression` returning the specified maximum limit of results
    List<T> Scan<T>(ScanExpression<T> request, int limit);

    // Executes the `ScanExpression` returning lazy results transparently paged across multiple queries
    IEnumerable<T> Scan<T>(ScanExpression<T> request);

    // Executes AWSSDK `ScanRequest` returning the specified maximum limit of results
    List<T> Scan<T>(ScanRequest request, int limit);

    // Executes AWSSDK `ScanRequest` returning lazy results transparently paged across multiple queries
    IEnumerable<T> Scan<T>(ScanRequest request);

    // Executes AWSSDK `ScanRequest` with a custom conversion function to map ScanResponse to results
    IEnumerable<T> Scan<T>(ScanRequest request, Func<ScanResponse, IEnumerable<T>> converter);


    // Return Live ItemCount using Table ScanRequest
    long ScanItemCount<T>();

    // Return cached ItemCount in summary DescribeTable
    long DescribeItemCount<T>();


    // Creates a Typed `QueryExpression` for the specified table
    QueryExpression<T> FromQuery<T>(Expression<Func<T, bool>> keyExpression = null);

    // Executes the `QueryExpression` returning lazy results transparently paged across multiple queries
    IEnumerable<T> Query<T>(QueryExpression<T> request);

    // Executes the `QueryExpression` returning the specified maximum limit of results
    List<T> Query<T>(QueryExpression<T> request, int limit);

    // Creates a Typed `QueryExpression` for the specified Local or Global Index
    QueryExpression<T> FromQueryIndex<T>(Expression<Func<T, bool>> keyExpression = null);

    // Executes AWSSDK `QueryRequest` returning the specified maximum limit of results
    List<T> Query<T>(QueryRequest request, int limit);

    // Executes AWSSDK `QueryRequest` returning lazy results transparently paged across multiple queries
    IEnumerable<T> Query<T>(QueryRequest request);

    // Executes AWSSDK `QueryRequest` with a custom conversion function to map QueryResponse to results
    IEnumerable<T> Query<T>(QueryRequest request, Func<QueryResponse, IEnumerable<T>> converter);


    // Create a clone of the PocoDynamo client with different default settings
    IPocoDynamo ClientWith(
        bool? consistentRead = null,
        long? readCapacityUnits = null,
        long? writeCapacityUnits = null,
        TimeSpan? pollTableStatus = null,
        TimeSpan? maxRetryOnExceptionTimeout = null,
        int? limit = null,
        bool? scanIndexForward = null);

    // Disposes the underlying IAmazonDynamoDB client
    void Close();
}

// Available API's with Async equivalents
public interface IPocoDynamoAsync
{
    Task CreateMissingTablesAsync(IEnumerable<DynamoMetadataType> tables, 
        CancellationToken token = default(CancellationToken));

    Task WaitForTablesToBeReadyAsync(IEnumerable<string> tableNames, 
        CancellationToken token = default(CancellationToken));

    Task InitSchemaAsync();
}
```

### PocoDynamo Extension helpers

To maintain a minimumal surface area for PocoDynamo, many additional API's used to provide a more DRY typed API's were moved into
[PocoDynamoExtensions](https://github.com/ServiceStack/ServiceStack/blob/main/ServiceStack.Aws/src/ServiceStack.Aws/DynamoDb/PocoDynamoExtensions.cs)

```csharp
class PocoDynamoExtensions
{
    //Register Table
    DynamoMetadataType RegisterTable<T>();
    DynamoMetadataType RegisterTable(Type tableType);
    void RegisterTables(IEnumerable<Type> tableTypes);
    void AddValueConverter(Type type, IAttributeValueConverter valueConverter);

    //Get Table Metadata
    Table GetTableSchema<T>();
    DynamoMetadataType GetTableMetadata<T>();

    //Create Table
    bool CreateTableIfMissing<T>();
    bool CreateTableIfMissing(DynamoMetadataType table);
    bool CreateTable<T>(TimeSpan? timeout = null);

    bool DeleteTable<T>(TimeSpan? timeout = null);

    //Decrement API's
    long DecrementById<T>(object id, string fieldName, long amount = 1);
    long IncrementById<T>(object id, Expression<Func<T, object>> fieldExpr, long amount = 1);
    long DecrementById<T>(object id, Expression<Func<T, object>> fieldExpr, long amount = 1);

    List<T> GetAll<T>();
    T GetItem<T>(DynamoId id);

    //Typed API overloads for popular hash object ids
    List<T> GetItems<T>(IEnumerable<int> ids);
    List<T> GetItems<T>(IEnumerable<long> ids);
    List<T> GetItems<T>(IEnumerable<string> ids);

    void DeleteItems<T>(IEnumerable<int> ids);
    void DeleteItems<T>(IEnumerable<long> ids);
    void DeleteItems<T>(IEnumerable<string> ids);

    //Scan Helpers
    IEnumerable<T> ScanInto<T>(ScanExpression request);
    List<T> ScanInto<T>(ScanExpression request, int limit);

    //Query Helpers
    IEnumerable<T> QueryInto<T>(QueryExpression request);
    List<T> QueryInto<T>(QueryExpression request, int limit);
}
```


# Getting started with AWS &#x2B; ServiceStack
Source: https://docs.servicestack.net/aws-getting-started

![](https://raw.githubusercontent.com/ServiceStack/Assets/5744efd80015870e6441cef6e8fd8bbc79044945/img/aws/servicestack-aws-banner.png)

The [ServiceStackApps/AwsGettingStarted](https://github.com/ServiceStackApps/AwsGettingStarted) repository contains Visual Studio solutions for getting started with AWS and ServiceStack libraries, as well as step by step guides to get you started below.

## Amazon RDS
- [PostgreSQL](#getting-started-with-aws-rds-postgresql-and-ormlite)
- [Aurora](#getting-started-with-aws-rds-aurora-and-ormlite)
- [MySQL](#getting-started-with-aws-rds-mysql-and-ormlite)
- [MariaDB](#getting-started-with-aws-rds-mariadb-and-ormlite)
- [SQL Server](#getting-started-with-aws-rds-sql-server-and-ormlite)

## Amazon ElastiCache
- [Redis](#getting-started-with-aws-elasticache-redis-and-servicestack)
- [Memcached](#getting-started-with-aws-elasticache-and-servicestack)

## Getting Started with AWS RDS PostgreSQL and OrmLite

![](https://github.com/ServiceStack/Assets/raw/master/img/aws/rds-postgres-powered-by-aws.png)

ServiceStack.OrmLite library has support for use with a [PostgreSQL](http://www.postgresql.org/) database via the [`ServiceStack.OrmLite.PostgreSQL`](https://www.nuget.org/packages/ServiceStack.OrmLite.PostgreSQL/) NuGet package. This can be used in conjunction with Amazon's RDS service using PostgreSQL.

To get started, first you will need to create your PostgreSQL database via the AWS RDS service.

# Creating a PostgreSQL RDS Instance

1. Login to the [AWS Web console](https://console.aws.amazon.com/console/home).
2. Select [RDS](https://console.aws.amazon.com/rds/home) from the **Services** from the top menu.
![](https://raw.githubusercontent.com/ServiceStack/Assets/master/img/aws/aws-rds-menu.png)
3. Select **Instances** from the **RDS Dashboard** and click **Launch DB Instance**.
![](https://raw.githubusercontent.com/ServiceStack/Assets/master/img/aws/launch-db-dashboard.png)

The above steps will start the RDS Wizard to launch a new DB instance. To setup a new PostgreSQL instance, follow the wizard selecting the appropriate options for your application. As an example, we can create a `Customers` database for a non-production environment.

- **Select Engine** - Select PostgreSQL
- **Production?** - Select `No` for multi-instance/production setup
- **Specify DB Details** 
    - Create a `db.t2.micro` instance with default settings
    - Specify **Multi-AZ Deployment** as `No`

![](https://raw.githubusercontent.com/ServiceStack/Assets/master/img/aws/postgres-default-details.png)

- Specify **DB Instance Identifier**, eg `servicestack-example-customers`.
- Specify **Master Username**, eg `postgres`.
- Create and confirm master user password.

- **Configure Advanced Settings** - Leave the suggested settings and specify a database name, eg `customers`. This will be used in your connection string.

::: info
Problems can occur if your default VPC is not setup to DNS Resolution and/or DNS Hostname. Navigate to **Services**, **VPC** and enable these two options on your default VPC
:::

Click **Launch DB Instance** at the *bottom right* to launch your new instance. If all is successful, you should see the following.

![](https://github.com/ServiceStack/Assets/raw/master/img/aws/create-db-success.png)

## Connecting with ServiceStack.OrmLite
Now that you're PostgreSQL instance is running, connecting with OrmLite will require the `ServiceStack.OrmLite.PostgreSQL` NuGet package as well as connection string to your new PostgreSQL instance.

``` xml
<appSettings>
    <add key="ConnectionString" value="User ID={User};Password={Password};Host={Host};Port={Port};" />   
</appSettings>
```

:::copy
`<PackageReference Include="ServiceStack.OrmLite.PostgreSQL" Version="8.*" />`
:::

Once this dependency is installed, the `OrmLiteConnectionFactory` can be used with the `PostgreSqlDialect.Provider` can be configured in the AppHost Configure method. For example.

``` csharp
public class AppHost : AppSelfHostBase
{
    public AppHost() : base("AWS PostgreSQL Customers", typeof(AppHost).Assembly) {}

    public override void Configure(Container container)
    {
        container.Register<IDbConnectionFactory>(c => new OrmLiteConnectionFactory(
            AppSettings.GetString("ConnectionString"), PostgreSqlDialect.Provider));

        using (var db = container.Resolve<IDbConnectionFactory>().Open())
        {
            if (db.CreateTableIfNotExists<Customer>())
            {
                //Add seed data
            }
        }
    }
}

```

Using our connection from a ServiceStack Service, we can use the `Db` property to access our `Customer` table. Eg, Below is an example of a CRUD service using OrmLite.

``` csharp
public class CustomerService : Service
{
    public object Get(GetCustomers request)
    {
        return new GetCustomersResponse { Results = Db.Select<Customer>() };
    }

    public object Get(GetCustomer request)
    {
        return Db.SingleById<Customer>(request.Id);
    }

    public object Post(CreateCustomer request)
    {
        var customer = new Customer { Name = request.Name };
        Db.Save(customer);
        return customer;
    }

    public object Put(UpdateCustomer request)
    {
        var customer = Db.SingleById<Customer>(request.Id);
        if (customer == null)
            throw HttpError.NotFound("Customer '{0}' does not exist".Fmt(request.Id));

        customer.Name = request.Name;
        Db.Update(customer);

        return customer;
    }

    public void Delete(DeleteCustomer request)
    {
        Db.DeleteById<Customer>(request.Id);
    }
}
```

See the [OrmLite GitHub](/ormlite/ormlite-apis) page for more info on working with OrmLite API.

## Getting Started with AWS RDS Aurora and OrmLite

![](https://github.com/ServiceStack/Assets/raw/master/img/aws/rds-aurora-powered-by-aws.png)

ServiceStack.OrmLite library has support for use with an [Aurora](https://aws.amazon.com/rds/aurora/) database via the [`ServiceStack.OrmLite.MySql`](https://www.nuget.org/packages/ServiceStack.OrmLite.MySql/) NuGet package. This can be used in conjunction with Amazon's RDS service using Aurora.

To get started, first you will need to create your Aurora database via the AWS RDS service.

## Creating an Aurora Instance

1. Login to the [AWS Web console](https://console.aws.amazon.com/console/home).
2. Select [RDS](https://console.aws.amazon.com/rds/home) from the **Services** from the top menu.
![](https://raw.githubusercontent.com/ServiceStack/Assets/master/img/aws/aws-rds-menu.png)
3. Select **Instances** from the **RDS Dashboard** and click **Launch DB Instance**.
![](https://raw.githubusercontent.com/ServiceStack/Assets/master/img/aws/launch-db-dashboard.png)

The above steps will start the RDS Wizard to launch a new DB instance. To setup a new Aurora instance, follow the wizard selecting the appropriate options for your application. As an example, we can create a `Customers` database for a non-production environment.

- **Select Engine** - Select Amazon Aurora
- **Specify DB Details** 
    - Create a `db.r3.large` instance with default settings
    - Specify **Multi-AZ Deployment** as `No`

![](https://raw.githubusercontent.com/ServiceStack/Assets/master/img/aws/aurora-default-details.png)

- Specify **DB Instance Identifier**, eg `servicestack-example-customers`.
- Specify **Master Username**, eg `admin`.
- Create and confirm master user password.

- **Configure Advanced Settings** - Leave the suggested settings and specify a **Database Name**, eg `customers`. This will be used in your connection string.

::: info
Problems can occur if your default VPC is not setup to DNS Resolution and/or DNS Hostname. Navigate to **Services**, **VPC** and enable these two options on your default VPC. Default settings are to create a new VPC security group that will allow remote access to your DB instance based on your IP address. If your IP address changes, you will lose remote access and this security group will need to be updated
:::

Click **Launch DB Instance** at the *bottom right* to launch your new instance. If all is successful, you should see the following.

![](https://github.com/ServiceStack/Assets/raw/master/img/aws/create-db-success.png)

## Connecting with ServiceStack.OrmLite
Now that you're Aurora instance is running, connecting with OrmLite will require the `ServiceStack.OrmLite.MySql` NuGet package as well as connection string to your new Aurora instance.


``` xml
<appSettings>
    <add key="ConnectionString" value="Uid={User};Password={Password};Server={EndpointUrl};Port={EndpointPort};Database=customers" />   
</appSettings>
```

:::copy
`<PackageReference Include="ServiceStack.OrmLite.MySql" Version="8.*" />`
:::

Once this dependency is installed, the `OrmLiteConnectionFactory` can be used with the `MySqlDialect.Provider` can be configured in the AppHost Configure method. For example.

``` csharp
public class AppHost : AppSelfHostBase
{
    public AppHost() : base("AWS Aurora Customers", typeof(AppHost).Assembly) {}

    public override void Configure(Container container)
    {
        container.Register<IDbConnectionFactory>(c => new OrmLiteConnectionFactory(
            AppSettings.GetString("ConnectionString"), MySqlDialect.Provider));

        using (var db = container.Resolve<IDbConnectionFactory>().Open())
        {
            if (db.CreateTableIfNotExists<Customer>())
            {
                //Add seed data
            }
        }
    }
}

```

Using our connection from a ServiceStack Service, we can use the `Db` property to access our `Customer` table. Eg, Below is an example of a CRUD service using OrmLite.

``` csharp
public class CustomerService : Service
{
    public object Get(GetCustomers request)
    {
        return new GetCustomersResponse { Results = Db.Select<Customer>() };
    }

    public object Get(GetCustomer request)
    {
        return Db.SingleById<Customer>(request.Id);
    }

    public object Post(CreateCustomer request)
    {
        var customer = new Customer { Name = request.Name };
        Db.Save(customer);
        return customer;
    }

    public object Put(UpdateCustomer request)
    {
        var customer = Db.SingleById<Customer>(request.Id);
        if (customer == null)
            throw HttpError.NotFound("Customer '{0}' does not exist".Fmt(request.Id));

        customer.Name = request.Name;
        Db.Update(customer);

        return customer;
    }

    public void Delete(DeleteCustomer request)
    {
        Db.DeleteById<Customer>(request.Id);
    }
}
```

See the [OrmLite GitHub](/ormlite/ormlite-apis) page for more info on working with OrmLite API.

## Getting Started with AWS RDS MySQL and OrmLite

![](https://github.com/ServiceStack/Assets/raw/master/img/aws/rds-mysql-powered-by-aws.png)

ServiceStack.OrmLite library has support for use with a [MySQL](https://www.mysql.com/) database via the [`ServiceStack.OrmLite.MySql`](https://www.nuget.org/packages/ServiceStack.OrmLite.MySql/) NuGet package. This can be used in conjunction with Amazon's RDS service using MySQL.

To get started, first you will need to create your MySQL database via the AWS RDS service.

## Creating a MySQL RDS Instance

1. Login to the [AWS Web console](https://console.aws.amazon.com/console/home).
2. Select [RDS](https://console.aws.amazon.com/rds/home) from the **Services** from the top menu.
![](https://raw.githubusercontent.com/ServiceStack/Assets/master/img/aws/aws-rds-menu.png)
3. Select **Instances** from the **RDS Dashboard** and click **Launch DB Instance**.
![](https://raw.githubusercontent.com/ServiceStack/Assets/master/img/aws/launch-db-dashboard.png)

The above steps will start the RDS Wizard to launch a new DB instance. To setup a new MySQL instance, follow the wizard selecting the appropriate options for your application. As an example, we can create a `Customers` database for a non-production environment.

- **Select Engine** - Select MySQL
- **Production?** - Select `No` for multi-instance/production setup
- **Specify DB Details** 
    - Create a `db.t2.micro` instance with default settings
    - Specify **Multi-AZ Deployment** as `No`

![](https://raw.githubusercontent.com/ServiceStack/Assets/master/img/aws/mysql-default-details.png)

- Specify **DB Instance Identifier**, eg `servicestack-example-customers`.
- Specify **Master Username**, eg `admin`.
- Create and confirm master user password.

- **Configure Advanced Settings** - Leave the suggested settings and specify a database name, eg `customers`. This will be used in your connection string.

::: info
Problems can occur if your default VPC is not setup to DNS Resolution and/or DNS Hostname. Navigate to **Services**, **VPC** and enable these two options on your default VPC
:::

Click **Launch DB Instance** at the *bottom right* to launch your new instance. If all is successful, you should see the following.

![](https://github.com/ServiceStack/Assets/raw/master/img/aws/create-db-success.png)

## Connecting with ServiceStack.OrmLite
Now that you're MySQL instance is running, connecting with OrmLite will require the `ServiceStack.OrmLite.MySql` NuGet package as well as connection string to your new MySQL instance.

``` xml
<appSettings>
    <add key="ConnectionString" value="Uid={User};Password={Password};Server={EndpointUrl};Port={EndpointPort};Database=customers" />   
</appSettings>
```

:::copy
`<PackageReference Include="ServiceStack.OrmLite.MySql" Version="8.*" />`
:::

Once this dependency is installed, the `OrmLiteConnectionFactory` can be used with the `MySqlDialect.Provider` can be configured in the AppHost Configure method. For example.

``` csharp
public class AppHost : AppSelfHostBase
{
    public AppHost() : base("AWS MySql Customers", typeof(AppHost).Assembly) {}

    public override void Configure(Container container)
    {
        container.Register<IDbConnectionFactory>(c => new OrmLiteConnectionFactory(
            AppSettings.GetString("ConnectionString"), MySqlDialect.Provider));

        using (var db = container.Resolve<IDbConnectionFactory>().Open())
        {
            if (db.CreateTableIfNotExists<Customer>())
            {
                //Add seed data
            }
        }
    }
}

```

Using our connection from a ServiceStack Service, we can use the `Db` property to access our `Customer` table. Eg, Below is an example of a CRUD service using OrmLite.

``` csharp
public class CustomerService : Service
{
    public object Get(GetCustomers request)
    {
        return new GetCustomersResponse { Results = Db.Select<Customer>() };
    }

    public object Get(GetCustomer request)
    {
        return Db.SingleById<Customer>(request.Id);
    }

    public object Post(CreateCustomer request)
    {
        var customer = new Customer { Name = request.Name };
        Db.Save(customer);
        return customer;
    }

    public object Put(UpdateCustomer request)
    {
        var customer = Db.SingleById<Customer>(request.Id);
        if (customer == null)
            throw HttpError.NotFound("Customer '{0}' does not exist".Fmt(request.Id));

        customer.Name = request.Name;
        Db.Update(customer);

        return customer;
    }

    public void Delete(DeleteCustomer request)
    {
        Db.DeleteById<Customer>(request.Id);
    }
}
```

See the [OrmLite GitHub](/ormlite/ormlite-apis) page for more info on working with OrmLite API.

## Getting Started with AWS RDS MariaDB and OrmLite

![](https://github.com/ServiceStack/Assets/raw/master/img/aws/rds-mariadb-powered-by-aws.png)

ServiceStack.OrmLite library has support for use with a [MariaDB](https://mariadb.org/) database via the [`ServiceStack.OrmLite.MySql`](https://www.nuget.org/packages/ServiceStack.OrmLite.MySql/) NuGet package. This can be used in conjunction with Amazon's RDS service using MariaDB.

::: info
MariaDB is a "binary drop in replacement for MySQL" which is why the `ServiceStack.OrmLite.MySql` NuGet package can be used. For more information, see the [MariaDB documentation](https://mariadb.com/kb/en/mariadb/mariadb-vs-mysql-compatibility/)
:::

To get started, first you will need to create your MariaDB database via the AWS RDS service.

## Creating a MariaDB RDS Instance

1. Login to the [AWS Web console](https://console.aws.amazon.com/console/home).
2. Select [RDS](https://console.aws.amazon.com/rds/home) from the **Services** from the top menu.
![](https://raw.githubusercontent.com/ServiceStack/Assets/master/img/aws/aws-rds-menu.png)
3. Select **Instances** from the **RDS Dashboard** and click **Launch DB Instance**.
![](https://raw.githubusercontent.com/ServiceStack/Assets/master/img/aws/launch-db-dashboard.png)

The above steps will start the RDS Wizard to launch a new DB instance. To setup a new MariaDB instance, follow the wizard selecting the appropriate options for your application. As an example, we can create a `Customers` database for a non-production environment.

- **Select Engine** - Select MariaDB
- **Production?** - Select `No` for multi-instance/production setup
- **Specify DB Details** 
    - Create a `db.t2.micro` instance with default settings
    - Specify **Multi-AZ Deployment** as `No`

![](https://raw.githubusercontent.com/ServiceStack/Assets/master/img/aws/mariadb-default-details.png)

- Specify **DB Instance Identifier**, eg `servicestack-example-customers`.
- Specify **Master Username**, eg `admin`.
- Create and confirm master user password.

- **Configure Advanced Settings** - Leave the suggested settings and specify a database name, eg `customers`. This will be used in your connection string.

::: info
Problems can occur if your default VPC is not setup to DNS Resolution and/or DNS Hostname. Navigate to **Services**, **VPC** and enable these two options on your default VPC
:::

Click **Launch DB Instance** at the *bottom right* to launch your new instance. If all is successful, you should see the following.

![](https://github.com/ServiceStack/Assets/raw/master/img/aws/create-db-success.png)

## Connecting with ServiceStack.OrmLite
Now that you're MariaDB instance is running, connecting with OrmLite will require the `ServiceStack.OrmLite.MySql` NuGet package as well as connection string to your new MariaDB instance.

``` xml
<appSettings>
    <add key="ConnectionString" value="Uid={User};Password={Password};Server={EndpointUrl};Port={EndpointPort};Database=customers" />   
</appSettings>
```

:::copy
`<PackageReference Include="ServiceStack.OrmLite.MySql" Version="8.*" />`
:::

Once this dependency is installed, the `OrmLiteConnectionFactory` can be used with the `MySqlDialect.Provider` can be configured in the AppHost Configure method. For example.

``` csharp
public class AppHost : AppSelfHostBase
{
    public AppHost() : base("AWS MariaDB Customers", typeof(AppHost).Assembly) {}

    public override void Configure(Container container)
    {
        container.Register<IDbConnectionFactory>(c => new OrmLiteConnectionFactory(
            AppSettings.GetString("ConnectionString"), MySqlDialect.Provider));

        using (var db = container.Resolve<IDbConnectionFactory>().Open())
        {
            if (db.CreateTableIfNotExists<Customer>())
            {
                //Add seed data
            }
        }
    }
}

```

Using our connection from a ServiceStack Service, we can use the `Db` property to access our `Customer` table. Eg, Below is an example of a CRUD service using OrmLite.

``` csharp
public class CustomerService : Service
{
    public object Get(GetCustomers request)
    {
        return new GetCustomersResponse { Results = Db.Select<Customer>() };
    }

    public object Get(GetCustomer request)
    {
        return Db.SingleById<Customer>(request.Id);
    }

    public object Post(CreateCustomer request)
    {
        var customer = new Customer { Name = request.Name };
        Db.Save(customer);
        return customer;
    }

    public object Put(UpdateCustomer request)
    {
        var customer = Db.SingleById<Customer>(request.Id);
        if (customer == null)
            throw HttpError.NotFound("Customer '{0}' does not exist".Fmt(request.Id));

        customer.Name = request.Name;
        Db.Update(customer);

        return customer;
    }

    public void Delete(DeleteCustomer request)
    {
        Db.DeleteById<Customer>(request.Id);
    }
}
```

See the [OrmLite GitHub](/ormlite/ormlite-apis) page for more info on working with OrmLite API.

## Getting Started with AWS RDS SQL Server and OrmLite

![](https://github.com/ServiceStack/Assets/raw/master/img/aws/rds-sqlserver-powered-by-aws.png)

ServiceStack.OrmLite library has support for use with a [Microsoft SQL Server](http://www.microsoft.com/en-au/server-cloud/products/sql-server/) database via the [`ServiceStack.OrmLite.SqlServer`](https://www.nuget.org/packages/ServiceStack.OrmLite.SqlServer/) NuGet package. This can be used in conjunction with Amazon's RDS service using SQL Server.

To get started, first you will need to create your SQL Server database via the AWS RDS service.

## Creating a SQL Server RDS Instance

1. Login to the [AWS Web console](https://console.aws.amazon.com/console/home).
2. Select [RDS](https://console.aws.amazon.com/rds/home) from the **Services** from the top menu.
![](https://raw.githubusercontent.com/ServiceStack/Assets/master/img/aws/aws-rds-menu.png)
3. Select **Instances** from the **RDS Dashboard** and click **Launch DB Instance**.
![](https://raw.githubusercontent.com/ServiceStack/Assets/master/img/aws/launch-db-dashboard.png)

The above steps will start the RDS Wizard to launch a new DB instance. To setup a new SQL Server instance, follow the wizard selecting the appropriate options for your application. As an example, we can create a `Customers` database for a non-production environment.

- **Select Engine**
    - Select **SQL Server**
    - Select appropriate SQL Server version, for this example, **SQL Server SE** 
- **Specify DB Details** 
    - Select **License Model** `license-included` 
    - Create a `db.m1.small` instance with default settings by changing the **DB Instance Class**.

![](https://raw.githubusercontent.com/ServiceStack/Assets/master/img/aws/mssql-default-details.png)

- Specify **DB Instance Identifier**, eg `customers`.
- Specify **Master Username**, eg `admin`.
- Create and confirm master user password.

- **Configure Advanced Settings** - Leave the suggested settings which will create your RDS instance with network rule that restricts public access via your current public IP address.

::: info
Problems can occur if your default VPC is not setup to DNS Resolution and/or DNS Hostname. Navigate to **Services**, **VPC** and enable these two options on your default VPC
:::

Click **Launch DB Instance** at the *bottom right* to launch your new instance. If all is successful, you should see the following.

![](https://github.com/ServiceStack/Assets/raw/master/img/aws/create-db-success.png)

## Connecting with ServiceStack.OrmLite
Now that you're SQL Server instance is running, connecting with OrmLite will require the `ServiceStack.OrmLite.SqlServer` NuGet package as well as connection string to your new SQL Server instance.

::: info
If you are connecting to a new instance without a database, you'll need to create a new Database via SQL Management Studio first. For this example the `customers` database was created
:::

``` xml
<appSettings>
    <add key="ConnectionString" value="Data Source={Endpoint},{Port};Initial Catalog=customers;User ID={User};Password={Password}" />   
</appSettings>
```

:::copy
`<PackageReference Include="ServiceStack.SqlServer" Version="8.*" />`
:::

Once this dependency is installed, the `OrmLiteConnectionFactory` can be used with the `SqlServerDialect.Provider` can be configured in the AppHost Configure method. For example.

``` csharp
public class AppHost : AppSelfHostBase
{
    public AppHost() : base("AWS SQL Server Customers", typeof(AppHost).Assembly) {}

    public override void Configure(Container container)
    {
        container.Register<IDbConnectionFactory>(c => new OrmLiteConnectionFactory(
            AppSettings.GetString("ConnectionString"), SqlServerDialect.Provider));

        using (var db = container.Resolve<IDbConnectionFactory>().Open())
        {
            if (db.CreateTableIfNotExists<Customer>())
            {
                //Add seed data
            }
        }
    }
}

```

Using our connection from a ServiceStack Service, we can use the `Db` property to access our `Customer` table. Eg, Below is an example of a CRUD service using OrmLite.

``` csharp
public class CustomerService : Service
{
    public object Get(GetCustomers request)
    {
        return new GetCustomersResponse { Results = Db.Select<Customer>() };
    }

    public object Get(GetCustomer request)
    {
        return Db.SingleById<Customer>(request.Id);
    }

    public object Post(CreateCustomer request)
    {
        var customer = new Customer { Name = request.Name };
        Db.Save(customer);
        return customer;
    }

    public object Put(UpdateCustomer request)
    {
        var customer = Db.SingleById<Customer>(request.Id);
        if (customer == null)
            throw HttpError.NotFound("Customer '{0}' does not exist".Fmt(request.Id));

        customer.Name = request.Name;
        Db.Update(customer);

        return customer;
    }

    public void Delete(DeleteCustomer request)
    {
        Db.DeleteById<Customer>(request.Id);
    }
}
```

See the [OrmLite GitHub](/ormlite/ormlite-apis) page for more info on working with OrmLite API.

## Getting started with AWS ElastiCache Redis and ServiceStack

![](https://github.com/ServiceStack/Assets/raw/master/img/aws/elasticache-redis-powered-by-aws.png)

Amazon's 'ElastiCache' allows a simple way to create and manage cache instances that can be simply incorporated into your ServiceStack application stack using the ServiceStack Redis client, `ServiceStack.Redis`. 

#### Creating an ElastiCache Cluster

1. Login to the [AWS Web console](https://console.aws.amazon.com/console/home).
2. Select [ElastiCache](https://console.aws.amazon.com/elasticache/home) from the **Services** from the top menu.
![](https://raw.githubusercontent.com/ServiceStack/Assets/master/img/aws/aws-services-menu-elasticcache.png)
3. Select **Get Started Now** or **ElasticCache Dashboard** and **Launch Cache Cluster**
4. Select **Redis** for the cluster engine.

You can run your cache as a single Redis node or add multiple nodes for additional redundency. In this example, we will be using 3 nodes. One as a primary (or master) node and 2 read only replicas (or slaves). 

![](https://github.com/ServiceStack/Assets/raw/master/img/aws/elasticcache-redis-config.png)

::: info
To use the smaller instances like the `cache.t2.micro`, **Multi-AZ** must be disabled
:::

So you're EC2 instance can access your Redis nodes, ensure you select a **VPC Security Group** that exposes the default port `6379`.

![](https://github.com/ServiceStack/Assets/raw/master/img/aws/elasticcache-redis-adv.png)

::: info
If you haven't already setup a security group exposing this port, you'll need to create one by [managing your VPC security groups](https://console.aws.amazon.com/vpc/home#securityGroups:)
:::

To finish, reviewed your settings and click **Launch Replication Group**.

## Enable Caching with ServiceStack.Redis

Now you're your Redis nodes are ready, your AppHost can be configured to use them when deployed. AWS **does not allow external access** to ElastiCache servers, so they can only be used when your ServiceStack application is deployed.

First, you'll need to install `ServiceStack.Redis` NuGet package if your application doesn't already use it.

:::copy
`<PackageReference Include="ServiceStack.Redis" Version="8.*" />`
:::

In this example, we are going to use a `PooledRedisClientManager` for our `IRedisClientsManager`. This will be responsible for creating `ICacheClient`s that our `Service`s will use to connect to the ElastiCache nodes. We will need to provide our `PooledRedisClientManager` with the nodes we have create. For example, as shown above, we created a cluster of **1 Primary** (master) and **2 Read Replicas** (slaves), these endpoint URLs can be accessed from the ElastiCache **Dashboard**.

![](https://github.com/ServiceStack/Assets/raw/master/img/aws/elasticcache-redis-nodes.png)

Below is a simple example of a configured self hosting AppHost that uses ElastiCache for caching when deployed and an in memory caching when developing locally.

``` csharp
public class AppHost : AppSelfHostBase
{
    public AppHost() : base("AWS Redis ElastiCache Example", typeof(MyServices).Assembly) { }

    public override void Configure(Container container)
    {
		//Your DB initialization
		...

        // AWS ElastiCache servers are NOT accessible from outside AWS
        // Use MemoryCacheClient locally
        if (AppSettings.GetString("Environment") == "Production")
        {
            container.Register<IRedisClientsManager>(c =>
                new PooledRedisClientManager(
                    // Primary node from AWS (master)
                    AwsElastiCacheConfig.MasterNodes,
                    // Read replica nodes from AWS (slaves)
                    AwsElastiCacheConfig.SlaveNodes));

            container.Register<ICacheClient>(c =>
                container.Resolve<IRedisClientsManager>().GetCacheClient());
        }
        else
        {
            container.Register<ICacheClient>(new MemoryCacheClient());
        }
    }
}

```

With configuration provided in your application config.
``` xml
<appSettings>
  <add key="Environment" value="Production"/>
  <add key="MasterNodes" value="{YourAWSPrimaryNodeAddress}"/>
  <add key="SlaveNodes" value="{Your1stAWSReadReplicaNodeAddress},{AWSReadReplicaNodeAddress}"/>
</appSettings>
```

Now that your caching is setup and connecting, you can cache your web servie responses easily by returning `Request.ToOptimizedResultUsingCache` from within a ServiceStack `Service`. For example, returning a full customers details might be an expensive database query. We can cache the result in the ElastiCache cluster for a faster response and invalidate the cache when the details are updated.

``` csharp
public class CustomerService : Service
{
    private static string CacheKey = "customer_details_{0}";

    public object Get(GetCustomer request)
    {
        return this.Request.ToOptimizedResultUsingCache(this.Cache,
            CacheKey.Fmt(request.Id), () => {
                Thread.Sleep(500); //Long request
                return new GetCustomerResponse
                {
                    Result = this.Db.LoadSingleById<Customer>(request.Id)
                };
            });
    }

    public object Put(UpdateCustomer request)
    {
        var customer = this.Db.LoadSingleById<Customer>(request.Id);
        customer = customer.PopulateWith(request.ConvertTo<Customer>());
        this.Db.Update(customer);
        //Invalidate customer details cache
        this.Cache.ClearCaches(CacheKey.Fmt(request.Id));
        return new UpdateCustomerResponse()
        {
            Result = customer
        };
    }
}
```

::: info
As this example uses the `Cache` property from the `Service` in a distributed cache environment, `Cache.Get<T>` values are coming from the read replica (slave) instances which will take time to replicate from a previous `Cache.Set<T>` call. To gaurantee a value is immediately available, reusing the same instance can be done by handling the creating from the `IRedisClientsManager` from within your `Service` method
:::

``` csharp
using var cache = this.RedisClientManager.GetClient();
//Your Cache Client code
```

## Getting started with AWS ElastiCache and ServiceStack
### Memcached

![](https://github.com/ServiceStack/Assets/raw/master/img/aws/elasticache-memcached-powered-by-aws.png)

Amazon's 'ElastiCache' allows a simple way to create and manage Memcached instances that can be simply incorporated into your ServiceStack application stack using the ServiceStack NuGet package, `ServiceStack.Caching.Memcached`. 

#### Creating an ElastiCache Cluster

1. Login to the [AWS Web console](https://console.aws.amazon.com/console/home).
2. Select [ElastiCache](https://console.aws.amazon.com/elasticache/home) from the **Services** from the top menu.
![](https://raw.githubusercontent.com/ServiceStack/Assets/master/img/aws/aws-services-menu-elasticcache.png)
3. Select **Get Started Now** or **ElasticCache Dashboard** and **Launch Cache Cluster**
4. Select **Memcached** for the cluster engine.

ElastiCache setup allows you to specify how many nodes you want in your cache cluster. In this example, we will be using 3.

![](https://github.com/ServiceStack/Assets/raw/master/img/aws/elasticcache-memcached-config.png)

So you're EC2 instance can access your Memcached cluster, ensure you select a **VPC Security Group** that exposes the default port `11211`. 

![](https://github.com/ServiceStack/Assets/raw/master/img/aws/elasticcache-memcached-adv.png)

::: info
If you haven't already setup a security group exposing this port, you'll need to create one by [managing your VPC security groups](https://console.aws.amazon.com/vpc/home#securityGroups:)
:::

To finish, reviewed your settings and click **Launch Cache Cluster**.

## Enable Caching in your ServiceStack application
Now you're your Memcached cluster is ready, your AppHost can be configured to use it when deployed. AWS **does not allow external access** to ElastiCache servers, so they can only be used when your ServiceStack application is deployed.

First, you'll need to install `ServiceStack.Caching.Memcached`:

:::copy
`<PackageReference Include="ServiceStack.Caching.Memcached" Version="8.*" />`
:::

To access the Memcached nodes from your `Service`s, you will need to register a `MemcachedClientCache` as a `ICacheClient` with the IoC container. This client has to initialized with each of the node endpoints provided by AWS. From the [ElastiCache Dashboard](https://console.aws.amazon.com/elasticache/home), click on the `nodes` on your cluster to see the node endpoint URLs. 

![Memcached cluster view from Dashboard](https://github.com/ServiceStack/Assets/raw/master/img/aws/elasticcache-memcached-nodes.png)

This will show all the nodes in the cluster. For example.

![Listed node endpoints](https://github.com/ServiceStack/Assets/raw/master/img/aws/elasticcache-memcached-node-urls.png)

Below is a simple example of a configured self hosting AppHost that uses ElastiCache for caching when deployed and an in memory caching when developing locally.

``` csharp
public class AppHost : AppSelfHostBase
{
    public AppHost() : base("AWS Memcached ElastiCache Example", typeof(MyServices).Assembly) {}

    public override void Configure(Container container)
    {
        //Your DB initialization
		...

        // AWS ElastiCache servers are NOT accessible from outside AWS
        // Use MemoryCacheClient locally
        if (AppSettings.GetString("Environment") == "Production")
        {
            container.Register<ICacheClient>(c => new MemcachedClientCache(
                AwsElastiCacheConfig.MemcachedNodes));
        }
        else
        {
            container.Register<ICacheClient>(new MemoryCacheClient());
        }
    }
}

```


With configuration provided in your application config.
``` xml
<appSettings>
  <add key="Environment" value="Production"/>
  <add key="MemcachedNodes" value="{MemcachedNodeAddress1},{MemcachedNodeAddress2}"/>
</appSettings>
```

Now that your caching is setup and connecting, you can cache your web service responses easily by returning `Request.ToOptimizedResultUsingCache` from within a ServiceStack `Service`. For example, returning a full customers details might be an expensive database query. We can cache the result in the ElastiCache cluster for a faster response and invalidate the cache when the details are updated.

``` csharp
public class CustomerService : Service
{
    private static string CacheKey = "customer_details_{0}";

    public object Get(GetCustomer request)
    {
        return this.Request.ToOptimizedResultUsingCache(this.Cache,
            CacheKey.Fmt(request.Id),
            () =>
            {
                Thread.Sleep(500); //Long request
                return new GetCustomerResponse
                {
                    Result = this.Db.LoadSingleById<Customer>(request.Id)
                };
            });
    }

    public object Put(UpdateCustomer request)
    {
        var customer = this.Db.LoadSingleById<Customer>(request.Id);
        customer = customer.PopulateWith(request.ConvertTo<Customer>());
        this.Db.Update(customer);
        //Invalidate customer details cache
        this.Cache.ClearCaches(CacheKey.Fmt(request.Id));
        return new UpdateCustomerResponse()
        {
            Result = customer
        };
    }
}
```


# Azure Resources
Source: https://docs.servicestack.net/azure

## ServiceStack.Azure

ServiceStack.Azure package provides support to Azure ServiceBus and Azure Blob Storage. All features are incapsulated in single ServiceStack.Azure package. To install package run from NuGet

:::copy
`<PackageReference Include="ServiceStack.Azure" Version="8.*" />`
:::

ServiceStack.Azure includes implementation of the following ServiceStack providers:

- [ServiceBusMqServer](#ServiceBusMqServer) - [MQ Server](/messaging) for invoking ServiceStack Services via Azure ServiceBus
- [AzureBlobVirtualFiles](#virtual-filesystem-backed-by-azure-blob-storage) - Virtual file system based on Azure Blob Storage
- [AzureTableCacheClient](#caching-support-with-azure-table-storage) - Cache client over Azure Table Storage

### ServiceBusMqServer

The code to configure and start an ServiceBus MQ Server is similar to other MQ Servers:

```csharp
container.Register<IMessageService>(c => new ServiceBusMqServer(ConnectionString));

var mqServer = container.Resolve<IMessageService>();
mqServer.RegisterHandler<ServiceDto>(ExecuteMessage);

AfterInitCallbacks.Add(appHost => mqServer.Start());
```

Where ConnectionString is connection string to Service Bus, how to obtain it from Azure Portal you can find in [Get Started with Service Bus queues](https://docs.microsoft.com/en-us/azure/service-bus-messaging/service-bus-dotnet-get-started-with-queues) article

When an MQ Server is registered, ServiceStack automatically publishes Requests accepted on the "One Way" pre-defined route to the registered MQ broker. The message is later picked up and executed by a Message Handler on a background Thread.

## Virtual FileSystem backed by Azure Blob Storage

You can use an Azure Blob Storage Container to serve website content with the **AzureBlobVirtualFiles**.

```csharp
public class AppHost : AppHostBase
{
    public override void Configure(Container container)
    {
        //All Razor Views, Markdown Content, imgs, js, css, etc are served from an Azure Blob Storage container

        //Use connection string to Azure Storage Emulator. For real application you should use connection string
        //to your Azure Storage account
        var azureBlobConnectionString = "UseDevelopmentStorage=true";
        //Azure container which hold your files. If it does not exist it will be automatically created.
        var containerName = "myazurecontainer";

        VirtualFiles = new AzureBlobVirtualFiles(connectionString, containerName);
        AddVirtualFileSources.Add(VirtualFiles);
    }
}
```

## Caching support with Azure Table Storage

The AzureTableCacheClient implements [ICacheClientExteded](https://github.com/ServiceStack/ServiceStack/blob/master/src/ServiceStack.Interfaces/Caching/ICacheClientExtended.cs) and [IRemoveByPattern](https://github.com/ServiceStack/ServiceStack/blob/master/src/ServiceStack.Interfaces/Caching/IRemoveByPattern.cs) using Azure Table Storage. 

```csharp
public class AppHost : AppHostBase
{
    public override void Configure(Container container)
    {
        string cacheConnStr = "UseDevelopmentStorage=true;";
        container.Register<ICacheClient>(new AzureTableCacheClient(cacheConnStr));
    }
}
```

### Deploying to Azure

See [Rockwind.Azure](https://github.com/sharp-apps/rockwind-azure) for a working configuration and step-by-step guide to deploy .NET Core Web Apps to Azure using Docker.

# Community Resources

  - [Using the Azure Cache With ServiceStack](http://blog.emmanuelnelson.com/post/33303196083/using-the-azure-cache-with-service-stack) by [@emmanuelnelson](http://emmanuelnelson.com/about-me)
  - [Securing ServiceStack using Azure Authentication Library and WPF Client](http://dhickey-ie-archive.azurewebsites.net/post/2012/12/12/Securing-ServiceStack-using-Azure-Authentication-Library.aspx) by [@randompunter](http://twitter.com/randompunter)
  - [ServiceStack.Azure](https://github.com/ServiceStack/ServiceStack.Azure), supporting VirtualPathProvider backed by Azure Blob Storage, and ICacheProvider backed by Azure Table Storage


# ServiceStack.Stripe
Source: https://docs.servicestack.net/stripe

The [ServiceStack.Stripe](https://github.com/ServiceStack/ServiceStack/tree/main/ServiceStack.Stripe) library contains a typed .NET client gateway for accessing [Stripe's REST API](https://stripe.com/docs/api/), updated to the latest **2018-02-28** Stripe API Version available which is used by [servicestack.net](http://servicestack.net/) to process merchant payments and recurring subscriptions online.

This library only maintains the core Stripe REST APIs for processing payments, subscriptions and managing Customer account & card information.
We welcome PR's with support of missing APIs which typically only requires adding annotated C# POCO DTOs as seen below.

## Features

  - **Small**, typed, message-based API uses only clean DTO's and fits in a single [StripeGateway.cs](https://github.com/ServiceStack/ServiceStack/blob/main/ServiceStack.Stripe/src/ServiceStack.Stripe/StripeGateway.cs)
  - **Async** every Stripe Service can be called via either Sync or Async methods
  - **Portable** profile available supporting .NET 4.5, Xamarin.iOS, Xamarin.Android and Windows Store clients
  - **Open-ended**, can use custom declarative DTO's defined in your own app to access new APIs  
  - **Testable**, implements the mockable [IRestGateway](https://github.com/ServiceStack/ServiceStack/blob/master/src/ServiceStack.Interfaces/IRestGateway.cs), can [return test data](https://github.com/ServiceStack/ServiceStack/blob/master/tests/ServiceStack.Common.Tests/MockRestGatewayTests.cs) with a generic [MockRestGateway](https://github.com/ServiceStack/ServiceStack/blob/master/src/ServiceStack/Testing/MockRestGateway.cs)
  - See [Stripe.Tests](https://github.com/ServiceStack/ServiceStack/tree/main/ServiceStack.Stripe/tests/ServiceStack.Stripe.Tests/Stripe.Tests) for more example usages.

## Install ServiceStack.Stripe

Install from NuGet with:

:::copy
`<PackageReference Include="ServiceStack.Stripe" Version="8.*" />`
:::

### ASP .NET Core on .NET Framework

To use this library in [ASP.NET Core Apps running on the .NET Framework](/templates/corefx), install the **.NET Standard 2.0** only NuGet package instead:

:::copy
`<PackageReference Include="ServiceStack.Stripe.Core" Version="8.*" />`
:::

## Usage

Requires a [registered Stripe API Key](https://manage.stripe.com/register), e.g:

```csharp
var gateway = new StripeGateway("sk_test_23KlmQohLKD4dfmAvxYESZ2z");
```

Request DTO's are just clean POCO's with `[Route]` attributes defined, e.g:

```csharp
[Route("/customers/{Id}")]
public class GetStripeCustomer : IGet, IReturn<StripeCustomer>
{
    public string Id { get; set; }
}
```

The `IGet` interface marker indicates which HTTP Method Stripe expects, whilst `IReturn<StripeCustomer>` indicates what Stripe returns. 
The gateway uses this type information to provide its typed API, e.g:

```csharp
StripeCustomer customer = gateway.Get(new GetStripeCustomer { Id = customerId });
```

#### Async

```csharp
StripeCustomer customer = await gateway.GetAsync(new GetStripeCustomer { Id = customerId });
```

If you prefer, you can use the same `gateway.Send()` generic method for **all** messages as it is able to make use of 
the `IVerb` interface marker to control which HTTP method is used, e.g.

```csharp
StripeCustomer customer = gateway.Send(new GetStripeCustomer { Id = customerId });
```

#### Async

```csharp
StripeCustomer customer = await gateway.SendAsync(new GetStripeCustomer { Id = customerId });
```

Both of these calls translates to the [Retrieving a Customer](https://stripe.com/docs/api/curl#retrieve_customer) HTTP Request, Example in curl:

:::sh
curl https://api.stripe.com/v1/customers/cus_3552jPRgtQeRcK -u yDOr26HsxyhpuRB3qbG07qfCmDhqutnA:
:::

### Open-Ended, Declarative Message-based APIs

The `StripeGateway` benefits from an **Open Ended** message-based API where you're also able to use own Request DTO's to call new Stripe Services that StripeGateway has no knowledge about. E.g. The only custom code required to implement the `ChargeStripeCustomer` is this single, clean, declarative Request DTO:

```csharp
[Route("/charges")]
public class ChargeStripeCustomer : IPost, IReturn<StripeCharge>
{
    public int Amount { get; set; }
    public string Currency { get; set; }
    public string Customer { get; set; }
    public string Card { get; set; }
    public string Description { get; set; }
    public bool? Capture { get; set; }
    public int? ApplicationFee { get; set; }
}
```  

Which contains all the information needed to call the Stripe Service including the `/charges` relative url, using the **POST** HTTP method and the typed `StripeCharge` DTO it returns. To charge a Customer the Request DTO can either use the explicit `Post/PostAsync` or universal `Send/SendAsync` StripeGateway methods. 

## Documentation

These API examples follows [Stripe's API Documentation](https://stripe.com/docs/api/).

## [Charges](https://stripe.com/docs/api/curl#charges)

### Creating a new charge (charging a credit card)

```csharp
var charge = gateway.Post(new ChargeStripeCustomer
{
    Amount = 100,
    Customer = customer.Id,
    Currency = "usd",
    Description = "Test Charge Customer",
});
```

#### Async

```csharp
var charge = await gateway.PostAsync(new ChargeStripeCustomer
{
    Amount = 100,
    Customer = customer.Id,
    Currency = "usd",
    Description = "Test Charge Customer",
});
```

### Retrieving a Charge


```csharp
var charge = gateway.Get(new GetStripeCharge { ChargeId = charge.Id });
```

### Updating a Charge


```csharp
var charge = gateway.Post(new UpdateStripeCharge 
{
    ChargeId = charge.Id,
    Description = "Updated Charge Description"
});
```

### Refunding a Charge


```csharp
var refundCharge = gateway.Post(new RefundStripeCharge
{
    ChargeId = charge.Id,
});
```

### Capture a charge


```csharp
var charge = gateway.Post(new ChargeStripeCustomer
{
    Amount = 100,
    Customer = customer.Id,
    Currency = "usd",
    Description = "Test Charge Customer",
    Capture = false,  //Don't capture the charge immediately
});

//Can capture charge later with an explicit call
var captureCharge = gateway.Post(new CaptureStripeCharge
{
    ChargeId = charge.Id,
});
```

### List all Charges


```csharp
var charges = gateway.Get(new GetStripeCharges());
```

List all customer charges

```csharp
var charges = gateway.Get(new GetStripeCharges
{
    Customer = customer.Id,
});
```


## [Customers](https://stripe.com/docs/api/curl#customers)

### Creating a New Customer

```csharp
var customer = gateway.Post(new CreateStripeCustomer
{
    AccountBalance = 10000,
    Card = new StripeCard
    {
        Name = "Test Card",
        Number = "4242424242424242",
        Cvc = "123",
        ExpMonth = 1,
        ExpYear = 2015,
        AddressLine1 = "1 Address Road",
        AddressLine2 = "12345",
        AddressZip = "City",
        AddressState = "NY",
        AddressCountry = "US",
    },
    Description = "Description",
    Email = "test@email.com",
});
```

### Creating a New Customer with a Card Token

```csharp
 var cardToken = gateway.Post(new CreateStripeToken {
    Card = new StripeCard
    {
        Name = "Test Card",
        Number = "4242424242424242",
        Cvc = "123",
        ExpMonth = 1,
        ExpYear = 2015,
        AddressLine1 = "1 Address Road",
        AddressLine2 = "12345",
        AddressZip = "City",
        AddressState = "NY",
        AddressCountry = "US",
    },
});

var customer = gateway.Post(new CreateStripeCustomerWithToken
{
    AccountBalance = 10000,
    Card = cardToken.Id,
    Description = "Description",
    Email = "test@email.com",
});
```

### Retrieving a Customer


```csharp
var customer = gateway.Get(new GetStripeCustomer { Id = customerId });
```

### Updating a Customer


```csharp
var updatedCustomer = gateway.Post(new UpdateStripeCustomer
{
    Id = customer.Id,
    Card = new StripeCard
    {
        Id = customer.Cards.Data[0].Id,
        Name = "Updated Test Card",
        Number = "4242424242424242",
        Cvc = "123",
        ExpMonth = 1,
        ExpYear = 2015,
        AddressLine1 = "1 Address Road",
        AddressLine2 = "12345",
        AddressZip = "City",
        AddressState = "NY",
        AddressCountry = "US",
    },
    AccountBalance = 20000,
    Description = "Updated Description",
    Email = "updated@email.com",
});
```

### Deleting a Customer


```csharp
var deletedRef = gateway.Delete(new DeleteStripeCustomer { Id = customer.Id });
```

### List all Customers


```csharp
var customers = gateway.Get(new GetStripeCustomers());
```

## [Cards](https://stripe.com/docs/api/curl#cards)

### Creating a new card


```csharp
var card = gateway.Post(new CreateStripeCard
{
    CustomerId = customer.Id,
    Card = new StripeCard
    {
        Name = "Test Card 2",
        Number = "5555555555554444",
        Cvc = "456",
        ExpMonth = 1,
        ExpYear = 2016,
        AddressLine1 = "1 Address Road",
        AddressLine2 = "12345",
        AddressZip = "City",
        AddressState = "NY",
        AddressCountry = "US",
    },
});
```

### Retrieving a customer's card


```csharp
var card = gateway.Get(new GetStripeCard
{
    CustomerId = customer.Id,
    CardId = card.Id,
});
```

### Updating a card


```csharp
var card = gateway.Post(new UpdateStripeCard
{
    CustomerId = customer.Id,
    CardId = customer.Cards.Data[0].Id,

    Name = "Test Card Updated",

    AddressLine1 = "1 Address Updated",
    AddressLine2 = "45321",
    AddressZip = "City",
    AddressState = "NY",
    AddressCountry = "US",

    ExpMonth = 2,
    ExpYear = 2030,
});
```

### Deleting cards


```csharp
var deletedRef = gateway.Delete(new DeleteStripeCard
{
    CustomerId = customer.Id,
    CardId = customer.Cards.Data[0].Id,
});
```

### Listing cards


```csharp
var cards = gateway.Get(new GetStripeCustomerCards { CustomerId = customer.Id });
```


## [Subscriptions](https://stripe.com/docs/api/curl#subscriptions)

### Updating the Customer's Active Subscription

```csharp
var subscription = gateway.Post(new SubscribeStripeCustomer
{
    CustomerId = customer.Id,
    Plan = plan.Id,
    Coupon = coupon.Id,
    Quantity = 1,
});
```

### Canceling a Customer's Subscription

```csharp
var cancelled = gateway.Delete(new CancelStripeSubscription
{
    CustomerId = customer.Id,
    AtPeriodEnd = false,
});
```


## [Plans](https://stripe.com/docs/api/curl#plans)

### Creating plans


```csharp
var plan = gateway.Post(new CreateStripePlan
{
    Id = "TEST-PLAN-01",
    Amount = 10000,
    Currency = "usd",
    Name = "Test Plan",
    Interval = StripePlanInterval.month,
    IntervalCount = 1,
});
```

### Retrieving a Plan


```csharp
var plan = gateway.Get(new GetStripePlan { Id = plan.Id });

```

### Updating a plan


```csharp
var updatedPlan = gateway.Post(new UpdateStripePlan
{
    Id = "TEST-PLAN-01",
    Name = "NEW PLAN UPDATED!",
});
```

### Deleting a plan


```csharp
var gateway.Delete(new DeleteStripePlan { Id = plan.Id });
```

### List all Plans


```csharp
var plans = gateway.Get(new GetStripePlans { Count = 20 });
```


## [Coupons](https://stripe.com/docs/api/curl#coupons)

### Creating coupons


```csharp
var coupon = gateway.Post(new CreateStripeCoupon
{
    Id = "TEST-COUPON-01",
    Duration = StripeCouponDuration.repeating,
    PercentOff = 20,
    Currency = "usd",
    DurationInMonths = 2,
    RedeemBy = DateTime.UtcNow.AddYears(1),
    MaxRedemptions = 10,
});
```

### Retrieving a Coupon


```csharp
var coupon = gateway.Get(new GetStripeCoupon { Id = coupon.Id });
```

### Deleting a coupon


```csharp
var deletedRef = gateway.Delete(new DeleteStripeCoupon { Id = plan.Id });
```

### List all Coupons


```csharp
var coupons = gateway.Get(new GetStripeCoupons { Count = 20 });
```


## [Discounts](https://stripe.com/docs/api/curl#discounts)

### Deleting a Discount


```csharp
var deletedRef = gateway.Delete(new DeleteStripeDiscount { CustomerId = customer.Id });
```


## [Invoices](https://stripe.com/docs/api/curl#invoices)

### Retrieving an Invoice


```csharp
var invoice = gateway.Get(new GetStripeInvoice { Id = invoice.Id });
```

### Creating an invoice


```csharp
var stripeInvoice = gateway.Post(new CreateStripeInvoice
{
    Customer = customer.Id
});
```

### Paying an invoice


```csharp
var paidInvoice = gateway.Post(new PayStripeInvoice
{
    Id = invoice.Id
});
```

### Retrieving a List of Invoices


```csharp
var invoices = gateway.Get(new GetStripeInvoices { Count = 20 });
```

Get a list of customer invoices


```csharp
var invoices = gateway.Get(new GetStripeInvoices 
{ 
    Customer = customer.Id
});
```

### Retrieving a Customer's Upcoming Invoice


```csharp
var upcomingInvoice = gateway.Get(new GetUpcomingStripeInvoice
{
    Customer = customer.Id,
});
```


# Install Redis on Windows
Source: https://docs.servicestack.net/install-redis-windows

The [ServiceStack/redis-windows](https://github.com/ServiceStack/redis-windows) project contains the binary releases of MS Open Tech redis port of windows as well as a vagrant configuration for redis letting you run the native version of Redis in a Virtual Box VM.

Whilst it's recommended to use [Redis](https://redis.io) on Linux in production, it is often useful for developers on Windows platforms to have their own local version of redis running to develop with. 

The 3 most popular ways of running redis on windows is to use the binary releases of [Microsoft's native port of redis](https://github.com/msopentech/redis), but as this is an unofficial port it always lags behind the latest official development of redis on Linux/OSX. 

Thanks to [Vagrant](https://www.vagrantup.com/) you can choose to run the latest linux version inside a Virtual Box Linux VM where you'll be able to run the official native version of redis.

Or from **Windows 10** you can install [Bash on Ubuntu on Windows](https://msdn.microsoft.com/en-us/commandline/wsl/about) which will let you run the official version of Redis on Ubuntu on Windows :) This is our preferred approach as it lets you run native Ubuntu binaries on Windows more efficiently than a VM of Linux.

## Option 1) Install Redis on Ubuntu on Windows

#### [Install Windows Subsystem for Linux (WSL)](https://learn.microsoft.com/en-us/windows/wsl/install)

From Command Line:

:::sh
wsl --install
:::

From GUI:

 1) From Start, search for **Turn Windows features on or off** (type `turn`)
 2) Select **Windows Subsystem for Linux**

<div class="my-8 flex justify-center">
  <a class="max-w-xl" href="https://learn.microsoft.com/en-us/windows/wsl/install"><img src="/img/pages/redis/install-wsl.png"></a>
</div>

Once installed you can run bash on Ubuntu by typing **bash** from a Windows Command Prompt, then you can install recent stable versions of Redis from the official `packages.redis.io` APT repository with:

```bash
curl -fsSL https://packages.redis.io/gpg | sudo gpg --dearmor -o /usr/share/keyrings/redis-archive-keyring.gpg

echo "deb [signed-by=/usr/share/keyrings/redis-archive-keyring.gpg] https://packages.redis.io/deb $(lsb_release -cs) main" | sudo tee /etc/apt/sources.list.d/redis.list

sudo apt-get update
sudo apt-get install redis
```

After install, start the Redis server with:

:::sh
sudo service redis-server start
:::

Then test that it's running with:

```bash
$ redis-cli
$ 127.0.0.1:6379> SET foo bar
OK
$ 127.0.0.1:6379> GET foo
"bar"
```

### Install latest from source

To install the latest version of Redis we first need to install some prerequisites:

```bash
$ sudo apt-get update
$ sudo apt-get install make
$ sudo apt-get install gcc
```

Then follow the [official installation guide](https://redis.io/topics/quickstart) 
to download, build and install the latest stable version. **NOTE:** Installing 
the binaries using `make install` will not work. You need to copy them manually 
to `/usr/bin` (just like described in the guide, except that they use 
`/usr/local/bin` - which is the problem).

You'll then be able to launch redis with:

:::sh
redis-server --daemonize yes
:::

Which will run redis in the background freeing your shell so you can play with it using the redis client:

```bash
$ redis-cli
$ 127.0.0.1:6379> SET foo bar
OK
$ 127.0.0.1:6379> GET foo
"bar"
```

Which you can connect to from within bash or from your Windows desktop using the [redis-cli native Windows binary from MSOpenTech](#option-3-running-microsofts-native-port-of-redis).

## Option 2) Running the latest version of Redis with Vagrant

1. [Install Vagrant on Windows](https://docs.vagrantup.com/v2/getting-started/)

2. Download the [vagrant-redis.zip](https://raw.github.com/ServiceStack/redis-windows/master/downloads/vagrant-redis.zip) vagrant configuration

:::sh
wget https://raw.github.com/ServiceStack/redis-windows/master/downloads/vagrant-redis.zip
:::

3. Extract `vagrant-redis.zip` in any folder, e.g. in `c:\vagrant-redis`

4. Launch the Virtual Box VM with `vagrant up`

```bash
$ cd c:\vagrant-redis
$ vagrant up
```

This will launch a new Ubuntu VM instance inside Virtual Box that will automatically install and start the latest stable version of redis.

## Option 3) Running Microsoft's native port of Redis

These 64-bit binary releases are created by building the [Microsoft's native port of redis](https://github.com/msopentech/redis) which have also been published on [NuGet](https://www.nuget.org/packages/redis-64), but as it's more convenient we provide a zip of the 64-bit binaries here.

#### MS Open Announcements

  - [MSOpenTech Redis on Windows 3.0 Release Notes](https://raw.githubusercontent.com/MSOpenTech/redis/3.0/Redis%20on%20Windows%20Release%20Notes.md)
  - [MSOpenTech Redis on Windows 2.8 Release Notes](https://raw.githubusercontent.com/MSOpenTech/redis/2.8/Redis%20on%20Windows%20Release%20Notes.md)
  - [MSOpenTech's Redis on Windows](https://github.com/ServiceStack/redis-windows/blob/master/docs/msopentech-redis-on-windows.md)
  - [Updates Released for Redis on Windows (2.8.4)](https://msopentech.com/blog/2014/03/24/updates-released-redis-windows/)

### Current Version: 3.0.503 (June 28, 2016)

1. Download the [redis-latest.zip](https://github.com/ServiceStack/redis-windows/raw/master/downloads/redis-latest.zip) native 64bit Windows port of redis

:::sh
wget https://github.com/ServiceStack/redis-windows/raw/master/downloads/redis-latest.zip
:::

2. Extract `redis64-latest.zip` in any folder, e.g. in `c:\redis`

3. Run the `redis-server.exe` using the local configuration

```bash
$ cd c:\redis
$ redis-server.exe redis.windows.conf
```

4. Run `redis-cli.exe` to connect to your redis instance

```bash
$ cd c:\redis
$ redis-cli.exe
```

5. Start playing with redis :)

```bash
redis 127.0.0.1:6379> SET foo bar
OK
redis 127.0.0.1:6379> KEYS *
1) "foo"
redis 127.0.0.1:6379> GET foo
"bar"
redis 127.0.0.1:6379>
```

The MSOpenTech of Redis adds some useful extensions for better integration with Windows:

#### Running Redis as a Service

If you installed Redis using the MSI package, then Redis was already installed as a Windows service. Nothing further to do. 
If you would like to change its settings, you can update the redis.windows-service.conf file and then restart the Redis 
service (Run -> services.msc -> Redis -> Restart). 

During installation of the MSI you can either use the installer’s user interface to update the port that Redis listens to and the firewall exception or run it silently without a UI. The following examples show how to install from the command line:

**default install (port 6379 and firewall exception ON):**

:::sh
msiexec /i Redis-Windows-x64.msi 
:::

**set port and turn OFF firewall exception:**

:::sh
msiexec /i Redis-Windows-x64.msi PORT=1234 ADD_FIREWALL_RULE=""
:::

**set port and turn ON firewall exception:**

:::sh
msiexec /i Redis-Windows-x64.msi PORT=1234 ADD_FIREWALL_RULE =1
:::

**install with no user interface:**

:::sh
msiexec /quiet /i Redis-Windows-x64.msi
:::
    
If you did not install Redis using the MSI package, then you still run Redis as a Windows service by following these instructions:

In order to better integrate with the Windows Services model, new command line arguments have been introduced to Redis. 
These service arguments require an elevated user context in order to connect to the service control manager. 
If these commands are invoked from a non-elevated context, Redis will attempt to create an elevated context in which to execute these commands. 
This will cause a User Account Control dialog to be displayed by Windows and may require Administrative user credentials in order to proceed.

#### Installing the Service

```
--service-install
```

This must be the first argument on the redis-server command line. Arguments after this are passed in the order they occur to Redis when the service is launched. 
The service will be configured as Autostart and will be launched as "NT AUTHORITY\NetworkService". Upon successful installation, a success message will be displayed and Redis will exit.

This command does not start the service.

For instance:

:::sh
redis-server --service-install redis.windows.conf --loglevel verbose
:::

#### Uninstalling the Service

```
--service-uninstall
```

This will remove the Redis service configuration information from the registry. Upon successful uninstallation, a success message will be displayed and Redis will exit.
This does command not to stop the service.  

For instance:

:::sh
redis-server --service-uninstall
:::

#### Starting the Service

```
--service-start
```

This will start the Redis service. Upon successful startup, a success message will be displayed and Redis service will be started.

For instance:  

:::sh
redis-server --service-start
:::

#### Stopping the Service

```
--service-stop
```

This will stop the Redis service. Upon successful termination, a success message will be displayed and Redis will exit.

For instance:

:::sh
redis-server --service-stop
:::

#### Naming the Service

```
--service-name name
```

This optional argument may be used with any of the preceding commands to set the name of the installed service. This argument should follow the service-install, service-start, service-stop or service-uninstall commands, and precede any arguments to be passed to Redis via the service-install command. 
The following would install and start three separate instances of Redis as a service:

```bash
$ redis-server --service-install –service-name redisService1 –port 10001
$ redis-server --service-start –service-name redisService1
$ redis-server --service-install –service-name redisService2 –port 10002
$ redis-server --service-start –service-name redisService2
$ redis-server --service-install –service-name redisService3 –port 10003
$ redis-server --service-start –service-name redisService3
```

## Redis Admin Desktop App

::include redis-admin.md::

## [Redis Vue](https://sharpscript.net/sharp-apps/redis#redis-vue)

Redis Vue is a simple, lightweight, versatile Redis Admin UI developed using [Vue](https://vuejs.org/v2/guide/) and ServiceStack [Sharp Apps](https://sharpscript.net/sharp-apps/). It supports Redis's core **Strings**, **Lists**, **Sets**, **Sorted Sets** and **Hash** data structures and custom Redis commands with its entire functionality contained in a single [/index.html](https://gist.github.com/gistlyn/6de7993333b457445793f51f6f520ea8#file-index-html) using the dynamic [#Script](https://sharpscript.net) language, making it easy to customize and further enhance.

![](https://sharpscript.net/assets/img/screenshots/redis.png)


After [app](/netcore-windows-desktop) install, open the Redis Vue Desktop App from your browser at:

<h3 class="text-3xl text-center"><a href="app://redis-vue">app://redis-vue</a></h3>

Or from the command-line with:

:::sh
app open redis-vue
:::


### Run headless on macOS, Linux and Windows

Non Windows OS can install the cross-platform [x dotnet tool](/dotnet-tool) then launch from Command Line with:

:::sh
x open redis-vue
:::

Where you can view it with your preferred browser at `http://localhost:5000`

## [Configure Redis Sentinel Servers](https://github.com/ServiceStack/redis-config)

[![Instant Redis Setup](https://raw.githubusercontent.com/ServiceStack/Assets/master/img/redis/instant-sentinel-setup.png)](https://github.com/ServiceStack/redis-config)

See the
[redis config project](https://github.com/ServiceStack/redis-config) for a quick way to setup up 
the minimal 
[highly available Redis Sentinel configuration](https://github.com/ServiceStack/redis-config/blob/master/README.md#3x-sentinels-monitoring-1x-master-and-2x-slaves)
including start/stop scripts for instantly running multiple redis instances on a single (or multiple) 
Windows, OSX or Linux servers.


# Install RabbitMQ on Windows and .NET
Source: https://docs.servicestack.net/install-rabbitmq-windows

[Rabbit MQ](http://www.rabbitmq.com) is a popular industrial strength open source implementation of the 
[AMQP messaging protocol](http://www.amqp.org) for communicating with message queue middleware that runs
on all major operating systems.

## Installing on Windows

Rabbit MQ is built on the robust Erlang OTP platform which is a prerequisite for installing Rabbit MQ Server, both are downloadable at:

  1. Download and install [Erlang OTP For Windows](http://www.erlang.org/download/otp_win32_R16B03.exe) (vR16B03)
  2. Run the [Rabbit MQ Server Windows Installer](http://www.rabbitmq.com/releases/rabbitmq-server/v3.2.3/rabbitmq-server-3.2.3.exe) (v3.2.3)

The windows installer will download, install and run the Rabbit MQ Server Windows Service listening for AMQP clients at the default port: **5672**.

### Enable [Rabbit MQ's Management Plugin](http://www.rabbitmq.com/management.html)

To provide better visibility of the state of the Rabbit MQ Server instance it's highly recommended to enable 
[Rabbit MQ's Management Plugin](http://www.rabbitmq.com/management.html) which you can do on the command line with:

```bash
"C:\Program Files (x86)\RabbitMQ Server\rabbitmq_server-3.2.3\sbin\rabbitmq-plugins.bat" enable rabbitmq_management
```

To see the new changes you need to restart the **RabbitMQ** Windows Service which can be done on the command line with:

:::sh
net stop RabbitMQ && net start RabbitMQ
:::

Or by restarting the service from the **services.msc** MMC applet UI:

1. Open Windows Run dialog by pressing the **Windows + R** key:

![Windows Run Dialog](https://raw.github.com/mythz/rabbitmq-windows/master/img/run-services.png)

2. Select the **RabbitMQ** Windows Service and click the Restart Icon:

![RabbitMQ Windows Service](https://raw.github.com/mythz/rabbitmq-windows/master/img/rabbitmq-service.png)

Once restarted, open the Rabbit MQ's management UI with a web browser at: `http://localhost:15672` to see an overview of 
the state of the Rabbit MQ server instance:

![RabbitMQ Management UI](https://raw.github.com/mythz/rabbitmq-windows/master/img/rabbitmq-management-ui.png)

## Usage from .NET

To use Rabbit MQ from .NET get Rabbit MQ's [.NET client bindings from NuGet](https://www.nuget.org/packages/RabbitMQ.Client):

:::copy
`<PackageReference Include="RabbitMQ.Client" Version="8.*" />`
:::

With the package installed, we can go through a common scenario of sending and receiving durable messages with Rabbit MQ.

See [RabbitMqTests.cs](https://github.com/mythz/rabbitmq-windows/blob/master/src/RabbitMq.Tests/RabbitMqTests.cs) in this repo, 
for runnable samples of this walkthru below:

### Declare durable Exchange and Queue

Firstly, you will need to register the type of Exchange and Queue before you can use them. 
To create a durable work queue, create a durable "direct" exchange and bind a durable queue to it, e.g:

```csharp
const string ExchangeName = "test.exchange";
const string QueueName = "test.queue";

using (IConnection conn = rabbitMqFactory.CreateConnection())
using (IModel channel = conn.CreateModel())
{
    channel.ExchangeDeclare(ExchangeName, "direct", durable:true, autoDelete:false, arguments:null);
                
    channel.QueueDeclare(QueueName, durable:true, exclusive:false, autoDelete:false,arguments:null);
    channel.QueueBind(QueueName, ExchangeName, routingKey: QueueName);
}
```

In this example we'll also reuse the QueueName for the **routing key** which will enable directly sending messages to a specific queue.

The registration code only needs to be run once to register and configure the Exchange and Queue we'll be using in the remaining examples.
Once run, go back to the Management UI to see the new **test.exchange** Exchange with a binding to the newly created **test.queue**:

![UI - Test Exchange](https://raw.github.com/mythz/rabbitmq-windows/master/img/ui-testexchange.png)

### Publishing a persistent message to a queue

Once the exchange and queue is setup we can start publishing messages to it. 
Rabbit MQ lets you send messages with any arbitrary `byte[]` body, for text messages you should send them as UTF8 bytes.
To ensure the message is persistent across Rabbit MQ Server starts you will want to mark the message as persistent as seen below:

```csharp
var props = channel.CreateBasicProperties();
props.SetPersistent(true);

var msgBody = Encoding.UTF8.GetBytes("Hello, World!");
channel.BasicPublish(ExchangeName, routingKey:QueueName, basicProperties:props, body:msgBody);
```

The routing key will ensure that a copy of the message is delievered to the **test.queue** which you can see in the Admin UI:

![UI - Test Queue](https://raw.github.com/mythz/rabbitmq-windows/master/img/ui-testqueue.png)

### Receiving Messages

There are a couple of different ways you can read published messages from the queue, the most straightforward way is to use `BasicGet`:

```csharp
BasicGetResult msgResponse = channel.BasicGet(QueueName, noAck:true);

var msgBody = Encoding.UTF8.GetString(msgResponse.Body);
msgBody //Hello, World!
```

The `noAck:true` flag tells Rabbit MQ to immediately remove the message from the queue. 

Another popular use-case is to only send acknowledgement (and remove it from the queue) after you've successfully accepted the message, 
which can be done with a separate call to `BasicAck`:

```csharp
BasicGetResult msgResponse = channel.BasicGet(QueueName, noAck:false);

//process message ...

channel.BasicAck(msgResponse.DeliveryTag, multiple:false);
```

An alternate way to consume messages is via a push-based event subscription.
You can use the built-in `QueueingBasicConsumer` to provide a simplified programming model by allowing you to block on a 
Shared Queue until a message is received, e.g:

```csharp
var consumer = new QueueingBasicConsumer(channel);
channel.BasicConsume(QueueName, noAck:true, consumer:consumer);

var msgResponse = consumer.Queue.Dequeue(); //blocking

var msgBody = Encoding.UTF8.GetString(msgResponse.Body);
msgBody //Hello, World!
```

### Processing multiple messages using a subscription

The Shared Queue will block until it receives a message or the channel it's assigned to is closed which causes it to throw 
an `EndOfStreamException`. With this, you can setup a long-running background thread to continually process multiple messages 
in an infinite loop until the Queue is closed.

The sample below shows an example of this in action which publishes 5 messages on a separate thread before closing the channel 
the subscription is bound to causing an **EndOfStreamException** to be thrown, ending the subscription and exiting the loop: 

```csharp
using (IConnection conn = rabbitMqFactory.CreateConnection())
using (IModel channel = conn.CreateModel())
{
    var consumer = new QueueingBasicConsumer(channel);
    channel.BasicConsume(QueueName, noAck: true, consumer: consumer);

    ThreadPool.QueueUserWorkItem(_ => {
        var now = DateTime.UtcNow;
        while (DateTime.UtcNow - now < TimeSpan.FromSeconds(5))
        {
            var props = channel.CreateBasicProperties();
            props.SetPersistent(true);

            var msgBody = Encoding.UTF8.GetBytes("Hello, World!");
            channel.BasicPublish(ExchangeName, routingKey:QueueName, basicProperties:props, 
                body:msgBody);

            Thread.Sleep(1000);
        }

        channel.Close();
    });

    while (true)
    {
        try
        {
            var msgResponse = consumer.Queue.Dequeue(); //blocking

            var msgBody = Encoding.UTF8.GetString(msgResponse.Body);

            Console.WriteLine("Received Message: " + msgBody);

            Thread.Sleep(1000);
        }
        catch (EndOfStreamException ex)
        {
            Console.WriteLine("Channel was closed, Exiting...");
            break;
        }
    }
}
```

The complete source of these examples are available in the stand-alone [RabbitMqTests.cs](https://github.com/mythz/rabbitmq-windows/blob/master/src/RabbitMq.Tests/RabbitMqTests.cs).


# Secure SSL Redis connections
Source: https://docs.servicestack.net/ssl-redis-azure

[ServiceStack.Redis](https://github.com/ServiceStack/ServiceStack.Redis) client includes support for SSL making it suitable for accessing remote Redis server instances over a secure SSL connection.

Redis is normally used as a back-end datastore whose access is typically limited to Internal networks or authorized networks protected via firewalls, when communicating outside of your VPC you'll typically want to communicate over SSL. 

### General SSL Info

ServiceStack.Redis uses .NET's [SslStream](https://docs.microsoft.com/en-us/dotnet/api/system.net.security.sslstream.-ctor?view=net-5.0#System_Net_Security_SslStream__ctor_System_IO_Stream_System_Boolean_System_Net_Security_RemoteCertificateValidationCallback_System_Net_Security_LocalCertificateSelectionCallback_) to establish its SSL connection where you can configure its [RemoteCertificateValidationCallback](https://docs.microsoft.com/en-us/dotnet/api/system.net.security.remotecertificatevalidationcallback?view=net-5.0) to validate whether to accept the specified certificate for authentication:

```csharp
RedisConfig.CertificateValidationCallback = (object sender,
    X509Certificate certificate,
    X509Chain chain,
    SslPolicyErrors sslPolicyErrors) => {
    //...
};
```

And a [LocalCertificateSelectionCallback](https://docs.microsoft.com/en-us/dotnet/api/system.net.security.localcertificateselectioncallback?view=net-5.0) to select the local SSL certificate used for authentication:

```csharp
RedisConfig.CertificateSelectionCallback = (object sender,
    string targetHost,
    X509CertificateCollection localCertificates,
    X509Certificate remoteCertificate,
    string[] acceptableIssuers) => {
    //...
}
```

### Specify SSL and TLS Version

You can specify to use SSL and what TLS version to use on your connection string, e.g:

```csharp
var connString = $"redis://{Host}?ssl=true&sslprotocols=Tls12&password={Password.UrlEncode()}";
var redisManager = new RedisManagerPool(connString);
using var client = redisManager.GetClient();
//...
```

If using `RedisSentinel` SSL needs to be specified on both host connection string and `HostFilter`, e.g: 

```csharp
var sentinel = new RedisSentinel(connString, masterName) {
    HostFilter = host => $"{host}?ssl=true&sslprotocols=Tls12"
};
container.Register(c => sentinel.Start());
```

### Secure SSL Redis connections to Azure Redis

The SSL Support in the Redis Client also enables secure access to a redis-server instance over the Internet and public networks as well, a scenario that's been recently popularized by Cloud hosting environments like [Azure Redis Cache](http://azure.microsoft.com/en-us/services/cache/).

## Getting Started

First we'll need a Redis instance to connect to, for this example we will be using Azure, so you will need an active account which you can create at the [Azure home page](https://azure.microsoft.com/).

Once you have access to the [Azure portal](https://portal.azure.com/), we can create a new Redis instance with 3 easy steps:

1 . Click `New` at the bottom left of the portal

![New](https://github.com/ServiceStack/Assets/raw/master/img/wikis/redis/azure-new-button.png)

2 . Select Redis Cache from the list

![Redis instance menu item](https://github.com/ServiceStack/Assets/raw/master/img/wikis/redis/azure-create-redis.png)

3 . Specify a DNS name, size, resource group and location

![Create instance](https://github.com/ServiceStack/Assets/raw/master/img/wikis/redis/azure-create-redis-demo.png)

It may take a while for the Redis Cache instance to be ready to use, from experience with a 1GB Basic instance, it takes around 15+ minutes.

Once the instance is ready, we can grab the **password** generated for us from the **Keys tile**. If we copy the key, and store it somewhere our host can access it, we can start connecting to Redis.

![Created Redis Instance and Keys menu](https://github.com/ServiceStack/Assets/raw/master/img/wikis/redis/azure-redis-instance.png)

## Configuring our AppHost

We have all the require information and our Redis Cache instance is running, we can now configure our AppHost to use it! 

To make it simple to use the [IRedisClient](https://github.com/ServiceStack/ServiceStack/blob/master/src/ServiceStack.Interfaces/Redis/IRedisClient.cs) from our web service methods, we can register an `IRedisClientsManager` to handle the clients for us. This way, we can use the `base.Redis` property from our services to access the Redis server instance. 

```cs
public override void Configure(Container container)
{
    var connString = AppSettings.GetString("RedisConnectionString");
    container.Register<IRedisClientsManager>(c => 
        new RedisManagerPool(connectionString));
}
```

We are getting our Redis connection string from our Web.Config `<appSettings/>`. The Redis connection string is made up of the domain name of the instance parsing query string parameters to specify other configuration options. In our example the format of the connection string looks like:

```
{AzureRedisKey}@servicestackdemo.redis.cache.windows.net?ssl=true 
```

## Accessing Redis from a Web Service

We can now try a simple example to test that our instance is working. Here's an example of a simple "Todo" service that persists items to our Redis instance:

```cs
// Create your ServiceStack Web Service
public class TodoService : Service
{
    public object Get(Todo todo)
    {
        //Return a single Todo if the id is provided.
        if (todo.Id != default(long))
            return Redis.As<Todo>().GetById(todo.Id);

        //Return all Todos items.
        return Redis.As<Todo>().GetAll();
    }

    // Handles creating the Todo items.
    public Todo Post(Todo todo)
    {
        var todos = Redis.As<Todo>();

        //Get next id for new todo
        todo.Id = todos.GetNextSequence();

        todos.Store(todo);

        return todo;
    }

    // Handles updating the Todo items.
    public Todo Put(Todo todo)
    {
        Redis.As<Todo>().Store(todo);
        return todo;
    }

    // Handles Deleting the Todo item
    public void Delete(Todo todo)
    {
        Redis.As<Todo>().DeleteById(todo.Id);
    }
}

[Route("/todo")]
[Route("/todo/{Id}")]
public class Todo
{
    public long Id { get; set; }
    public string Content { get; set; }
    public int Order { get; set; }
    public bool Done { get; set; }
}
```

You can try a redis-powered TODO's web app like this in our [todos.netcore.io](http://todos.netcore.io) Live Demo. A more comprehensive example can be seen in the [Repository.cs](https://github.com/ServiceStackApps/RedisStackOverflow/blob/master/src/RedisStackOverflow/RedisStackOverflow.ServiceInterface/IRepository.cs) used to power the [RedisStackOverflow Live Demo](http://redisstackoverflow.netcore.io/).

Another property automatically injected when registering our `RedisManagerPool` is `base.Cache` which provides a substitutable [Caching abstraction](/caching) our Services can use to cache results. E.g. we can make use of ServiceStack's high-level Caching API in [Request.ToOptimizedResultUsingCache](/caching#cache-a-response-of-a-service) to enable maximum performance of your Services:

```cs
public object Get(CachedCustomers request)
{
    return base.Request.ToOptimizedResultUsingCache(this.Cache, 
        "urn:customers", () =>
            this.ResolveService<CustomersService>()
            .Get(new Customers()));
}
```

This snippet is from the [Northwind example](https://github.com/ServiceStackApps/Northwind).

## Troubleshooting

### Add Required SSL Certificates to work in Mono

Connecting to Azure Redis Cache via SSL requires Microsoft SSL Certificates. The required certificates can be imported and registered with Mono by running the commands below:

```bash
$ sudo mozroots --import --machine --sync
$ sudo certmgr -ssl -m https://go.microsoft.com
$ sudo certmgr -ssl -m https://nugetgallery.blob.core.windows.net
$ sudo certmgr -ssl -m https://nuget.org
```


# Support for RHEL 9&#x27;s hardened cryptography policy
Source: https://docs.servicestack.net/rhel9-cryptography

A consequence of RedHat Enterprise Linux 9's hardened 
[system-wide cryptographic policies](https://docs.redhat.com/en/documentation/red_hat_enterprise_linux/8/html/security_hardening/using-the-system-wide-cryptographic-policies_security-hardening) 
is that it's incompatible with ServiceStack's current licensing mechanism which uses RSA encryption and SHA1 hashing algorithm
to protect and validate license keys.

Unfortunately this makes it no longer possible to use License Keys to run unrestricted ServiceStack Apps on default 
installs of RHEL 9 or any of its variants including [Rocky Linux 9](https://rockylinux.org).

![](/img/pages/release-notes/v8.3/bg-redhat.webp)

### Use Legacy Cryptography Policy

As it only affected a small number of users initially we recommend 
that they just switch to use
[RHEL's Legacy Cryptography Policy](https://docs.redhat.com/en/documentation/red_hat_enterprise_linux/8/html/security_hardening/using-the-system-wide-cryptographic-policies_security-hardening)
which allows for maximum compatibility with existing software.

### Support for RHEL 9 Default Cryptography Policy

As more customers upgraded to RHEL 9 and started experiencing the same issue, we've invested efforts to 
address this issue starting with adding support for a configurable Hashing algorithm when creating and validating
License Keys. 

Since this issue only affected a minority of our Customers we decided to go with providing a way for customers
affected by this to regenerate their License Key to support RHEL 9's hardened cryptography policy to avoid inflicting any 
additional complexity on the majority of our Customers who are unaffected by this issue.

### Generate License Key for RHEL 9+

Starting from **ServiceStack v8.3+** Customers can regenerate a new License Key with a stronger **SHA512** Hash Algorithm 
that's compatible with RHEL 9's default hardened cryptography policy by visiting:

:::{.text-3xl .text-indigo-600}
https://account.servicestack.net/regenerate-license
:::

### Future

We'll need to wait at least 1-2 years before we can make the stronger Hash Algorithm the default in order to reduce the
impact of not being able to use new License Keys on versions of ServiceStack prior to **v8.2**.

After the switch is made regenerating license keys will no longer be necessary.


# Real World Performance
Source: https://docs.servicestack.net/real-world-performance

We maintain a list of external benchmark results here people have been experiencing to provide an idea of the relative performance you can expect from real-world usage:

#### [Get 25k rows from MS SQL Express and convert to JSON](https://twitter.com/lukaszgasior/status/331704240085028864)

```
EF & JSON.NET                         2300ms
EF [AsNoTracking] & JSON.NET           973ms
EF [AsNoTracking] & ServiceStack       809ms
Simple.Data & JSON.NET                1598ms
Simple.Data & ServiceStack             933ms
ServiceStack.OrmLite & JSON.NET        405ms
ServiceStack.OrmLite & ServiceStack    245ms
```

#### [ServiceStack vs WebApi client / server end-to-end results](https://twitter.com/anilmujagic/status/272544925478973440)

```
ServiceStack                 9667ms
WebApi                      30407ms
```

GitHub project for the benchmarks are at:
[https://github.com/anilmujagic/ServiceBenchmark](https://github.com/anilmujagic/ServiceBenchmark)

#### [ServiceStack: a good alternative to WCF (French)](http://sgbd.arbinada.com/node/77)

```
ServiceStack                    19s
WCF Data Services (Optimized)   28s
WCF Data Services               48s
```

#### [ServiceStack.net](http://fir3pho3nixx.blogspot.com/2011/04/servicestacknet.html)

> One thing that I was completely surprised by today was the performance of the open source ServiceStack.NET frameworks. Even with the performance tuned release of JSON.NET I found that ServiceStack.Text beat it by a rediculous margin. It serialises 2x faster and deserialises 4x faster.

#### [Redis vs RavenDB – Benchmarks for .NET Client NoSQL Solutions](http://www.servicestack.net/mythz_blog/?p=474)

```
Redis (Cygwin)                254ms
Redis (Cygwin + fsync)        543ms
Raven DB                     2983ms
```


# Roadmap
Source: https://docs.servicestack.net/roadmap

Our future Roadmap is driven by Customer Feature requests which are maintained on [ServiceStack/Discuss](https://github.com/ServiceStack/Discuss/discussions/categories/ideas).


# Quick Start
Source: https://docs.servicestack.net/ai-server/quickstart

Install AI Server by running [install.sh](https://github.com/ServiceStack/ai-server/blob/main/install.sh):

### 1. Clone the Repository

Clone the AI Server repository from GitHub:

:::sh
git clone https://github.com/ServiceStack/ai-server
:::

### 2. Run the Installer

:::sh
cd ai-server && cat install.sh | bash
:::

The installer will detect common environment variables for its supported AI Providers including OpenAI, Anthropic, 
Mistral AI, Google, etc. and prompt if you would like to include any others in your AI Server configuration.

<ascii-cinema src="/pages/ai-server/ai-server-install.cast" 
    loop="true" poster="npt:00:21" theme="dracula" rows="12" />

## Accessing AI Server

Once the AI Server is running, you can access the Admin Portal at [http://localhost:5006/admin](http://localhost:5005/admin) to configure your AI providers and generate API keys.
If you first ran the AI Server with configured API Keys in your `.env` file, you providers will be automatically configured for the related services.

::: info
The default password to access the Admin Portal is `p@55wOrd`. You can change this in your `.env` file by setting the `AUTH_SECRET` or providing it during the installation process.
:::

You will then be able to make requests to the AI Server API endpoints, and access the Admin Portal user interface like the [Chat interface](http://localhost:5005/admin/Chat) to use your AI Provider models.

#### Re-install

If needed you can reset the process by deleting your local `App_Data` directory and rerunning `docker compose up` or re-running the `install.sh`.

### Optional - Install ComfyUI Agent

If your server also has a GPU you can ask the installer to also install the [ComfyUI Agent](/ai-server/comfy-extension) locally:

<ascii-cinema src="/pages/ai-server/agent-comfy-install.cast" 
    loop="true" poster="npt:00:09" theme="dracula" rows="13" />

The ComfyUI Agent is a separate Docker agent for running [ComfyUI](https://www.comfy.org), 
[Whisper](https://github.com/openai/whisper) and [FFmpeg](https://www.ffmpeg.org) on servers with GPUs to handle 
AI Server's [Image](/ai-server/transform/image) and 
[Video transformations](/ai-server/transform/video) and Media Requests, including:

- [Text to Image](/ai-server/text-to-image)
- [Image to Text](/ai-server/image-to-text)
- [Image to Image](/ai-server/image-to-image)
- [Image with Mask](/ai-server/image-with-mask)
- [Image Upscale](/ai-server/image-upscale)
- [Speech to Text](/ai-server/speech-to-text)
- [Text to Speech](/ai-server/text-to-speech)

#### Comfy UI Agent Installer

To install the ComfyUI Agent on a separate server (with a GPU), you can clone and run the ComfyUI Agent installer from there instead:

**Clone the Comfy Agent Repo:**

:::sh
git clone https://github.com/ServiceStack/agent-comfy.git
:::

**Run the Comfy Agent Installer:***

:::sh
cd agent-comfy && cat install.sh | bash
:::

Providing your AI Server URL and Auth Secret when prompted will automatically register the ComfyUI Agent with your AI Server to handle related requests.


You will be prompted to provide the AI Server URL and ComfyUI Agent URL during the installation.
These should be the accessible URLs for your AI Server and ComfyUI Agent. When running locally, the ComfyUI Agent will be populated with a docker accessible path as `localhost` won't be accessible from the AI Server container.
If you want to reset the ComfyUI Agent settings, remember to remove the provider from the AI Server Admin Portal.
:::

### Supported OS

The AI Server installer is supported on Linux, macOS, and Windows with WSL2, and all require Docker and Docker Compose to be installed at a minimum.

## Prerequisites 

### Linux

Linux requires the following software installed:

- Docker Engine (with Docker Compose)
- Git

#### ComfyUI Agent

To run the ComfyUI Agent locally, you will also need:

- Nvidia GPU with CUDA support
- Nvidia Container Toolkit for [Docker](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/install-guide.html)

### macOS

macOS also requires:

- Docker Engine (with Docker Compose)

#### ComfyUI Agent

ComfyUI Agent requires Pytorch running in Docker which isn't available for macOS

### Windows with WSL2

Windows with WSL2 requires the following prerequisites:

- Docker Engine accessible from WSL2 like [Docker Desktop](https://www.docker.com/products/docker-desktop)
- WSL2 with Ubuntu 20.04 LTS or later

#### ComfyUI Agent

To run the ComfyUI Agent locally, you will also need:

- Nvidia GPU with [WSL2 CUDA support](https://docs.nvidia.com/cuda/wsl-user-guide/index.html)


# Configuring AI Server
Source: https://docs.servicestack.net/ai-server/configuration

AI Server can be configured in several ways:

- **install.sh Script**: Run the `install.sh` script to set up the AI Server and ComfyUI Agent.
- **.env File**: Update the `.env` file with your API keys and run the AI Server for the first time.
- **Admin Portal**: Use the Admin Portal to add, edit, or remove AI Providers and generate AI Server API keys.

## Running the Installer

The `install.sh` script is the quickest way to get AI Server up and running with the default configuration. This is ideal for local development and testing.

To run the installer:

```sh
git clone https://github.com/ServiceStack/ai-server.git
cd ai-server
cat install.sh | bash
```

The installer will prompt you to configure your AI Providers and optionally add the ComfyUI Agent.

## `.env` Configuration

The installer populates the `.env` file with the choices you made during the installation script. You can also manually configure the `.env` file with your API keys and settings.

```ini
OPENAI_API_KEY=<Your OpenAI API Key>
ANTHROPIC_API_KEY=<Your Anthropic API Key>
OPENROUTER_API_KEY=<Your OpenRouter API Key>
MISTRAL_API_KEY=<Your Mistral API Key>
GOOGLE_API_KEY=<Your GoogleCloud API Key>
GROQ_API_KEY=<Your Groq Cloud API Key>
AUTH_SECRET="p@55wOrd"
ASSETS_BASE_URL="http://localhost:5006"
```

After these values are set in your `.env` file, you can run the AI Server for the first time via docker compose:

```sh
docker compose up
```

This will perform an initial setup, saving providers configuration in the SQLite database. From here, you can manage your AI Providers via the [Admin Portal](http://localhost:5006/admin).

:::info 
The default credentials to access the Admin Portal are `p@55wOrd`, this can be changed in your `.env` file by setting the `AUTH_SECRET` key.
:::

### Using the Admin Portal

The Admin Portal provides a more interactive way to manage your AI Providers after the AI Server is running.

To access the Admin Portal:

1. Navigate to [http://localhost:5006/admin](http://localhost:5005/admin).
2. Log in with the default credentials `p@55wOrd`.
3. Click on the **AI Providers** tab to view and manage your AI Providers.

Here you can add, edit, or remove AI Providers, as well as generate API keys for each provider.

AI Server supports the following AI Providers:

- **OpenAI**: OpenAI Chat API
- **Anthropic**: Anthropic Claude API
- **Google**: Google Cloud AI
- **OpenRouter**: OpenRouter API
- **Mistral**: Mistral API
- **GROQ**: GROQ API
- **Ollama**: Ollama API

Media Providers can also be configured in the Admin Portal. These include:

- **ComfyUI**: ComfyUI Agent
  - **Image Generation**
  - **Text-to-Speech**
  - **Speech-to-Text**
  - **Video & Image Processing**
- **Replicate**: Replicate API
  - **Image Generation**
- **OpenAI**: OpenAI API
  - **Image Generation**
  - **Text-to-Speech**

## Register AI Providers 

To let AI Server know about your API Providers or self-hosted instances by creating them in the **AI Provider** section where you can use **Custom** AI Provider type to register any OpenAI Chat compatible endpoint, e.g:

[![](/img/pages/ai-server/custom-openai-provider.webp)](/ai-server/)

After registering AI Providers you can try to use them in the [Chat UI](/ai-server/chat):

[![](/img/pages/ai-server/custom-openai-provider-chat.webp)](/ai-server/chat)

## Create API Keys for your Apps

After testing the llama-server instance is working with the Chat UI it's time to create API Keys
for all your Apps so they can access AI Servers APIs with the [API Keys UI](/auth/admin-apikeys#api-keys-admin-ui):

![](/img/pages/ai-server/admin-apikeys.webp)

Here you can create new API keys, view existing keys, and revoke keys as needed. Keys can be created with expiration dates, 
and restrictions to specific API endpoints, along with notes to help identify the key's purpose.

It's recommended to use a different API Key per App so they can be monitored and analyzed separately.

With a valid API Key in hand your App's can use AI Server's DTOs with ServiceStack generic
service clients to enable typed integrations in [11 different languages](/ai-server/openai-chat-all-languages).

## Stored File Management

AI Server stores results of the AI operations in a pre-configured paths.

- **Artifacts**: AI generated images, audio, and video files, default path is `App_Data/artifacts`.
- **Files**: Cached variants and processed files, default path is `App_Data/files`.

These paths can be configured in the `.env` file by setting the `ARTIFACTS_PATH` and `AI_FILES_PATH` keys.

## Custom Definitions

AI Server's knowledge is limited to the AI Provider and Model types and definitions defined in its 
[/data](https://github.com/ServiceStack/ai-server/tree/main/AiServer/wwwroot/lib/data) definitions.

These definitions are merged and can be extended with custom definitions you can create in your `/App_Data/overrides/` folder, e.g:

```files
/App_Data
  /overrides
    ai-models.json 
    ai-types.json 
    generation-types.json 
    media-models.json 
    media-types.json 
    prompts.json
    tts-voices.json
```


# Self-hosted AI Providers with Ollama
Source: https://docs.servicestack.net/ai-server/ollama

Ollama can be used as an AI Provider type to process LLM requests in AI Server.

:::youtube S1Xw0iQLa2c
Using Ollama with AI Server
:::

## Setting up Ollama

When using Ollama as an AI Provider, you will need to ensure the models you want to use are available in your Ollama instance.

This can be done via the command `ollama pull <model-name>` to download the model from the [Ollama library](https://ollama.com/library).

Once the model is downloaded, and your Ollama instance is running and accessible to AI Server, you can configure Ollama as an AI Provider in AI Server Admin Portal.

## Configuring Ollama in AI Server

Navigating to the Admin Portal in AI Server, select the **AI Providers** menu item on the left sidebar.

![AI Providers](/img/pages/ai-server/admin-dashboard.webp)

Click on the **New Provider** button at the top of the grid.

![New Provider](/img/pages/ai-server/admin-dashboard-providers.webp)

Select Ollama as the Provider Type at the top of the form, and fill in the required fields:

- **Name**: A friendly name for the provider.
- **Endpoint**: The URL of your Ollama instance, eg `http://localhost:11434`.
- **API Key**: Optional API key to authenticate with your Ollama instance.
- **Priority**: The priority of the provider, used to determine the order of provider selection if multiple provide the same model.

![Ollama Provider](/img/pages/ai-server/admin-dashboard-ollama-provider.webp)

Once the URL (and optional API Key) is set, requests will be made to your Ollama instance to list available models.
By default, it will look for a locally running Ollama instance on port 11434, but you can change the URL to point to your Ollama instance.
These will then be displayed as options to enable for the provider you are configuring.

![Ollama Models](/img/pages/ai-server/ollama-models.webp)

Select the models you want to enable for this provider, and click **Save** to save the provider configuration.

## Using Ollama models in AI Server

Once configured, you can make requests to AI Server to process LLM requests using the models available in your Ollama instance.

Model names in AI Server are common across all providers, enabling you to switch or load balance between providers without changing your client code. See [Usage](https://docs.servicestack.net/ai-server/usage) for more information on making requests to AI Server.


# Self-host LLMs in production with llama.cpp llama-server
Source: https://docs.servicestack.net/ai-server/llama-server

[Ollama](https://ollama.com), [LM Studio](https://lmstudio.ai) and [Jan](https://jan.ai) 
have become popular choices for AI enthusiasts looking to run large language models 
(LLMs) locally which provide a UX-friendly intuitive interfaces for downloading, installing and running a variety of open-source models on personal workstations, acceleratable with GPUs.

However, when scaling beyond personal use, these tools reveal their limitations which weren't 
designed with production deployment in mind, often lacking flexible and robust resource 
management, fine-grained authorized usage and optimizations necessary for sustained, high-demand 
environments.

## Enter llama-server: The Production workhorse

The technology underpinning these applications is 
[llama.cpp](https://github.com/ggml-org/llama.cpp), a groundbreaking C/C++ implementation that 
enables running sophisticated language models on consumer hardware. 
This remarkable project, created by Georgi Gerganov, revolutionized the LLM landscape by making 
previously cloud-only models accessible to everyday users through clever quantization techniques 
and memory-efficient operations.

While Ollama and LM Studio provide user-friendly wrappers around this technology, llama.cpp's
[llama-server](https://github.com/ggml-org/llama.cpp/tree/master/examples/server) leverages the 
same core but strips away the overhead to focus exclusively on performance and stability. 
By directly utilizing the llama.cpp library and its server component, organizations can bypass the 
abstractions introduced by desktop applications and tap into the raw power of the underlying engine whose 
[highly configurable runtime](https://github.com/ggml-org/llama.cpp/tree/master/examples/server#usage)
allows for optimized self-hosting of authorized models.

This direct approach eliminates unnecessary layers that might introduce latency or unexpected 
behaviors, providing a more consistent and predictable experience necessary for production environments. 
For DevOps teams and system administrators, this translates to fewer surprises during deployment 
and operation — a crucial factor when incorporating self-hosting AI solutions into critical business applications.

## Hosting llama-server with Docker

Organizations that have incorporated container based deployment solutions will most likely prefer 
a docker solution of which is available in a number of different hardware optimized configurations including CPU, CUDA for NVIDIA GPUs, ROCm for AMD GPUs and MUSA for Moore Threads GPUs.

Docker containers requiring NVIDIA GPU accelearation will require installing the
[NVidia Container Toolkit](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/install-guide.html) which allows you to run the `llama.cpp:server-cuda` CUDA optimized image with the `--gpus` flag to utilize your hardwares NVIDIA GPUs, e.g:

```sh
docker run -p 8080:8080 -v /path/to/models:/models --gpus all \
    ghcr.io/ggml-org/llama.cpp:server-cuda -m models/phi-4.Q4_K_M.gguf \
    -c 512 --host 0.0.0.0 --port 8080 --n-gpu-layers 999
```

llama.cpp can run models in the [GGUF File format](https://github.com/ggml-org/ggml/blob/master/docs/gguf.md) that are commonly [hosted on hugging face](https://huggingface.co/models?library=gguf&sort=trending). As of this writing Microsoft, Google and Mistral AI have released some of the best quantized LLMs you can run on consumer GPUs:

 - [Phi-4 14B](https://huggingface.co/bartowski/phi-4-GGUF/tree/main) by Microsoft
 - [Gemma3 27B](https://huggingface.co/google/gemma-3-27b-it-qat-q4_0-gguf/tree/main) by Google
 - [Mistral Small 3.1 24B](https://huggingface.co/openfree/Mistral-Small-3.1-24B-Instruct-2503-Q8_0-GGUF/tree/main) by Mistral AI

### Docker compose

Docker compose is a great solution for hosting llama-server in production environments which simplifies managing multiple services within declarative configurations, making deployments more repeatable and scalable.

```yml
version: '3'

services:
  phi:
    image: ghcr.io/ggml-org/llama.cpp:server-cuda
    environment:
      - LLAMA_ARG_N_GPU_LAYERS=999
      - LLAMA_ARG_MODEL=/models/phi-4.Q4_K_M.gguf
    ports:
      - "8000:8080"
    volumes:
      - ./models:/models
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: all
              capabilities: [gpu]
  gemma:
    image: ghcr.io/ggml-org/llama.cpp:server-cuda
    environment:
      - LLAMA_ARG_N_GPU_LAYERS=999
      - LLAMA_ARG_MODEL=/models/gemma-3-27b-it-qat-q4_0-gguf
    ports:
      - "8001:8080"
    volumes:
      - ./models:/models
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: all
              capabilities: [gpu]
  mistral:
    image: ghcr.io/ggml-org/llama.cpp:server-cuda
    environment:
      - LLAMA_ARG_N_GPU_LAYERS=999
      - LLAMA_ARG_MODEL=/models/mistral-small-3.1-24b-instruct-2503-q8_0.gguf
    ports:
      - "8002:8080"
    volumes:
      - ./models:/models
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: all
              capabilities: [gpu]
```

After saving this to `docker-compose.yml` along with the models:

```files
/models
  phi-4.Q4_K_M.gguf
  gemma-3-27b-it-qat-q4_0-gguf
  mistral-small-3.1-24b-instruct-2503-q8_0.gguf
docker-compose.yml
```

You'll be able to run and test them with:

:::sh
docker compose up
:::

This will launch 3 container instances of llama-server configured to run different models accessible via an [OpenAI compatible API](https://platform.openai.com/docs/api-reference/chat) on ports `8000`, `8001` and `8002` which you can test using llama-server's Chat Web UI.

### Dedicated GPUs

Docker containers can also be configured to run llama-server on different dedicated GPUs, 
identified by their GPU index:

```yml
- driver: nvidia
  device_ids: ['0'] # Assign to GPU 0
  capabilities: [gpu]
```

## Systemd Services

You can trade hosting flexibility to squeeze an extra ounce of performance and run without the overhead of a container by running a compiled llama-server natively by cloning llama.cpp repo:

:::sh
git clone https://github.com/ggml-org/llama.cpp
:::

For NVIDIA GPUs you'll need to install [NVIDIA CUDA Toolkit](https://developer.nvidia.com/cuda-toolkit) before running a CUDA optimized llama.cpp build with:

```sh
cmake -B build -DGGML_CUDA=ON
cmake --build build --config Release
```

If all goes well after a long while you'll get a freshly minted llama-server executable at
`/build/bin/llama-server` which you can create a managed Systemd service with:

:::sh
sudo vi /etc/systemd/system/llama-server-gemma3.service
:::

With the configuration of your llama-server service using your preferred model and configuration options, e.g:

```ini
[Unit]
Description=Llama Server: Gemma3 27B
After=network.target

[Service]
Type=simple
User=root
WorkingDirectory=/home/deploy/llama.cpp
Environment="CUDA_VISIBLE_DEVICES=0"
ExecStart=/home/deploy/llama.cpp/build/bin/llama-server \
  --model /home/deploy/llama.cpp/models/gemma-3-27b-it-qat-q4_0-gguf \
  -ngl 999 --host 0.0.0.0 --port 8080
Restart=on-failure
RestartSec=5s
StandardOutput=file:/home/deploy/llama.cpp/logs/llama-server-gemma3.stdout.log
StandardError=file:/home/deploy/llama.cpp/logs/llama-server-gemma3.stderr.log

[Install]
WantedBy=multi-user.target
```

To enable your new systemd service, reload systemd's configuration with:

:::sh
systemctl daemon-reload
:::

Where you'll now be able to use systemd to start/stop/restart your llama-service with:

:::sh
systemctl start llama-server-gemma3
:::

### Typed Open AI Chat APIs in 11 Languages

Since [AI Server](https://openai.servicestack.net) is written in ServiceStack we're able to use
its OpenAI Compatible Chat API DTOs to enable typed integrations in its
[11 supported languages](/ai-server/openai-chat-all-languages).

### Access llama-server from C#

1. Create an empty console application:

:::sh
dotnet new console
:::

2. Add the **ServiceStack.Client** NuGet package:

:::sh
dotnet add package ServiceStack.Client
:::

3. Download AI Server's Typed C# DTOs:

:::sh
`npx get-dtos csharp https://openai.servicestack.net`
:::

4. Call llama-server's OpenAI Chat API from C#: 

```csharp
// Program.cs
using ServiceStack;
using ServiceStack.Text;
using AiServer.ServiceModel;

var client = new JsonApiClient("https://localhost:8000");
var result = await client.PostAsync<OpenAiChatResponse>("/v1/chat/completions",
    new OpenAiChatCompletion {
        Messages = [
            new () { Role = "user", Content = "What's the capital of France?" }
        ],
        MaxTokens = 50
    });

result.PrintDump();
```

Run the program:

:::sh
dotnet run
:::

### Access llama-server from [Node](https://nodejs.org) or [Bun](https://bun.sh) with TypeScript

1. Add the `@servicestack/client` client library:

:::sh
npm install @servicestack/client
:::

2. Download AI Server's TypeScript DTOs:

:::sh
`npx get-dtos typescript https://openai.servicestack.net`
:::

Call llama-server with TypeScript DTOs and the generic `JsonServiceClient`

```ts
import { JsonServiceClient, Inspect } from "@servicestack/client"
import { OpenAiChatCompletion } from "./dtos"

const client = new JsonServiceClient("https://localhost:8000")

const result = await client.postToUrl("/v1/chat/completions",
    new OpenAiChatCompletion({
        messages: [
            { role: "user", content: "What's the capital of France?" }
        ],
        max_tokens: 50
    })
)

Inspect.printDump(result)
```

## Managed AI Server Gateway

If your organization needs to maintain a number of AI integrations you may want to consider
running them behind a Managed AI Gateway so that your App's only need to be configured to use a 
single endpoint, abstracting away all the complexity of managing multiple AI Providers, 
API Key managment and monitoring behind a single location.

### Open Source AI Server

To support this use-case we're developing [AI Server](https://openai.servicestack.net) - an OSS self-hosted managed gateway that our production AI Applications utilize for all their AI requirements.

AI Server allows you to orchestrate your systems AI requests through a single self-hosted application to control what AI Providers App's should use without impacting their client integrations. It serves as a private gateway to process LLM, AI, and Media Transformations, dynamically delegating tasks across multiple providers.

[![](/img/pages/ai-server/overview.svg)](https://openai.servicestack.net)

:::youtube Ojo80oFQte8
AI Server
:::

Benefits include:

 - **Unified AI Gateway** - Centralized management, load balance and monitor AI usage
 - **Multi Providers** - Manage multiple self-hosted llama-server/Ollama instances or API Hosted LLMs (e.g. OpenAI, Anthropic, Mistral AI, Google, OpenRouter, Groq)
 - **Load Balancing** - Delegate requests across multiple providers hosting same model
 - **Developer UX** - Simple Typed AI access to developer friendly APIs 
 in 11 different languages supporting **Synchronous**, **Queued** and **Web Callback** integrations
 - **Secure access** - Only allow access from Auhtorized Apps using simple API keys
 - **Analytics** - Observe and monitor your Organizations AI Usage
 - **Background Jobs** - Monitor executing AI requests in real-time
 - **Audit History** - Access previous AI Request/Responses in monthly archivable DBs

### Install

AI Server can be installed on Linux, macOS or WSL/Windows with Docker

1. Clone the Repository

:::sh
git clone https://github.com/ServiceStack/ai-server
:::

2. Run the Installer

:::sh
cd ai-server && cat install.sh | bash
:::

<ascii-cinema src="https://docs.servicestack.net/pages/ai-server/ai-server-install.cast"
  loop="true" poster="npt:00:21" theme="dracula" rows="12" />

This will launch a self-hosted instance of AI Server at: `https://localhost:5006` where you'll be able to Sign In with your chosen Admin password at installation and access AI Server's Admin UI at:

<div class="not-prose">
  <h3 class="text-4xl text-center text-indigo-800 pb-3">
    <span class="text-gray-300">https://localhost:5006</span>/admin
  </h3>
</div>

![](/img/pages/ai-server/admin-dashboard.webp)

## Registering llama-server endpoints

To let AI Server know about your new llama-server instances create a new **AI Provider** with the **Custom** AI Provider type to register an OpenAI Chat compatible endpoint, e.g:

[![](/img/pages/ai-server/custom-openai-provider.webp)](/ai-server/)

As llama-server is only configured to serve a single model it can configured with any model name as it's ignored by llama-server but used by AI Server to route AI requests for that model to the custom AI Provider instance which you can try in the [Chat UI](/ai-server/chat):

[![](/img/pages/ai-server/custom-openai-provider-chat.webp)](/ai-server/chat)

## Create API Keys for your Apps

After testing the llama-server instance is working with the Chat UI it's time to create API Keys
for all your Apps so they can access AI Servers APIs with the [API Keys UI](/auth/admin-apikeys#api-keys-admin-ui):

![](/img/pages/ai-server/admin-apikeys.webp)

It's recommended to use a different API Key per App so they can be monitored and analyzed separately.

With a valid API Key in hand your App's can use AI Server's DTOs with ServiceStack generic
service clients to enable typed integrations in [11 different languages](/ai-server/openai-chat-all-languages).

### Synchronous Usage Example

Here's an example of Synchronous Usage in C#: 

```csharp
var client = new JsonApiClient("https://localhost:5006") { 
  BearerToken = Environment.GetEnvironmentVariable("AI_SERVER_API_KEY")
};

var response = await client.PostAsync(new OpenAiChatCompletion {
    Model = "phi4.gguf",
    Messages =
    [
      new() { Role = "system", Content = "You are a helpful AI assistant" },
      new() { Role = "user", Content = "How do LLMs work?" }
    ],
    MaxTokens = 50
});
var answer = response.Choices[0].Message.Content;
```

### Queued Open AI Chat Completion

Alternatively, you can call the same endpoint asynchronously which will queue the request for processing then check the status of the request and download the response when it's ready.

```csharp
var response = await client.PostAsync(new QueueOpenAiChatCompletion {
  Request = new() {
    Model = "phi4.gguf",
      Messages =
      [
        new() { Role = "system", Content = "You are a helpful AI assistant" },
        new() { Role = "user", Content = "How do LLMs work?" }
      ],
      MaxTokens = 50
    },
});

// Poll for Job Completion Status
GetOpenAiChatStatusResponse status = new();
while (status.JobState is 
  BackgroundJobState.Started or BackgroundJobState.Queued)
{
    status = await client.GetAsync(new GetOpenAiChatStatus { 
      RefId = response.RefId 
    });
    await Task.Delay(1000);
}

var answer = status.Result.Choices[0].Message.Content;
```

### ReplyTo Callback Chat Completion

A more reliable Application integration pattern is to provide a `ReplyTo` callback URL to get notified of the response when it's completed, e.g:

```csharp
var response = await client.PostAsync(new QueueOpenAiChatCompletion {
  Request = new() {
    Model = "phi4.gguf",
      Messages =
      [
        new() { Role = "system", Content = "You are a helpful AI assistant" },
        new() { Role = "user", Content = "How do LLMs work?" }
      ],
      MaxTokens = 50
    },
    ReplyTo = "https://localhost:5001/api/QueueOpenAiChatResponse"
});
```

This enables a push notification integration where your response is not coupled to the client making the request and polling for the response. It's a more robust solution as the notification is handled by a managed background job with retries so that App's are still able to get notified of responses after deployments.


# ComfyUI Agent
Source: https://docs.servicestack.net/ai-server/comfy-extension

ComfyUI is a powerful workflow tool for various AI related tasks including the ability to create images from text, images from images, and more. It is a key component of AI Server that provides a wide range of processing capabilities.

One issue it has though is that it can be difficult to integrate with other systems. The ComfyUI API consists of converting a JSON workflow definition to an API format with very specific requirements.

As a way to leverage the ComfyUI API in a more accessible manner, we have created a [ComfyUI Agent](https://github.com/serviceStack/agent-comfy) repository so you can more easily use ComfyUI workflows and add it to be a provider in AI Server. This allows you to integrate a ComfyUI Agent into your AI Server instance using it as a remote self-hosted agent capable of processing image requests, and other modalities.

Since a lot of AI workloads require GPUs or other specialized hardware, the ComfyUI Agent can be run on a separate machine with the necessary hardware, and AI Server can be configured to use it as a provider for these kinds of tasks.

## Installing the ComfyUI Agent

To install this more easily, you can use the `install.sh` script in the ComfyUI Agent repository. This works the same way as the AI Server installer, and will prompt you for the necessary configuration options.

This installer supports both local and remote installations, and will ask you for the necessary configuration options including the Auth Secret for your AI Server instance. The install process will then register the ComfyUI Agent with your AI Server instance, enabling it for the model selections you make during the installation.

```sh
git clone https://github.com/ServiceStack/agent-comfy.git
cd agent-comfy
cat install.sh | bash
```

This process will also persist the configuration in the `.env` file in the ComfyUI Agent directory, so you can easily restart the ComfyUI Agent with the same configuration.

<ascii-cinema src="/pages/ai-server/agent-comfy-install.cast" 
    loop="true" poster="npt:00:09" theme="dracula" rows="13" />

:::info
On the first run, the ComfyUI Agent will download the models you selected during the installation process. This can take some time depending on the size of the models and your internet connection speed.
:::

### .env Configuration

The `.env` file is used to configure the ComfyUI Agent during the initial setup, and is the easiest way to get started.

```sh
DEFAULT_MODELS=sdxl-lightning,text-to-speech,speech-to-text,image-upscale-2x,image-to-text
HF_TOKEN=your_huggingface_token
AGENT_PASSWORD=password-to-restrict-access-to-agent
```

::: info 
Models requiring authentication to download are also flagged in the `/lib/data/media-models.json` file of AI Server GitHub repository.
:::

### Accessing the ComfyUI Agent

Once the ComfyUI Agent is running, you can access the ComfyUI Agent instance at [http://localhost:7860](http://localhost:7860) and can be used as a standard ComfyUI.
The AI Server has pre-defined workflows to interact with your ComfyUI Agent instance to generate images, audio, text, and more.

### Overriding Workflows

These workflows are found in the AI Server AppHost project under `workflows`. These are templated JSON versions of workflows you save in the ComfyUI web interface.

You can override these workflows by creating a new JSON file with the same name and path but in the `App_Data/overrides` folder. 

E.g. to override the `text_to_image` workflow, you would create a file at `App_Data/overrides/text_to_image.json`

This would override all calls that use text-to-image workflow sent to your ComfyUI Agent instance. 

You can also override just `flux-schnell` by creating a file at `App_Data/overrides/flux1/text_to_image.json`
and Stable Diffusion 3.5 at `App_Data/overrides/sd35/text_to_image.json`.


# Typed Open AI Chat &amp; Ollama APIs in 11 Languages
Source: https://docs.servicestack.net/ai-server/openai-chat-all-languages

A nice consequence of AI Server's [OpenAiChatCompletion](https://openai.servicestack.net/ui/OpenAiChatCompletion?tab=details) API 
being an **Open AI Chat compatible API** is that it can also be used to access other LLM API Gateways, like Open AI's Chat GPT, Open Router,  Mistral AI, GroqCloud as well as self-hosted Ollama instances directly in 11 of ServiceStack's supported typed languages.

## Great use-case for Add ServiceStack Reference

It serves as a great opportunity to showcase the simplicity and flexibility of the [Add ServiceStack Reference](/add-servicestack-reference) feature where invoking APIs are all done the same way in all languages where the same generic Service Client can be used to call any ServiceStack API by downloading their typed API DTOs and sending its populated Request DTO.

Typically your `baseUrl` would be the URL of the remote ServiceStack API, but in this case we're using the
generic JSON Service Client and Typed DTOs to call an external Open AI Chat API directly, e.g. to call your 
local self-hosted [Ollama Server](https://ollama.com) you'd use:

```csharp
var baseUrl = "http://localhost:11434";
```

We'll use this to show how to call Open AI Chat APIs in 11 different languages:

### C#

Install the `ServiceStack.Client` NuGet package:

:::copy
`<PackageReference Include="ServiceStack.Client" Version="8.*" />`
:::

Download AI Server's C# DTOs with [x dotnet tool](/dotnet-tool):

:::copy
`x csharp https://openai.servicestack.net`
:::

Call API by sending `OpenAiChatCompletion` Request DTO with `JsonApiClient`:

```csharp
using ServiceStack;

var client = new JsonApiClient(baseUrl);

var result = await client.PostAsync<OpenAiChatResponse>("/v1/chat/completions",
    new OpenAiChatCompletion {
        Model = "mixtral:8x22b",
        Messages = [
            new () { Role = "user", Content = "What's the capital of France?" }
        ],
        MaxTokens = 50
    });
```

### TypeScript

Install the `@servicestack/client` npm package:

:::copy
npm install @servicestack/client
:::

Download AI Server's TypeScript DTOs:

:::copy
`npx get-dtos typescript https://openai.servicestack.net`
:::

Call API by sending `OpenAiChatCompletion` Request DTO with JsonServiceClient: 

```ts
import { JsonServiceClient } from "@servicestack/client"
import { OpenAiChatCompletion } from "./dtos"

const client = new JsonServiceClient(baseUrl)

const result = await client.postToUrl("/v1/chat/completions",
    new OpenAiChatCompletion({
        model: "mixtral:8x22b",
        messages: [
            { role: "user", content: "What's the capital of France?" }
        ],
        max_tokens: 50
    })
)
```

### JavaScript

Save [servicestack-client.mjs](https://unpkg.com/@servicestack/client@2/dist/servicestack-client.mjs) to your project

Define an Import Map referencing its saved location

```html
<script type="importmap">
    {
        "imports": {
            "@servicestack/client": "/js/servicestack-client.mjs"
        }
    }
</script>
```

Download AI Server's ESM JavaScript DTOs:

:::copy
`npx get-dtos mjs https://openai.servicestack.net`
:::

Call API by sending `OpenAiChatCompletion` Request DTO with JsonServiceClient:

```js
import { JsonServiceClient } from "@servicestack/client"
import { OpenAiChatCompletion } from "./dtos.mjs"

const client = new JsonServiceClient(baseUrl)

const result = await client.postToUrl("/v1/chat/completions",
    new OpenAiChatCompletion({
        model: "mixtral:8x22b",
        messages: [
            { role: "user", content: "What's the capital of France?" }
        ],
        max_tokens: 50
    })
)
```

### Python

Install the `servicestack` PyPI package:

:::copy
pip install servicestack
:::

Download AI Server's Python DTOs:

:::copy
`npx get-dtos python https://openai.servicestack.net`
:::

Call API by sending `OpenAiChatCompletion` Request DTO with JsonServiceClient:

```py
from servicestack import JsonServiceClient
from my_app.dtos import *

client = JsonServiceClient(baseUrl)

result = client.post_url("/v1/chat/completions",OpenAiChatCompletion(
    model="mixtral:8x22b",
    messages=[
        OpenAiMessage(role="user",content="What's the capital of France?")
    ],
    max_tokens=50
))
```

### Dart

Include `servicestack` package in your projects `pubspec.yaml`:

:::copy
servicestack: ^3.0.1
:::

Download AI Server's Dart DTOs:

:::copy
`npx get-dtos dart https://openai.servicestack.net`
:::

Call API by sending `OpenAiChatCompletion` Request DTO with JsonServiceClient:

```dart
import 'dart:io';
import 'dart:typed_data';
import 'package:servicestack/client.dart';

var client = JsonServiceClient(baseUrl);

var result = await client.postToUrl('/v1/chat/completions', 
    OpenAiChatCompletion()
      ..model = 'mixtral:8x22b'
      ..max_tokens = 50
      ..messages = [
        OpenAiMessage()
          ..role = 'user'
          ..content = "What's the capital of France?"
      ]);
```

### PHP

Include `servicestack/client` package in your projects `composer.json`:

:::copy
"servicestack/client": "^1.0"
:::

Download AI Server's PHP DTOs:

:::copy
`npx get-dtos php https://openai.servicestack.net`
:::

Call API by sending `OpenAiChatCompletion` Request DTO with JsonServiceClient:

```php
use ServiceStack\JsonServiceClient;
use dtos\OpenAiChatCompletion;
use dtos\OpenAiMessage;

$client = new JsonServiceClient(baseUrl);
$client->bearerToken = apiKey;

/** @var {OpenAiChatCompletionResponse} $result */
$result = $client->postUrl('/v1/chat/completions', 
    body: new OpenAiChatCompletion(
        model: "mixtral:8x22b",
        messages: [
            new OpenAiMessage(
                role: "user",
                content: "What's the capital of France?"
            )
        ],
        max_tokens: 50
    ));
```

### Java

Include `net.servicestack:client` package in your projects `build.gradle`:

:::copy
implementation 'net.servicestack:client:1.1.3'
:::

Download AI Server's Java DTOs:

:::copy
`npx get-dtos java https://openai.servicestack.net`
:::

Call API by sending `OpenAiChatCompletion` Request DTO with JsonServiceClient:

```java
import net.servicestack.client.*;
import java.util.Collections;

var client = new JsonServiceClient(baseUrl);

OpenAiChatResponse result = client.post("/v1/chat/completions", 
    new OpenAiChatCompletion()
        .setModel("mixtral:8x22b")
        .setMaxTokens(50)
        .setMessages(Utils.createList(new OpenAiMessage()
                .setRole("user")
                .setContent("What's the capital of France?")
        )),
    OpenAiChatResponse.class);
```

### Kotlin

Include `net.servicestack:client` package in your projects `build.gradle`:

:::copy
implementation 'net.servicestack:client:1.1.3'
:::

Download AI Server's Kotlin DTOs:

:::copy
`npx get-dtos kotlin https://openai.servicestack.net`
:::

Call API by sending `OpenAiChatCompletion` Request DTO with JsonServiceClient:

```kotlin
package myapp
import net.servicestack.client.*

val client = JsonServiceClient(baseUrl)

val result: OpenAiChatResponse = client.post("/v1/chat/completions", 
    OpenAiChatCompletion().apply {
        model = "mixtral:8x22b"
        messages = arrayListOf(OpenAiMessage().apply {
            role = "user"
            content = "What's the capital of France?"
        })
        maxTokens = 50
    }, 
    OpenAiChatResponse::class.java)
```

### Swift

Include `ServiceStack` package in your projects `Package.swift`

```swift
dependencies: [
    .package(url: "https://github.com/ServiceStack/ServiceStack.Swift.git", from: "6.0.5")
],
```

Download AI Server's Swift DTOs:

:::copy
`npx get-dtos swift https://openai.servicestack.net`
:::

Call API by sending `OpenAiChatCompletion` Request DTO with JsonServiceClient:

```swift
import Foundation
import ServiceStack

let client = JsonServiceClient(baseUrl:baseUrl)

let request = OpenAiChatCompletion()
request.model = "mixtral:8x22b"
let msg =  OpenAiMessage()
msg.role = "user"
msg.content = "What's the capital of France?"
request.messages = [msg]
request.max_tokens = 50

let result:OpenAiChatResponse = try await client.postAsync(
    "/v1/chat/completions", request:request)
```

### F#

Install the `ServiceStack.Client` NuGet package:

:::copy
`<PackageReference Include="ServiceStack.Client" Version="8.*" />`
:::

Download AI Server's F# DTOs with [x dotnet tool](/dotnet-tool):

:::copy
`x fsharp https://openai.servicestack.net`
:::

Call API by sending `OpenAiChatCompletion` Request DTO with `JsonApiClient`:

```fsharp
open ServiceStack
open ServiceStack.Text

let client = new JsonApiClient(baseUrl)

let result = client.Post<OpenAiChatCompletionResponse>("/v1/chat/completions", 
     OpenAiChatCompletion(
        Model = "mixtral:8x22b",
        Messages = ResizeArray [
            OpenAiMessage(
                Role = "user",
                Content = "What's the capital of France?"
            )
        ],
        MaxTokens = 50))
```

### VB.NET

Install the `ServiceStack.Client` NuGet package:

:::copy
`<PackageReference Include="ServiceStack.Client" Version="8.*" />`
:::

Download AI Server's VB.NET DTOs with [x dotnet tool](/dotnet-tool):

:::copy
`x vbnet https://openai.servicestack.net`
:::

Call API by sending `OpenAiChatCompletion` Request DTO with `JsonApiClient`:

```vb
Imports ServiceStack
Imports ServiceStack.Text

Dim client = New JsonApiClient(baseUrl)

Dim result = Await client.PostAsync(Of OpenAiChatResponse)(
    "/v1/chat/completions",
    New OpenAiChatCompletion() With {
        .Model = "mixtral:8x22b",
        .Messages = New List(Of OpenAiMessage) From {
            New OpenAiMessage With {
                .Role = "user",
                .Content = "What's the capital of France?"
            }
        },
        .MaxTokens = 50
    })
```


# AI Server API Usage
Source: https://docs.servicestack.net/ai-server/chat

AI Server provides a unified API to process requests for AI services to access LLMs, Image Generation, Transcription, and more. The API is designed to be simple to use and easy to integrate into your applications providing many supported languages and frameworks.

## Chat UI

AI Server's Chat UI lets upi send Open AI Chat requests with custom system prompts to any of its active LLMs:

<div class="not-prose">
<h3 class="text-4xl text-center text-indigo-800 pb-3"><span class="text-gray-300">https://localhost:5006</span>/Chat
</h3>
</div>

![](/img/pages/ai-server/uis/Chat.webp)

## Making a Chat Request

To make a chat request to AI Server, you can use the `/api/OpenAiChatCompletion` endpoint. This endpoint requires a `OpenAiChatCompletion` request DTO that contains a property matching the `OpenAI` API.

### Sync Open AI Chat Completion

::include ai-server/cs/ai-server-compatible-1.cs.md::

This request will generate a response from the `llama3:8b` model using the `system` and `user` messages provided. This will perform the operation synchronously, waiting for the response to be generated before returning it to the client.

Alternatively, you can call the same endpoint asynchronously by using the `/api/QueueOpenAiChatCompletion` endpoint. This will queue the request for processing and return a URL to check the status of the request and download the response when it's ready.

### Queued Open AI Chat Completion

::include ai-server/cs/queue-openai-chat-completion-1.cs.md::

Additional optional features on the request to enhance the usage of AI Server include:

- **RefId**: A unique identifier for the request specified by the client to more easily track the progress of the request.
- **Tag**: A tag to help categorize the request for easier tracking.

`RefId` and `Tag` are available on both synchronous and asynchronous requests, where as Queue requests also support:

- **ReplyTo**: A URL to send a POST request to when the request is complete.


## Open AI Chat with ReplyTo Callback

The Queued API also accepts a **ReplyTo Web Callback** for a more reliable push-based App integration
where responses are posted back to a custom URL Endpoint:

```csharp
var correlationId = Guid.NewGuid().ToString("N");
var response = client.Post(new QueueOpenAiChatCompletion
{
    //...
    ReplyTo = $"https://example.org/api/OpenAiChatResponseCallback?CorrelationId=${correlationId}"
});
```

Your callback can add any additional metadata on the callback to assist your App in correlating the response with 
the initiating request which just needs to contain the properties of the `OpenAiChatResponse` you're interested in
along with any metadata added to the callback URL, e.g:

```csharp
public class OpenAiChatResponseCallback : IPost, OpenAiChatResponse, IReturnVoid
{
    public Guid CorrelationId { get; set; }
}

public object Post(OpenAiChatResponseCallback request)
{
    // Handle OpenAiChatResponse callabck
}
```

Unless your callback API is restricted to only accept requests from your AI Server, you should include a 
unique Id like a `Guid` in the callback URL that can be validated against an initiating request to ensure 
the callback can't be spoofed.

## Using the AI Server Request DTOs with other OpenAI compatible APIs

One advantage of using AI Server is that it provides a common set of request DTOs in 11 different languages that are compatible with OpenAI's API. This allows you to switch between OpenAI and AI Server without changing your client code.
This means you can switch to using typed APIs in your preferred language with your existing service providers OpenAI compatible APIs, and optionally switch to AI Server when you're ready to self-host your AI services for better value.

::include ai-server/cs/open-ai-requests-1.cs.md::

This shows usage of the `OpenAiChat` request DTO directly with OpenAI's API using the ServiceStack `JsonApiClient`, so you get the benefits of using typed APIs in your preferred language with your existing service providers OpenAI compatible APIs.


# Text to Image
Source: https://docs.servicestack.net/ai-server/text-to-image

## Text to Image UI

AI Server's Text to Image UI lets send Text to Image requests to any of its active Comfy UI Agents Models, Diffusion
or DALL·E 3 API Providers:

<div class="not-prose">
    <h3 class="text-4xl text-center text-indigo-800 pb-3">
        <span class="text-gray-300">https://localhost:5006</span>/TextToImage
    </h3>
</div>

![](/img/pages/ai-server/uis/TextToImage.webp)

## Using Text to Image Endpoints

::include ai-server/endpoint-usage.md::

### Text to Image {#text-to-image}

::include ai-server/cs/text-to-image-1.cs.md::

### Queue Text to Image {#queue-text-to-image}

::include ai-server/cs/queue-text-to-image-1.cs.md::


# Image to Text
Source: https://docs.servicestack.net/ai-server/image-to-text

## Image to Text UI

AI Server's Image to Text UI lets you request image classifications from its active Comfy UI Agents:

<div class="not-prose">
    <h3 class="text-4xl text-center text-indigo-800 pb-3">
        <span class="text-gray-300">https://localhost:5006</span>/ImageToText
    </h3>
</div>

![](/img/pages/ai-server/uis/ImageToText.webp)

## Using Image to Text Endpoints

::include ai-server/endpoint-usage.md::

### Ollama Vision Models

If AI Server has access to any Ollama Vision Models (e.g. **gemma3:27b** or **mistral-small**), it can be used
instead to get information about the uploaded image:

 - `Model` - the ollama vision model to use
 - `Prompt` - vision model prompt

### Image to Text {#image-to-text}

::include ai-server/cs/image-to-text-1.cs.md::

### Queue Image to Text {#queue-image-to-text}

::include ai-server/cs/queue-image-to-text-1.cs.md::

:::info
Ensure that the ComfyUI Agent has the Florence 2 model downloaded and installed for the Image-To-Text functionality to work.
This can be done by setting the `DEFAULT_MODELS` environment variable in the `.env` file to include `image-to-text`
:::

## Support for Ollama Vision Models

By default [ImageToText](/ai-server/image-to-text) uses a purpose-specific **Florence 2 Vision model** with ComfyUI for its functionality which is capable of generating a very short description about an image, e.g:

> A woman sitting on the edge of a lake with a wolf

But with LLMs gaining multi modal capabilities and Ollama's recent support of Vision Models we can instead use popular
Open Source models like Google's **gemma3:27b** or Mistral's **mistral-small:24b** to extract information from images.

Both models are very capable vision models that's can provide rich detail about an image:

### Describe Image

<div class="not-prose mt-8 grid grid-cols-2 gap-4">
    <a class="block group border dark:border-gray-800 hover:border-indigo-700 dark:hover:border-indigo-700 flex flex-col justify-between" href="/img/pages/ai-server/image-to-text/gemma3-describe.png">
        <img class="p-2" src="/img/pages/ai-server/image-to-text/gemma3-describe.png" />
    </a>
    <a class="block group border dark:border-gray-800 hover:border-indigo-700 dark:hover:border-indigo-700 flex flex-col justify-between" href="/img/pages/ai-server/image-to-text/mistral-small-describe.png">
        <img class="p-2" src="/img/pages/ai-server/image-to-text/mistral-small-describe.png" />
    </a>
</div>

### Caption Image

Although our initial testing sees gemma being better at responding to a wide variety of different prompts, e.g:

<div class="not-prose mt-8 grid grid-cols-2 gap-4">
    <a class="block group border dark:border-gray-800 hover:border-indigo-700 dark:hover:border-indigo-700 flex flex-col justify-between" href="/img/pages/ai-server/image-to-text/gemma3-caption.png">
        <img class="p-2" src="/img/pages/ai-server/image-to-text/gemma3-caption.png" />
    </a>
    <a class="block group border dark:border-gray-800 hover:border-indigo-700 dark:hover:border-indigo-700 flex flex-col justify-between" href="/img/pages/ai-server/image-to-text/mistral-small-caption.png">
        <img class="p-2" src="/img/pages/ai-server/image-to-text/mistral-small-caption.png" />
    </a>
</div>

## Support OllamaGenerate Endpoint

To support Ollama's vision models AI Server added a new feature pipeline around
[Ollama's generate completion API](https://github.com/ollama/ollama/blob/main/docs/api.md#generate-a-completion):


- `ImageToText`
  - **Model** - Whether to use a Vision Model for the request
  - **Prompt** - Prompt for the vision model
- `OllamaGeneration`: Synchronous invocation of Ollama's Generate API
- `QueueOllamaGeneration`: Asynchronous or Web Callback invocation of Ollama's Generate API
- `GetOllamaGenerationStatus`: Get the generation status of an Ollama Generate API


# Image to Image
Source: https://docs.servicestack.net/ai-server/image-to-image

## Image to Image UI

AI Server's Image to Image UI lets you create custom Images from a blueprint image from its active Comfy UI Agents:

<div class="not-prose">
    <h3 class="text-4xl text-center text-indigo-800 pb-3">
        <span class="text-gray-300">https://localhost:5006</span>/ImageToImage
    </h3>
</div>

![](/img/pages/ai-server/uis/ImageToImage.webp)

## Using Image to Image Endpoints

::include ai-server/endpoint-usage.md::

### Image to Image {#image-to-image}

::include ai-server/cs/image-to-image-1.cs.md::

### Queue Image to Image {#queue-image-to-image}

::include ai-server/cs/queue-image-to-image-1.cs.md::


# Image with Mask
Source: https://docs.servicestack.net/ai-server/image-with-mask

## Using Image with Mask Endpoints

::include ai-server/endpoint-usage.md::

### Image with Mask {#image-with-mask}

::include ai-server/cs/image-with-mask-1.cs.md::

### Queue Image with Mask {#queue-image-with-mask}

::include ai-server/cs/queue-image-with-mask-1.cs.md::


# Image Upscale
Source: https://docs.servicestack.net/ai-server/image-upscale

## Image Upscale UI

AI Server's Image Upscale UI lets you use AI to 2x upscale and image from its active Comfy UI Agents:

<div class="not-prose">
    <h3 class="text-4xl text-center text-indigo-800 pb-3">
        <span class="text-gray-300">https://localhost:5006</span>/ImageUpscale
    </h3>
</div>

![](/img/pages/ai-server/uis/ImageUpscale.webp)

## Using Image Upscale Endpoints

::include ai-server/endpoint-usage.md::

### Image Upscale {#image-upscale}

::include ai-server/cs/image-upscale-1.cs.md::

### Queue Image Upscale {#queue-image-upscale}

::include ai-server/cs/queue-image-upscale-1.cs.md::

## Additional Functionality

AI Server also provides Image-To-Text generation using the ComfyUI Agent that utilizes the [Florence 2 model](https://huggingface.co/microsoft/Florence-2-base). The ComfyUI Agent must have this model downloaded and installed to support this functionality.


# Speech to Text
Source: https://docs.servicestack.net/ai-server/speech-to-text

AI Server can transcribe audio files to text using the Speech-to-Text provider. This is powered by the Whisper model and is hosted on your own ComfyUI Agent.

## Speech to Text UI

AI Server's Speech to Text UI lets you transcribe audio files from its active Comfy UI Agents:

<div class="not-prose">
    <h3 class="text-4xl text-center text-indigo-800 pb-3">
        <span class="text-gray-300">https://localhost:5006</span>/SpeechToText
    </h3>
</div>

![](/img/pages/ai-server/uis/SpeechToText.webp)

## Using Speech to Text Endpoints

::include ai-server/endpoint-usage.md::

### Speech to Text {#speech-to-text}

The Speech to Text endpoint converts audio input into text. It provides two types of output:

1. Text with timestamps: JSON format with `start` and `end` timestamps for each segment.
2. Plain text: The full transcription without timestamps.

These outputs are returned in the `TextOutputs` array, where the JSON will need to be parsed to extract the text and timestamps.

::include ai-server/cs/speech-to-text-1.cs.md::

### Queue Speech to Text {#queue-speech-to-text}

For longer audio files or when you want to process the request asynchronously, you can use the Queue Speech to Text endpoint.

::include ai-server/cs/queue-speech-to-text-1.cs.md::


# Text to Speech
Source: https://docs.servicestack.net/ai-server/text-to-speech

## Text to Speech UI

AI Server's Text to Speech UI lets you create audio files from its active Comfy UI Agents or Open AI Text to Speech models:

<div class="not-prose">
    <h3 class="text-4xl text-center text-indigo-800 pb-3">
        <span class="text-gray-300">https://localhost:5006</span>/TextToSpeech
    </h3>
</div>

![](/img/pages/ai-server/uis/TextToSpeech.webp)

## Using Text to Speech Endpoints

::include ai-server/endpoint-usage.md::

## Text to Speech {#text-to-speech}

The Text to Speech endpoint converts text input into audio output.

::include ai-server/cs/text-to-speech-1.cs.md::

## Queue Text to Speech {#queue-text-to-speech}

For generating longer audio files or when you want to process the request asynchronously, you can use the Queue Text to Speech endpoint.

::include ai-server/cs/queue-text-to-speech-1.cs.md::

## Comfy UI

The ComfyUI Agent uses PiperTTS to generate the audio files. You can configure download the necessary models by setting the `DEFAULT_MODELS` in the `.env` file to include **text-to-speech** for your ComfyUI Agent where
PiperTTS via ComfyUI Agent uses the preconfigured `lessac` model.

Available Comfy UI Models:
 
 - `text-to-speech` - Default (Lessic)
 - `lessac` - [Piper](https://github.com/rhasspy/piper) TTS using the US English **Lessac** "high" voice model 

## Open AI

If you have included an `OPENAI_API_KEY` in your `.env` file, you can also use the OpenAI API to generate audio files from text which by default uses their `alloy` voice model.

Available Open AI Model [Voice Options](https://platform.openai.com/docs/guides/text-to-speech/voice-options):
 
 - `text-to-speech` - Default (Alloy)
 - `tts-alloy` - Alloy
 - `tts-echo` - Echo
 - `tts-fable` - Fable
 - `tts-onyx` - Onyx
 - `tts-nova` - Nova
 - `tts-shimmer` - Shimmer


# Image Transform Endpoints
Source: https://docs.servicestack.net/ai-server/transform/image

AI Server incorporates various image processing capabilities. It wraps some common operations into easier-to-use endpoints, such as:

- **Crop Image** - Crop an image to a specific size
- **Convert Image** - Convert an image to a different format
- **Scale Image** - Scale an image to a different resolution
- **Watermark Image** - Add a watermark to an image

:::info
These operations are processed on the AI Server itself, rather than an external API or agent.
:::

## Using Image Endpoints

These endpoints are used in a similar way to the other AI Server endpoints, e.g., you can provide a RefId and Tag to help categorize the request, and for Queue requests, you can provide a ReplyTo URL to send a POST request to when the request is complete.

### Crop Image {#crop-image}

::include ai-server/cs/crop-image-1.cs.md::

### Queue Crop Image {#crop-image}

::include ai-server/cs/queue-crop-image-1.cs.md::

### Convert Image {#convert-image}

::include ai-server/cs/convert-image-1.cs.md::

### Queue Convert Image {#convert-image}

::include ai-server/cs/queue-convert-image-1.cs.md::

### Scale Image {#scale-image}

::include ai-server/cs/scale-image-1.cs.md::

### Queue Scale Image {#scale-image}

::include ai-server/cs/queue-scale-image-1.cs.md::

### Watermark Image {#watermark-image}

::include ai-server/cs/watermark-image-1.cs.md::

### Queue Watermark Image {#watermark-image}

::include ai-server/cs/queue-watermark-image-1.cs.md::


# Video Transform Endpoints
Source: https://docs.servicestack.net/ai-server/transform/video

Also incorporated into the ComfyUI Agent is FFmpeg, which can be used to process videos. AI Server wraps some common operations into easier-to-use endpoints, such as:

- **Crop Video** - Crop a video to a specific size
- **Convert Video** - Convert a video to a different format
- **Scale Video** - Scale a video to a different resolution
- **Watermark Video** - Add a watermark to a video
- **Trim Video** - Trim a video to a specific length

## Using Video Endpoints

These endpoints are used in a similar way to the other AI Server endpoints, e.g., you can provide a RefId and Tag to help categorize the request, and for Queue requests, you can provide a ReplyTo URL to send a POST request to when the request is complete.

### Crop Video {#crop-video}

::include ai-server/cs/crop-video-1.cs.md::

### Queue Crop Video {#crop-video}

::include ai-server/cs/queue-crop-video-1.cs.md::

### Convert Video {#convert-video}

::include ai-server/cs/convert-video-1.cs.md::

### Queue Convert Video {#convert-video}

::include ai-server/cs/queue-convert-video-1.cs.md::

### Scale Video {#scale-video}

::include ai-server/cs/scale-video-1.cs.md::

### Queue Scale Video {#scale-video}

::include ai-server/cs/queue-scale-video-1.cs.md::

### Watermark Video {#watermark-video}

::include ai-server/cs/watermark-video-1.cs.md::

### Queue Watermark Video {#watermark-video}

::include ai-server/cs/queue-watermark-video-1.cs.md::

### Trim Video {#trim-video}

::include ai-server/cs/trim-video-1.cs.md::

### Queue Trim Video {#trim-video}

::include ai-server/cs/queue-trim-video-1.cs.md::

:::info
These operations depend on support from FFmpeg, which comes installed with the ComfyUI Agent.
Limitations on encoders, decoders, and filters may apply.
:::


# Service Clients Authentication
Source: https://docs.servicestack.net/auth/client-auth

## Authenticating with JavaScript or TypeScript Service Clients

Typically when using ServiceStack's **@servicestack/client** `JsonServiceClient` it will utilize the browser's authenticated
cookies where you'll be able to make authenticated requests as the currently Authenticated User in your Application: 

```ts
import { JsonServiceClient } from "@servicestack/client";

const client = new JsonServiceClient()

// Uses browser's authenticated cookies by default
const api = await client.api(new Secured())
```

Alternatively you can also authenticate with JavaScript by sending an  `Authenticate` Request, e.g:

```ts
import { JsonServiceClient } from "@servicestack/client";

const client = new JsonServiceClient()

const apiAuth = await client.api(new Authenticate({ provider:'credentials', userName, password }))

if (apiAuth.suceeded) {
    const api = await client.api(new Secured())
}
```

As the cookies are shared with the browser, this will also authenticate the browser session where you'll be able to 
view protected Blazor, MVC or Razor Pages after successful authentication.

## Authenticating with C#/.NET Service Clients

On the client you can use the [C#/.NET Service Clients](/csharp-client) to easily consume your authenticated Services.

You can authenticate against your registered **Credentials** Auth Provider by submitting a populated `Authenticate` Request DTO, e.g:

```csharp
var client = new JsonServiceClient(BaseUrl);

var apiAuth = await client.ApiAsync(new Authenticate {
    provider = "credentials", 
    UserName = userName,
    Password = password,
});

if (apiAuth.Succeeded) 
{
    //...
}
```

If authentication was successful the Service Client `client` instance will be populated with authenticated session cookies 
which then allows calling Authenticated services, e.g:

```csharp
var api = await client.ApiAsync(new GetActiveUserId());
```

If you've also registered the `BasicAuthProvider` it will enable your Services to accept [HTTP Basic Authentication](https://en.wikipedia.org/wiki/Basic_access_authentication) 
which is built-in the Service Clients that you can populate on the Service Client with:

```csharp
client.UserName = userName;
client.Password = password
```

Which will also let you access protected Services, e.g:

```csharp
var response = client.Get(new GetActiveUserId());
```

Although behind-the-scenes it ends up making 2 requests, 1st request sends a normal request which will get rejected with 
a `401 Unauthorized` and if the Server indicates it has the `BasicAuthProvider` enabled it will resend the request with 
the HTTP Basic Auth credentials.

You could instead save the latency of the additional auth challenge request by specifying the client should always send 
the Basic Auth with every request:

```csharp
client.AlwaysSendBasicAuthHeader = true;
```

## Authenticating with HTTP

To Authenticate against your registered **Credentials** Auth Provider you can **POST** a raw JSON body:

**POST** localhost:60339/auth/credentials?format=json

```json
{
    "UserName": "admin",
    "Password": "p@55wOrd",
    "RememberMe": true
}
```


# Restricting Services
Source: https://docs.servicestack.net/auth/restricting-services

You can change the Visibility and Access restrictions on any service using the `[Restrict]` attribute. This is a class based attribute and should be placed on your Service class.
Visibility affects whether or not the service shows up on the public `/metadata` pages, whilst access restrictions limits the accessibility of your services. 

## Named Configurations

The Restrict attribute includes a number of Named configurations for common use-cases. E.g You can specify a Service should only be available from your local machine with:

```csharp
[Restrict(LocalhostOnly = true)]
public class LocalAdmin { }
```

Which ensures access to this service is only allowed from localhost clients and the details of this service will only be visible on `/metadata` pages that are viewed locally.

This is equivalent to using the underlying granular form of specifying individual `RequestAttributes`, e.g:

```csharp
[Restrict(AccessTo = RequestAttributes.Localhost, VisibilityTo = RequestAttributes.Localhost)]
public class LocalAdmin { }
```

There are many more named configurations available. You can use **VisibleInternalOnly** to only have a service listed on internally viewed `/metadata` pages with:

```csharp
[Restrict(VisibleInternalOnly = true)]
public class InternalAdmin { }
```

Services can be restricted on any EndpointAttribute, e.g. to ensure this service is only called by XML clients, do:

```csharp
[Restrict(RequestAttributes.Xml)]
public class XmlOnly { }
```

## Restriction Combinations 

Likewise you can add any combination of Endpoint Attributes together, E.g. this restricts access to service to Internal JSON clients only:

```csharp
[Restrict(RequestAttributes.InternalNetworkAccess | RequestAttributes.Json)]
public class JsonInternalOnly { }
```

## Multiple restriction scenarios

It also supports multiple restriction scenarios, E.g. This service is only accessible by **internal JSON** clients or **External XML** clients:

```csharp
[Restrict(
    RequestAttributes.InternalNetworkAccess | RequestAttributes.Json,
    RequestAttributes.External | RequestAttributes.Xml)]
public class JsonInternalOrXmlExternalOnly { }
```

A popular configuration that takes advantage of this feature would be to only allow HTTP plain-text traffic from Internal Networks and only allow external access via secure HTTPS, which you can enforce with:

```csharp
[Restrict(RequestAttributes.InSecure | RequestAttributes.InternalNetworkAccess,
          RequestAttributes.Secure   | RequestAttributes.External)]
public class InternalHttpAndExternalHttps { }
```

## Hiding Services from Metadata

You can use the `[Exclude*]` attributes to hide Services from appearing in your public metadata services:

```csharp
[ExcludeMetadata]
public class InternalService : IReturnVoid {}

[Exclude(Feature.Metadata | Feature.Soap)]
public class InternalService : IReturnVoid {}
```

## Restricting built-in Services

In addition to statically annotating classes, you can also add .NET Attributes at runtime to restrict Services 
you don't control. So to only allow built-in Services to be visible from **localhost** requests you can add 
restriction attributes to Request DTO's in your AppHost with:

```csharp
typeof(AssignRoles)
    .AddAttributes(new RestrictAttribute { VisibleLocalhostOnly = true });
typeof(UnAssignRoles)
    .AddAttributes(new RestrictAttribute { VisibleLocalhostOnly = true });
```

Or to hide it for all requests you can set the visibility to none:

```csharp
typeof(AssignRoles)
    .AddAttributes(new RestrictAttribute { VisibilityTo=RequestAttributes.None });
typeof(UnAssignRoles)
    .AddAttributes(new RestrictAttribute { VisibilityTo=RequestAttributes.None });
```

Note they'll still be shown in development mode when `Debug=true` which is automatically enabled for 
**Debug** builds, to simulate what it would look like in a release build you can set it to `false`, e.g:

```csharp
SetConfig(new HostConfig {
    DebugMode = false
});
```


# Encrypted Messaging
Source: https://docs.servicestack.net/auth/encrypted-messaging

One of the benefits of adopting a message-based design is being able to easily layer functionality and generically add value to all Services, we've seen this recently with [Auto Batched Requests](/auto-batched-requests) which automatically enables each Service to be batched and executed in a single HTTP Request. Similarly the new Encrypted Messaging feature 
enables a secure channel for all Services (inc Auto Batched Requests :) offering protection to clients who can now easily send and receive encrypted messages over unsecured HTTP!

## Encrypted Messaging Overview

![](https://raw.githubusercontent.com/ServiceStack/Assets/master/img/release-notes/encrypted-messaging.png)

### Configuration

Encrypted Messaging support is enabled by registering the plugin:

```csharp
Plugins.Add(new EncryptedMessagesFeature {
    PrivateKeyXml = ServerRsaPrivateKeyXml
});
```

Where `PrivateKeyXml` is the Servers RSA Private Key Serialized as XML. 

## Generate a new Private Key

If you don't have an existing one, a new one can be generated with:

```csharp
var rsaKeyPair = RsaUtils.CreatePublicAndPrivateKeyPair();
string ServerRsaPrivateKeyXml = rsaKeyPair.PrivateKey;
```

Once generated, it's important the Private Key is kept confidential as anyone with access will be able to decrypt 
the encrypted messages! Whilst most [obfuscation efforts are ultimately futile](http://stackoverflow.com/a/6018247/85785) the goal should be to contain the private key to your running Web Application, limiting access as much as possible.

Once registered, the EncryptedMessagesFeature enables the 2 Services below:

 - `GetPublicKey` - Returns the Serialized XML of your Public Key (extracted from the configured Private Key)
 - `EncryptedMessage` - The Request DTO which encapsulates all encrypted Requests (can't be called directly)

## Giving Clients the Public Key

To communicate clients need access to the Server's Public Key, it doesn't matter who has accessed the Public Key only that clients use the **real** Servers Public Key. It's therefore not advisable to download the Public Key over unsecure `http://` where traffic can potentially be intercepted and the key spoofed, subjecting them to a [Man-in-the-middle attack](https://en.wikipedia.org/wiki/Man-in-the-middle_attack). 

It's safer instead to download the public key over a trusted `https://` url where the servers origin is verified by a trusted [CA](https://en.wikipedia.org/wiki/Certificate_authority). Sharing the Public Key over Dropbox, Google Drive, OneDrive or other encrypted channels are also good options.

Since `GetPublicKey` is just a ServiceStack Service it's easily downloadable using a Service Client:

```csharp
var client = new JsonApiClient(BaseUrl);
string publicKeyXml = client.Get(new GetPublicKey());
```

If the registered `EncryptedMessagesFeature.PublicKeyPath` has been changed from its default `/publickey`, it can be dowloaded with:

```csharp
string publicKeyXml = client.Get<string>("/my-publickey"); //or with HttpUtils
string publicKeyXml = BaseUrl.CombineWith("/my-publickey").GetStringFromUrl();
```

::: info
To help with verification the SHA256 Hash of the PublicKey is returned in `X-PublicKey-Hash` HTTP Header
:::

## Encrypted Service Client

Once they have the Server's Public Key, clients can use it to get an `EncryptedServiceClient` via the `GetEncryptedClient()` extension method on `JsonServiceClient` or new `JsonHttpClient`, e.g:

```csharp
var client = new JsonApiClient(BaseUrl);
IEncryptedClient encryptedClient = client.GetEncryptedClient(publicKeyXml);
```

Once configured, clients have access to the familiar typed Service Client API's and productive workflow they're used to with the generic Service Clients, sending typed Request DTO's and returning the typed Response DTO's - rendering the underlying encrypted messages a transparent implementation detail:

```csharp
HelloResponse response = encryptedClient.Send(new Hello { Name = "World" });
response.Result.Print(); //Hello, World!
```

REST Services Example:

```csharp
HelloResponse response = encryptedClient.Get(new Hello { Name = "World" });
```

Auto-Batched Requests Example:

```csharp
var requests = new[] { "Foo", "Bar", "Baz" }.Map(x => 
    new HelloSecure { Name = x });
var responses = encryptedClient.SendAll(requests);
```

When using the `IEncryptedClient`, the entire Request and Response bodies are encrypted including Exceptions which continue to throw a populated `WebServiceException`:

```csharp
try
{
    var response = encryptedClient.Send(new Hello());
}
catch (WebServiceException ex)
{
    ex.ResponseStatus.ErrorCode.Print(); //= ArgumentNullException
    ex.ResponseStatus.Message.Print();   //= Value cannot be null. 
}
```

### Authentication with Encrypted Messaging

Many encrypted messaging solutions use Client Certificates which Servers can use to cryptographically verify a client's identity - providing an alternative to HTTP-based Authentication. We've decided against using this as it would've forced an opinionated implementation and increased burden of PKI certificate management and configuration onto Clients and Servers - reducing the applicability and instant utility of this feature.

We can instead leverage the existing Session-based Authentication Model in ServiceStack letting clients continue to use the existing Auth functionality and Auth Providers they're already used to, e.g:

```csharp
var authResponse = encryptedClient.Send(new Authenticate {
    provider = CredentialsAuthProvider.Name,
    UserName = "test@gmail.com",
    Password = "p@55w0rd",
});
```

Encrypted Messages have their cookies stripped so they're no longer visible in the clear which minimizes their exposure to Session hijacking. This does pose the problem of how we can call authenticated Services if the encrypted HTTP Client is no longer sending Session Cookies? 

Without the use of clear-text Cookies or HTTP Headers there's no longer an *established Authenticated Session* for the `encryptedClient` to use to make subsequent Authenticated requests. What we can do  instead is pass the Session Id in the encrypted body for Request DTO's that implement the new `IHasSessionId` interface, e.g:

```csharp
[Authenticate]
public class HelloAuthenticated : IReturn<HelloAuthenticatedResponse>, 
    IHasSessionId
{
    public string SessionId { get; set; }
    public string Name { get; set; }
}

var response = encryptedClient.Send(new HelloAuthenticated {
    SessionId = authResponse.SessionId,
    Name = "World"
});
```

Here we're injecting the returned Authenticated `SessionId` to access the `[Authenticate]` protected Request DTO. However remembering to do this for every authenticated request can get tedious, a nicer alternative is just setting it once on the `encryptedClient` which will then use it to automatically populate any `IHasSessionId` Request DTO's:

```csharp
encryptedClient.SessionId = authResponse.SessionId;

var response = encryptedClient.Send(new HelloAuthenticated {
    Name = "World"
});
```

::: info
This feature is now supported in **all Service Clients**
:::

### Combined Authentication Strategy

Another potential use-case is to only use Encrypted Messaging when sending any sensitive information and the normal Service Client for other requests. In which case we can Authenticate and send the user's password with the `encryptedClient`:

```csharp
var authResponse = encryptedClient.Send(new Authenticate {
    provider = CredentialsAuthProvider.Name,
    UserName = "test@gmail.com",
    Password = "p@55w0rd",
});
```

But then fallback to using the normal `IServiceClient` for subsequent requests. But as the `encryptedClient` doesn't receive cookies we'd need to set it explicitly on the client ourselves with:

```csharp
client.SetSessionId(authResponse.SessionId);

//Equivalent to:
client.SetCookie("ss-id", authResponse.SessionId);
```

After which the ServiceClient "establishes an authenticated session" and can be used to make Authenticated requests, e.g:

```csharp
var response = await client.GetAsync(new HelloAuthenticated { Name = "World" });
```

### BearerToken in Request DTOs

Similar to the `IHasSessionId` interface Request DTOs can also implement `IHasBearerToken` to send Bearer Tokens as an alternative for sending them in HTTP Headers or Cookies.

This lets you authenticate with Auth Providers like [API Key](/auth/api-key-authprovider) and [JWT](/auth/jwt-authprovider) in [Encrypted Messaging](/auth/encrypted-messaging) requests, e.g:

```csharp
public class Secure : IHasBearerToken
{
    public string BearerToken { get; set; }
    public string Name { get; set; }
}

IEncryptedClient encryptedClient = client.GetEncryptedClient(publicKey);
var response = encryptedClient.Get(new Secure { BearerToken = apiKey, Name = "World" });
```

Where it will be embedded and encrypted along with all content in the Request DTO so it can be sent securely over an unsecured HTTP Request.

Alternatively you can set the `BearerToken` property on the `IEncryptedClient` once where it will automatically populate all Request DTOs 
that implement `IHasBearerToken`, e.g:

```csharp
encryptedClient.BearerToken = apiKey;

var response = encryptedClient.Get(new Secure { Name = "World" });
```

### RSA and AES Hybrid Encryption verified with HMAC SHA-256

The Encrypted Messaging Feature follows a [Hybrid Cryptosystem](https://en.wikipedia.org/wiki/Hybrid_cryptosystem) 
which uses RSA Public Keys for [Asymmetric Encryption](https://en.wikipedia.org/wiki/Public-key_cryptography) 
combined with the performance of AES [Symmetric Encryption](https://en.wikipedia.org/wiki/Symmetric-key_algorithm) 
making it suitable for encrypting large message payloads. The authenticity of Encrypted Data are then verified 
with HMAC SHA-256, essentially following an [Encrypt-then-MAC strategy](http://crypto.stackexchange.com/a/205/25652). 

The key steps in the process are outlined below:

  1. Client creates a new `IEncryptedClient` configured with the Server **Public Key**
  2. Client uses the `IEncryptedClient` to create a EncryptedMessage Request DTO:
     1. Generates a new AES 256bit/CBC/PKCS7 Crypt Key **(Kc)**, Auth Key **(Ka)** and **IV**
     2. Encrypts Crypt Key **(Kc)**, Auth Key **(Ka)** with Servers Public Key padded with OAEP = **(Kc+Ka+P)e**
     3. Authenticates **(Kc+Ka+P)e** with **IV** using HMAC SHA-256 = **IV+(Kc+Ka+P)e+Tag**
     4. Serializes Request DTO to JSON packed with current `Timestamp`, `Verb` and `Operation` = **(M)**
     5. Encrypts **(M)** with Crypt Key **(Kc)** and **IV** = **(M)e**
     6. Authenticates **(M)e** with Auth Key **(Ka)** and **IV** = **IV+(M)e+Tag**
     7. Creates `EncryptedMessage` DTO with Servers `KeyId`, **IV+(Kc+Ka+P)e+Tag** and **IV+(M)e+Tag**
  3. Client uses the `IEncryptedClient` to send the populated `EncryptedMessage` to the remote Server

On the Server, the `EncryptedMessagingFeature` Request Converter processes the `EncryptedMessage` DTO:

  1. Uses Private Key identified by **KeyId** or the current Private Key if **KeyId** wasn't provided
     1. Request Converter Extracts **IV+(Kc+Ka+P)e+Tag** into **IV** and **(Kc+Ka+P)e+Tag**
     2. Decrypts **(Kc+Ka+P)e+Tag** with Private Key into **(Kc)** and **(Ka)**
     3. The **IV** is checked against the nonce Cache, verified it's never been used before, then cached
     4. The **IV+(Kc+Ka+P)e+Tag** is verified it hasn't been tampered with using Auth Key **(Ka)**
     5. The **IV+(M)e+Tag** is verified it hasn't been tampered with using Auth Key **(Ka)**
     6. The **IV+(M)e+Tag** is decrypted using Crypt Key **(Kc)** = **(M)**
     7. The **timestamp** is verified it's not older than `EncryptedMessagingFeature.MaxRequestAge`
     8. Any expired nonces are removed. (The **timestamp** and **IV** are used to prevent replay attacks)
     9. The JSON body is deserialized and resulting **Request DTO** returned from the Request Converter
  2. The converted **Request DTO** is executed in ServiceStack's Request Pipeline as normal
  3. The **Response DTO** is picked up by the EncryptedMessagingFeature **Response Converter**:
     1. Any **Cookies** set during the Request are removed
     2. The **Response DTO** is serialized with the **AES Key** and returned in an `EncryptedMessageResponse`
  4. The `IEncryptedClient` decrypts the `EncryptedMessageResponse` with the **AES Key**
     1. The **Response DTO** is extracted and returned to the caller

A visual of how this all fits together in captured in the high-level diagram below:

![](https://raw.githubusercontent.com/ServiceStack/Assets/master/img/release-notes/encrypted-messaging.png)

 - Components in **Yellow** show the encapsulated Encrypted Messaging functionality where all encryption and decryption is performed
 - Components in **Blue** show Unencrypted DTO's
 - Components in **Green** show Encrypted content:
    - The AES Keys and IV in **Dark Green** is encrypted by the client using the Server's Public Key
    - The EncryptedRequest in **Light Green** is encrypted with a new AES Key generated by the client on each Request
 - Components in **Dark Grey** depict existing ServiceStack functionality where Requests are executed as normal through the [Service Client](/csharp-client) and [Request Pipeline](/order-of-operations)

All Request and Response DTO's get encrypted and embedded in the `EncryptedMessage` and `EncryptedMessageResponse` DTO's below:

```csharp
public class EncryptedMessage : IReturn<EncryptedMessageResponse>
{
    public string KeyId { get; set; }
    public string EncryptedSymmetricKey { get; set; }
    public string EncryptedBody { get; set; }
}

public class EncryptedMessageResponse
{
    public string EncryptedBody { get; set; }
}
```

The diagram also expands the `EncryptedBody` Content containing the **EncryptedRequest** consisting of the following parts:

 - **Timestamp** - Unix Timestamp of the Request
 - **Verb** - Target HTTP Method
 - **Operation** - Request DTO Name
 - **JSON** - Request DTO serialized as JSON

### Support for versioning Private Keys with Key Rotations

One artifact visible in the above process was the use of a `KeyId`. This is a human readable string used 
to identify the Servers Public Key using the first 7 characters of the Public Key Modulus 
(visible when viewing the Private Key serialized as XML). 
This is automatically sent by `IEncryptedClient` to tell the `EncryptedMessagingFeature` which Private Key 
should be used to decrypt the AES Crypt and Auth Keys.

By supporting multiple private keys, the Encrypted Messaging feature allows the seamless transition to a 
new Private Key without affecting existing clients who have yet to adopt the latest Public Key. 

Transitioning to a new Private Key just involves taking the existing Private Key and adding it to the 
`FallbackPrivateKeys` collection whilst introducing a new Private Key, e.g:

```csharp
Plugins.Add(new EncryptedMessagesFeature
{
    PrivateKey = NewPrivateKey,
    FallbackPrivateKeys = {
        PreviousKey2015,
        PreviousKey2014,
    },
});
```

### Why Rotate Private Keys?

Since anyone who has a copy of the Private Key can decrypt encrypted messages, rotating the private key clients
use limits the amount of exposure an adversary who has managed to get a hold of a compromised private key has. 
i.e. if the current Private Key was somehow compromised, an attacker with access to the encrypted 
network packets will be able to read each message sent that was encrypted with the compromised private key 
up until the Server introduces a new Private Key which clients switches over to.

### Source Code

 - The Client implementation is available in [EncryptedServiceClient.cs](https://github.com/ServiceStack/ServiceStack/blob/master/src/ServiceStack.Client/EncryptedServiceClient.cs)
 - The Server implementation is available in [EncryptedMessagesFeature.cs](https://github.com/ServiceStack/ServiceStack/blob/master/src/ServiceStack/EncryptedMessagesFeature.cs)
 - The Crypto Utils used are available in the [RsaUtils.cs](https://github.com/ServiceStack/ServiceStack/blob/3af2526d2f710576a9764d22501af428e85315cb/src/ServiceStack.Client/CryptUtils.cs#L31) and [AesUtils.cs](https://github.com/ServiceStack/ServiceStack/blob/3af2526d2f710576a9764d22501af428e85315cb/src/ServiceStack.Client/CryptUtils.cs#L198)
 - Tests are available in [EncryptedMessagesTests.cs](https://github.com/ServiceStack/ServiceStack/blob/master/tests/ServiceStack.WebHost.Endpoints.Tests/UseCases/EncryptedMessagesTests.cs)


# ASP.NET Core Identity Auth
Source: https://docs.servicestack.net/auth/identity-auth

### ASP.NET Core Identity Auth now used in new Integrated Auth projects

ASP.NET Core Identity Auth is the default Auth Model adopted in new ServiceStack projects which closely follows the same 
approach as the Microsoft Project Template it integrates ServiceStack with, e.g. the .NET 8
**Blazor** and **Blazor Vue** project templates adopts the exact same Auth configuration as Microsoft's default Blazor Project 
Template configured with **Individual** Identity Auth, likewise with the **Bootstrap** and **Tailwind** styled **MVC** and 
**Razor Pages** templates.

You can find ServiceStack Integrated Identity Auth Templates for each of ASP.NET Core's major Blazor, Razor Pages and MVC 
Project Templates:

<div class="not-prose mx-auto px-8">
  <h3 id="identityauth-template" class="mb-4 text-4xl tracking-tight font-extrabold text-gray-900">
      Create a Project with ASP.NET Identity Auth
  </h3>
  <identity-auth-templates></identity-auth-templates>
</div>

### Identity Auth Template Live Demos

For a quick preview of what these look like, checkout out their Internet Hosted Live Demos:

<div class="not-prose mt-8 grid grid-cols-2 gap-4">
    <a class="block group border dark:border-gray-800 hover:border-indigo-700 dark:hover:border-indigo-700 flex flex-col justify-between" href="https://blazor.web-templates.io">
        <img class="p-2" src="https://raw.githubusercontent.com/ServiceStack/Assets/master/csharp-templates/blazor.png">
        <div class="bg-gray-50 dark:bg-gray-800 text-gray-600 dark:text-gray-300 font-semibold group-hover:bg-indigo-700 group-hover:text-white text-center py-2">blazor.web-templates.io</div>
    </a>
    <a class="block group border dark:border-gray-800 hover:border-indigo-700 dark:hover:border-indigo-700" href="https://blazor-vue.web-templates.io">
        <div style="max-height:350px;overflow:hidden">
        <img class="p-2" src="https://raw.githubusercontent.com/ServiceStack/Assets/master/csharp-templates/blazor-vue.png"></div>
        <div class="bg-gray-50 dark:bg-gray-800 text-gray-600 dark:text-gray-300 font-semibold group-hover:bg-indigo-700 group-hover:text-white text-center py-2">blazor-vue.web-templates.io</div>
    </a>
    <a class="block group border dark:border-gray-800 hover:border-indigo-700 dark:hover:border-indigo-700" href="https://blazor-wasm.web-templates.io">
        <div style="max-height:350px;overflow:hidden">
        <img class="p-2" src="https://raw.githubusercontent.com/ServiceStack/Assets/master/csharp-templates/blazor-wasm.png"></div>
        <div class="bg-gray-50 dark:bg-gray-800 text-gray-600 dark:text-gray-300 font-semibold group-hover:bg-indigo-700 group-hover:text-white text-center py-2">blazor-wasm.web-templates.io</div>
    </a>
    <a class="block group border dark:border-gray-800 hover:border-indigo-700 dark:hover:border-indigo-700" href="https://razor.web-templates.io">
        <div style="max-height:350px;overflow:hidden">
        <img class="p-2" src="https://raw.githubusercontent.com/ServiceStack/Assets/master/csharp-templates/razor.png"></div>
        <div class="bg-gray-50 dark:bg-gray-800 text-gray-600 dark:text-gray-300 font-semibold group-hover:bg-indigo-700 group-hover:text-white text-center py-2">razor.web-templates.io</div>
    </a>
    <a class="block group border dark:border-gray-800 hover:border-indigo-700 dark:hover:border-indigo-700" href="https://mvc.web-templates.io">
        <div style="max-height:350px;overflow:hidden">
        <img class="p-2" src="https://raw.githubusercontent.com/ServiceStack/Assets/master/csharp-templates/mvc.png"></div>
        <div class="bg-gray-50 dark:bg-gray-800 text-gray-600 dark:text-gray-300 font-semibold group-hover:bg-indigo-700 group-hover:text-white text-center py-2">mvc.web-templates.io</div>
    </a>
    <a class="block group border dark:border-gray-800 hover:border-indigo-700 dark:hover:border-indigo-700" href="https://razor-bootstrap.web-templates.io">
        <div style="max-height:350px;overflow:hidden">
        <img class="p-2" src="https://raw.githubusercontent.com/ServiceStack/Assets/master/csharp-templates/razor-bootstrap.png"></div>
        <div class="bg-gray-50 dark:bg-gray-800 text-gray-600 dark:text-gray-300 font-semibold group-hover:bg-indigo-700 group-hover:text-white text-center py-2">razor-bootstrap.web-templates.io</div>
    </a>
</div>


The configuration and source code for the above projects are a good reference for how to configure ServiceStack with
Identity Auth in your own projects:

- [blazor](https://github.com/NetCoreTemplates/blazor)
- [blazor-vue](https://github.com/NetCoreTemplates/blazor-vue)
- [blazor-wasm](https://github.com/NetCoreTemplates/blazor-wasm)
- [razor](https://github.com/NetCoreTemplates/razor)
- [mvc](https://github.com/NetCoreTemplates/mvc)
- [razor-bootstrap](https://github.com/NetCoreTemplates/razor-bootstrap)
- [mvc-bootstrap](https://github.com/NetCoreTemplates/mvc-bootstrap)

The **Bootstrap** versions use same Individual Identity Auth Pages that Microsoft's **Razor Pages** and **MVC** templates use,
whilst the **Tailwind** versions have been enhanced to use **Tailwind CSS** instead of Bootstrap,
includes a **visual QR Code** implementation that was missing and includes an
`IEmailSender` SMTP solution that's easily enabled via Configuration to use your preferred **SMTP Server**.

### Migrating to ASP.NET Core Identity Auth

Migrating from ServiceStack Auth to Identity Auth should be relatively straight-forward as ServiceStack uses a compatible
Identity v2 password hashing format, which should let you migrate your users to Identity Auth without them noticing.

## ServiceStack's Identity Auth Integration

ServiceStack's Identity Auth integration is focused on high compatibility so existing ServiceStack Customers
require minimal effort to migrate existing code bases to use the new Identity Auth integration, despite Identity Auth
being an entirely different Auth Provider model and implementation.

It does this by retaining a lot of the existing user-facing Authentication and Session abstractions that ServiceStack APIs
use for Authorization as well as existing endpoints and Request/Response DTOs that ServiceStack Clients use to Authenticate,
but replace their internal implementation to use ASP.NET Identity Auth instead.

The new Identity Auth integration is contained in the .NET 6+ **ServiceStack.Extensions** NuGet package:

```xml
<PackageReference Include="ServiceStack.Extensions" Version="8.*" />
```

Which at a minimum lets you configure ServiceStack to use Identity Auth by simply registering the existing `AuthFeature`
plugin with the Application's custom EF `ApplicationUser` Data Model:

```csharp
Plugins.Add(new AuthFeature(IdentityAuth.For<ApplicationUser>()));
```

It requires minimal configuration as all Authorization is configured using ASP.NET Core's
standard APIs, any configuration in this plugin is then just used to customize Identity Auth's integration with ServiceStack.

There's also no new concepts to learn as all ASP .NET Core endpoints, pages and controllers continue to Authenticate against
the populated `ClaimsPrincipal` whilst all ServiceStack APIs continue to Authenticate against the populated typed
[User Session](https://docs.servicestack.net/auth/sessions).

The `AuthFeature` works by registering the following Identity Auth Providers:

### Identity Auth Providers

- [IdentityApplicationAuthProvider](https://github.com/ServiceStack/ServiceStack/blob/main/ServiceStack/src/ServiceStack.Extensions/Auth/IdentityApplicationAuthProvider.cs) - Converts an Identity Auth `ClaimsPrincipal` into a ServiceStack Session
- [IdentityCredentialsAuthProvider](https://github.com/ServiceStack/ServiceStack/blob/main/ServiceStack/src/ServiceStack.Extensions/Auth/IdentityCredentialsAuthProvider.cs) - Implements ServiceStack's `Authenticate` API using Identity Auth
- [IdentityJwtAuthProvider](https://github.com/ServiceStack/ServiceStack/blob/main/ServiceStack/src/ServiceStack.Extensions/Auth/IdentityJwtAuthProvider.cs) - Converts an Identity Auth JWT into an Authenticated ServiceStack Session

Only the `IdentityApplicationAuthProvider` is registered by default which is required to convert Identity Auth's `ClaimPrincipal`
into an Authenticated ServiceStack [Session](/auth/sessions). The other Auth Providers are required if you want to enable authentication with
ServiceStack's endpoints. E.g. ServiceStack's [Built-in UIs](https://servicestack.net/auto-ui) would require the Credentials Auth
to be enabled to authenticate via the built-in Sign In dialogs.

### Configuring Auth Providers

Which is what all the Blazor and MVC Identity Auth templates enable by default in
[Configure.Auth.cs](https://github.com/NetCoreTemplates/blazor/blob/main/MyApp/Configure.Auth.cs):

```csharp
public class ConfigureAuth : IHostingStartup
{
    public void Configure(IWebHostBuilder builder) => builder
        .ConfigureAppHost(appHost => 
        {
            appHost.Plugins.Add(new AuthFeature(IdentityAuth.For<ApplicationUser>(
                // Configure ServiceStack's Integration with Identity Auth
                options => {
                    // options.SessionFactory = () => new CustomUserSession(); //optional
                    options.CredentialsAuth();
                })
            ));
        });
}
```

If you're using a `CustomUserSession` you'll also need to register it with the `SessionFactory` for it to be used.

### Configure Individual Auth Providers

Each of the Identity Auth Providers can also be customized individually:

```csharp
Plugins.Add(new AuthFeature(IdentityAuth.For<ApplicationUser>(options => {
        // Configure IdentityApplicationAuthProvider
        options.ApplicationAuth(options => {});

        // Configure IdentityCredentialsAuthProvider
        options.CredentialsAuth(options => {});

        // Configure IdentityJwtAuthProvider
        options.JwtAuth(options => {});
    })
));
```

### Enable Optional ServiceStack Auth Services

Typically you'll want to use the included Identity UI Pages and dependencies to register new users and assign roles,
but if you have any existing client integrations that use ServiceStack APIs they can also be enabled with:

```csharp
Plugins.Add(new AuthFeature(IdentityAuth.For<ApplicationUser>(options => {
    // Include ServiceStack's Register API
    options.IncludeRegisterService = true;
    
    // Include ServiceStack's AssignRoles and UnAssignRoles APIs
    options.IncludeAssignRoleServices = true;
));
```

### Extending Identity Auth Cookies and User Sessions

By default all [well known Claim Names](https://github.com/ServiceStack/ServiceStack/blob/3ab3d23c85cf48435b8cd9386f25afab79fcb542/ServiceStack/src/ServiceStack.Extensions/Auth/IdentityApplicationAuthProvider.cs#L49)
are used to populate the User Session, but you can also include additional claims in the Identity Auth Cookie
and use them to populate the User Session by overriding `PopulateFromClaims()` in your
[CustomUserSession.cs](https://github.com/NetCoreTemplates/blazor/blob/main/MyApp.ServiceInterface/Data/CustomUserSession.cs), e.g:

```csharp
public class CustomUserSession : AuthUserSession
{
    public override void PopulateFromClaims(IRequest httpReq, ClaimsPrincipal principal)
    {
        // Populate Session with data from Identity Auth Claims
        ProfileUrl = principal.FindFirstValue(JwtClaimTypes.Picture);
    }
}

// Add additional claims to the Identity Auth Cookie
public class AdditionalUserClaimsPrincipalFactory(UserManager<ApplicationUser> userManager, RoleManager<IdentityRole> roleManager, IOptions<IdentityOptions> optionsAccessor)
    : UserClaimsPrincipalFactory<ApplicationUser,IdentityRole>(userManager, roleManager, optionsAccessor)
{
    public override async Task<ClaimsPrincipal> CreateAsync(ApplicationUser user)
    {
        var principal = await base.CreateAsync(user);
        var identity = (ClaimsIdentity)principal.Identity!;

        var claims = new List<Claim>();
        // Add additional claims here
        if (user.ProfileUrl != null)
        {
            claims.Add(new Claim(JwtClaimTypes.Picture, user.ProfileUrl));
        }

        identity.AddClaims(claims);
        return principal;
    }
}
```

### Custom Application User Primary Key

The default `IdentityUser` uses a `string` as the primary key populated with a `Guid`, but you could also change it to use an
`int` by having your EF IdentityUser Data Model inherit from `IdentityUser<int>` instead:

```csharp
public class AppUser : IdentityUser<int>
{
    //...
}
```

You'll also need to specify the Key Type when registering the `AuthFeature` plugin:

```csharp
public class ConfigureAuth : IHostingStartup
{
    public void Configure(IWebHostBuilder builder) => builder
        .ConfigureAppHost(appHost => {
            appHost.Plugins.Add(new AuthFeature(IdentityAuth.For<AppUser,int>(
                options => {
                    options.SessionFactory = () => new CustomUserSession();
                    options.CredentialsAuth();
                })
            ));
        });
}
```

Which the new .NET 8 BlazorDiffusion App does in [Configure.Auth.cs](https://github.com/NetCoreApps/BlazorDiffusionVue/blob/main/BlazorDiffusion/Configure.Auth.cs)
to be compatible with its existing ServiceStack `UserAuth` tables which used an `int` primary key.

## Using Identity Auth in ServiceStack Apps

One of the primary benefits of adopting Identity Auth is the wealth of documentation and resources available for it,
which also applies to how you would use Identity Auth to secure your own Apps.

If you're new to Identity Auth we recommend starting with the official introduction from Microsoft:

- [Introduction to Identity on ASP.NET Core](https://learn.microsoft.com/en-us/aspnet/core/security/authentication/identity)

To learn about securing Blazor Apps, go to:

- [ASP.NET Core Blazor authentication and authorization](https://learn.microsoft.com/en-us/aspnet/core/blazor/security/)

### Declarative Validation Attributes

The recommended way to protect your ServiceStack APIs is to continue to use the [Declarative Validation](https://docs.servicestack.net/declarative-validation)
attributes which are decoupled from any implementation so be safely annotated on Request DTOs without adding
any implementation dependencies, where they're also accessible to Clients and UIs using the Request DTOs to invoke your APIs.

The available Typed Authorization Attributes include:

| Attribute                   | Description                                            |
|-----------------------------|--------------------------------------------------------|
| `[ValidateIsAuthenticated]` | Restrict access toAuthenticated Users only             |
| `[ValidateIsAdmin]`         | Restrict access to Admin Users only                    |
| `[ValidateHasRole]`         | Restrict access to only Users assigned with this Role  |
| `[ValidateHasClaim]`        | Restrict access to only Users assigned with this Claim |
| `[ValidateHasScope]`        | Restrict access to only Users assigned with this Scope |

That can be annotated on **Request DTOs** to protect APIs:

```csharp
[ValidateIsAuthenticated]
[ValidateIsAdmin]
[ValidateHasRole(role)]
[ValidateHasClaim(type,value)]
[ValidateHasScope(scope)]
public class Secured {}
```

### Using Identity Auth in ServiceStack Clients

As ServiceStack Identity Auth integration registers replacements Auth Providers for ServiceStack's built-in Auth Providers,
existing ServiceStack Client integrations will continue to work without any changes, e.g:

```csharp
const client = new JsonApiClient(baseUrl);

var response = await client.ApiAsync(new Authenticate {
    provider = "credentials",
    UserName = userName,
    Password = password,
});
```

The difference being that instead of returning an Authenticated ServiceStack Session Cookie, it instead returns an
ASP.NET's Identity `.AspNetCore.Identity.Application` Cookie which it will be used to perform Authenticated API requests.

This transparent re-implementation of ServiceStack Auth Providers and endpoints is also how ServiceStack's
[Built-in UIs](https://servicestack.net/auto-ui) was able to continue to work without any code changes.

### SMTP IEmailSender

The .NET 8 Templates also include a nice solution for sending Identity Auth emails through the `IEmailSender` interface
which drops the Email Request in the registered Background MQ in
[Configure.Mq.cs](https://github.com/NetCoreTemplates/blazor/blob/main/MyApp/Configure.Mq.cs)
which uses it to invoke the `SendEmail` API in
[EmailServices](https://github.com/NetCoreTemplates/blazor/blob/main/MyApp.ServiceInterface/EmailServices.cs) in a
managed background worker:

```csharp
public class EmailSender(IMessageService messageService) : IEmailSender
{
    public Task SendEmailAsync(string email, string subject, string htmlMessage)
    {
        using var mqClient = messageService.CreateMessageProducer();
        mqClient.Publish(new SendEmail
        {
            To = email,
            Subject = subject,
            BodyHtml = htmlMessage,
        });

        return Task.CompletedTask;
    }
}
```

To enable it you'll need to register your preferred SMTP Server in your App's `appsettings.json`:

```json
{
  "SmtpConfig": {
    "Username": "username",
    "Password": "password",
    "Host": "smtp.mailtrap.io",
    "Port": 587,
    "FromEmail": "mail@example.org"
  }
}
```

Then uncomment the `EmailSender` registration in your `Program.cs`

```csharp
services.AddSingleton<IEmailSender, EmailSender>();
```

### Send any App Email

The nice part about this solution is that it's not limited to just sending Identity Auth emails, you can also use it to send
any App Email, either by publishing a message to the registered MQ with `PublishMessage` or by using the
[Service Gateway](https://docs.servicestack.net/service-gateway) to invoke the API directly, e.g:

```csharp
public class MyServices : Service
{
    public object Any(MyRequest request)
    {
        // Send Email in managed Background MQ Worker
        PublishMessage(new SendEmail {
            To = email,
            Subject = subject,
            BodyHtml = body,
        });

        // Block until Email is sent to SMTP Server
        Gateway.Send(new SendEmail {
            To = email,
            Subject = subject,
            BodyHtml = body,
        });
    }
}
```


# JWT Identity Auth
Source: https://docs.servicestack.net/auth/jwt-identity-auth

JWTs enable stateless authentication of clients without servers needing to maintain any Auth state in server infrastructure
or perform any I/O to validate a token. As such,
[JWTs are a popular choice for Microservices](/auth/jwt-authprovider#stateless-auth-microservices)
as they only need to configured with confidential keys to validate access.

### ASP.NET Core JWT Authentication

ServiceStack's JWT Identity Auth reimplements many of the existing [ServiceStack JWT AuthProvider](/auth/jwt-authprovider)
features but instead of its own implementation, integrates with and utilizes ASP.NET Core's built-in JWT Authentication that's
configurable in .NET Apps with the `.AddJwtBearer()` extension method, e.g:

#### Program.cs

```csharp
services.AddAuthentication()
    .AddJwtBearer(options => {
        options.TokenValidationParameters = new()
        {
            ValidIssuer = config["JwtBearer:ValidIssuer"],
            ValidAudience = config["JwtBearer:ValidAudience"],
            IssuerSigningKey = new SymmetricSecurityKey(
                Encoding.UTF8.GetBytes(config["JwtBearer:IssuerSigningKey"]!)),
            ValidateIssuerSigningKey = true,
        };
    })
    .AddIdentityCookies(options => options.DisableRedirectsForApis());
```

Then use the `JwtAuth()` method to enable and configure ServiceStack's support for ASP.NET Core JWT Identity Auth: 

#### Configure.Auth.cs

```csharp
public class ConfigureAuth : IHostingStartup
{
    public void Configure(IWebHostBuilder builder) => builder
        .ConfigureServices(services => {
            services.AddPlugin(new AuthFeature(IdentityAuth.For<ApplicationUser>(
                options => {
                    // options.SessionFactory = () => new CustomUserSession(); //optional
                    options.CredentialsAuth();
                    options.JwtAuth(x => {
                        // Enable JWT Auth Features...
                    });
                })));
        });
}
```

### Enable in Swagger UI

Once configured we can enable JWT Auth in Swagger UI by installing **Swashbuckle.AspNetCore**:

:::copy
`<PackageReference Include="Swashbuckle.AspNetCore" Version="7.*" />`
:::

Then enable Open API, Swagger UI, ServiceStack's support for Swagger UI and the JWT Bearer Auth option:

```csharp
public class ConfigureOpenApi : IHostingStartup
{
    public void Configure(IWebHostBuilder builder) => builder
        .ConfigureServices((context, services) => {
            if (context.HostingEnvironment.IsDevelopment())
            {
                services.AddEndpointsApiExplorer();
                services.AddSwaggerGen();
                services.AddServiceStackSwagger();
                services.AddJwtAuth();
                //services.AddBasicAuth<Data.ApplicationUser>();
            
                services.AddTransient<IStartupFilter,StartupFilter>();
            }
        });

    public class StartupFilter : IStartupFilter
    {
        public Action<IApplicationBuilder> Configure(Action<IApplicationBuilder> next) => app =>
        {
            app.UseSwagger();
            app.UseSwaggerUI();
            next(app);
        };
    }
}
```

This will enable the **Authorize** button in Swagger UI where you can authenticate with a JWT Token:

![](/img/pages/auth/identity/jwt-swagger-ui.png)

### JWT Auth in Built-in UIs

This also enables the **JWT** Auth Option in ServiceStack's built-in 
[API Explorer](/api-explorer), 
[Locode](/locode/) and 
[Admin UIs](/admin-ui):

<img class="shadow p-1" src="/img/pages/auth/identity/jwt-api-explorer.png">

### Authenticating with JWT

JWT Identity Auth is a drop-in replacement for ServiceStack's JWT AuthProvider where Authenticating via Credentials
will convert the Authenticated User into a JWT Bearer Token returned in the **HttpOnly**, **Secure** `ss-tok` Cookie
that will be used to Authenticate the client:

```csharp
var client = new JsonApiClient(BaseUrl);
await client.SendAsync(new Authenticate {
    provider = "credentials",
    UserName = Username,
    Password = Password,
});

var bearerToken = client.GetTokenCookie(); // ss-tok Cookie
```

## JWT Refresh Tokens

Refresh Tokens can be used to allow users to request a new JWT Access Token when the current one expires.

To enable support for JWT Refresh Tokens your `IdentityUser` model should implement the `IRequireRefreshToken` interface
which will be used to store the 64 byte Base64 URL-safe `RefreshToken` and its `RefreshTokenExpiry` in its persisted properties:

```csharp
public class ApplicationUser : IdentityUser, IRequireRefreshToken
{
    //...
    public string? RefreshToken { get; set; }
    public DateTime? RefreshTokenExpiry { get; set; }
}
```

Now after successful authentication, the `RefreshToken` will also be returned in the `ss-reftok` Cookie:

```csharp
var refreshToken = client.GetRefreshTokenCookie(); // ss-reftok Cookie
```

### Transparent Server Auto Refresh of JWT Tokens

To be able to terminate a users access, Users need to revalidate their eligibility to verify they're still allowed access 
(e.g. deny Locked out users). This JWT revalidation pattern is implemented using Refresh Tokens which are used to request 
revalidation of their access and reissuing a new JWT Access Token which can be used to make authenticated requests until it expires.

As Cookies are used to return Bearer and Refresh Tokens ServiceStack is able to implement the revalidation logic on the 
server where it transparently validates Refresh Tokens, and if a User is eligible will reissue a new JWT Token Cookie that
replaces the expired Access Token Cookie.

Thanks to this behavior HTTP Clients will be able to Authenticate with just the Refresh Token, which will transparently
reissue a new JWT Access Token Cookie and then continue to perform the Authenticated Request:

```csharp
var client = new JsonApiClient(BaseUrl);
client.SetRefreshTokenCookie(RefreshToken);

var response = await client.SendAsync(new Secured { ... });
```

There's also opt-in sliding support for extending a User's RefreshToken after usage which allows Users to treat 
their Refresh Token like an API Key where it will continue extending whilst they're continuously using it to make API requests, 
otherwise expires if they stop. How long to extend the expiry of Refresh Tokens after usage can be configured with:

```csharp
options.JwtAuth(x => {
    // How long to extend the expiry of Refresh Tokens after usage (default None)
    x.ExtendRefreshTokenExpiryAfterUsage = TimeSpan.FromDays(90);
});
```

## Convert Session to Token Service

Another useful Service that's available is being able to Convert your current Authenticated Session into a Token
with the `ConvertSessionToToken` Service which can be enabled with:

```csharp
options.JwtAuth(x => {
    x.IncludeConvertSessionToTokenService = true;
});
```

This can be useful for when you want to Authenticate via an external OAuth Provider that you then want to convert into a stateless 
JWT Token by calling the `ConvertSessionToToken` on the client, e.g:

#### .NET Clients

```csharp
await client.SendAsync(new ConvertSessionToToken());
```

#### TypeScript/JavaScript

```ts
fetch('/session-to-token', { method:'POST', credentials:'include' })
```

The default behavior of `ConvertSessionToToken` is to remove the Current Session from the Auth Server which will prevent 
access to protected Services using our previously Authenticated Session. If you still want to preserve your existing Session 
you can indicate this with:

```csharp
await client.SendAsync(new ConvertSessionToToken { 
    PreserveSession = true 
});
```

### JWT Options

Other configuration options available for Identity JWT Auth include:

```csharp
options.JwtAuth(x => {
    // How long should JWT Tokens be valid for. (default 14 days)
    x.ExpireTokensIn = TimeSpan.FromDays(14);
    
    // How long should JWT Refresh Tokens be valid for. (default 90 days)
    x.ExpireRefreshTokensIn = TimeSpan.FromDays(90);
    
    x.OnTokenCreated = (req, user, claims) => {
        // Customize which claims are included in the JWT Token
    };
    
    // Whether to invalidate Refresh Tokens on Logout (default true)
    x.InvalidateRefreshTokenOnLogout = true;
    
    // How long to extend the expiry of Refresh Tokens after usage (default None)
    x.ExtendRefreshTokenExpiryAfterUsage = null;
});
```


# API Keys
Source: https://docs.servicestack.net/auth/apikeys

As we continue to embrace and natively integrate with ASP.NET Core's .NET 8 platform, we've reimplemented the last major
feature missing from ServiceStack Auth - support for API Keys that's available from **ServiceStack v8.3**.

:::warning API Key Feature Vulnerability
**ServiceStack v8.7+** resolves a vulnerability we've discovered in the management APIs of this API Keys feature, if using API Keys please upgrade as soon as possible.
:::

### What are API Keys?

API Keys are a simple and effective way to authenticate and authorize access to your APIs, which are typically used 
for machine-to-machine communication, where a client application needs to access an API without user intervention. 
API Keys are often used to control access to specific resources or features in your API, providing a simple way 
to manage access control.

### Redesigning API Keys

Building on our experience with API Keys in previous versions of ServiceStack, we've taken the opportunity to redesign
how API Keys work to provide a more flexible and powerful way to manage access control for your APIs.

The existing [API Key Auth Provider](https://docs.servicestack.net/auth/api-key-authprovider) was implemented as 
another Auth Provider that provided another way to authenticate a single user. The consequences of this was:

 - Initial API Request was slow as it required going through the Authentication workflow to authenticate the user and setup authentication for that request
 - No support for fine-grained access control as API Keys had same access as the authenticated user
 - API Keys had to be associated with a User which was unnecessary for machine-to-machine communication

Given the primary use-case for API Keys is for machine-to-machine communication where the client is not a User,
nor do they want systems they give out their API Keys to, to have access to their User Account, we've changed
how API Keys work in .NET 8.

## .NET 8 API Keys Feature

:::youtube U4vqOIHOs_Q
New .NET 8 API Keys Feature with Built-In UIs!
:::

The first design decision to overcome the above issues was to separate API Keys from Users and Authentication itself,
where the new `ApiKeysFeature` is now just a plugin instead of an Auth Provider, which can be added to existing Identity
Auth Apps with:

:::sh
x mix apikeys
:::

Which will add the API Keys [Modular Startup](https://docs.servicestack.net/modular-startup) to your Host project, a minimal example of which looks like:

```csharp
public class ConfigureApiKeys : IHostingStartup
{
    public void Configure(IWebHostBuilder builder) => builder
        .ConfigureServices(services => {
            services.AddPlugin(new ApiKeysFeature());
        })
        .ConfigureAppHost(appHost => {
            using var db = appHost.Resolve<IDbConnectionFactory>().Open();
            var feature = appHost.GetPlugin<ApiKeysFeature>();
            feature.InitSchema(db);
        });
}
```

Where it registers the `ApiKeysFeature` plugin and creates the `ApiKey` table in the App's configured database if it
doesn't already exist.

### Creating Seed API Keys

The plugin can also be used to programmatically generate API Keys for specified Users:

```csharp
if (feature.ApiKeyCount(db) == 0)
{
    var createApiKeysFor = new [] { "admin@email.com", "manager@email.com" };
    var users = IdentityUsers.GetByUserNames(db, createApiKeysFor);
    foreach (var user in users)
    {
        // Create a super API Key for the admin user
        List<string> scopes = user.UserName == "admin@email.com"
            ? [RoleNames.Admin] 
            : [];
        var apiKey = feature.Insert(db, new() { 
            Name="Seed Key", UserId=user.Id, UserName=user.UserName, Scopes=scopes });
        
        var generatedApiKey = apiKey.Key;
    }
}
```

### Basic Usage

With the plugin registered, you can now use the `ValidateApiKey` attribute to limit APIs to only be accessible with a 
valid API Key, e.g:

```csharp
[ValidateApiKey]
public class MyRequest {}
```

### Use API Keys with our without Users and Authentication

API Keys can optionally be associated with a User, but they don't have to be, nor do they run in the context of a User
or are able to invoke any Authenticated APIs on their own. Users who create them can also limit their scope to only
call APIs they have access to, which can be done with user-defined scopes:

### Scopes

Scopes are user-defined strings that can be used to limit APIs from only being accessible with API Keys that have the 
required scope. For example, we could create generate API Keys that have **read only**, **write only** or **read/write** 
access to APIs by assigning them different scopes, e.g: 

```csharp
public static class Scopes
{
    public const string TodoRead = "todo:read";
    public const string TodoWrite = "todo:write";
}

[ValidateApiKey(Scopes.TodoRead)]
public class QueryTodos : QueryDb<Todo> {}

[ValidateApiKey(Scopes.TodoWrite)]
public class CreateTodo : ICreateDb<Todo>, IReturn<Todo> {}

[ValidateApiKey(Scopes.TodoWrite)]
public class UpdateTodo : IUpdateDb<Todo>, IReturn<Todo> {}

[ValidateApiKey(Scopes.TodoWrite)]
public class DeleteTodos : IDeleteDb<Todo>, IReturnVoid {}
```

Where only API Keys with the `todo:read` scope can access the `QueryTodos` API, and only API Keys with the `todo:write`
scope can access the `CreateTodo`, `UpdateTodo` and `DeleteTodos` APIs.

APIs that aren't assigned a scope can be accessed by any valid API Key.

The only built-in Scope is `Admin` which like the `Admin` role enables full access to all `[ValidateApiKeys]` APIs.

### Fine-grained Access Control

Alternatively API Keys can be restricted to only be able to access specific APIs.

### Features

In addition to scopes, API Keys can also be tagged with user-defined **Features** which APIs can inspect to enable 
different behavior, e.g. a **Paid** feature could be used to increase rate limits or return premium content whilst a 
**Tracking** feature could be used to keep a record of API requests, etc.

These can be accessed in your Services with:

```csharp
public object Any(QueryTodos request)
{
    if (Request.GetApiKey().HasFeature(Features.Paid))
    {
        // return premium content
    }
}
```

## Integrated UIs

Like many of ServiceStack's other premium features, API Keys are fully integrated into [ServiceStack's built-in UIs](https://servicestack.net/auto-ui)
including [API Explorer](https://docs.servicestack.net/api-explorer) and the [Admin UI](https://docs.servicestack.net/admin-ui).

### API Explorer

Your Users and API Consumers can use API Explorer to invoke protected APIs with their API Key. API Key protected APIs
will display a **key** icon next to the API instead of the **padlock** which is used to distinguish APIs that require
Authentication.

Users can configure API Explorer with their API Key by either clicking the **key** icon on the top right or by clicking
the **API Key** link on the alert message that appears when trying to access an API requiring an API Key:

![](/img/pages/auth/apikeys/apiexplorer-apikeys.png)

Both of these will open the **API Key** dialog where they can paste their API Key:

![](/img/pages/auth/apikeys/apiexplorer-apikeys-dialog.png)

:::info NOTE
API Keys are not stored in localStorage and only available in the current session
:::

### Admin UI

Whilst **Admin** users can view and manage API Keys in the API Key [Admin UI](https://docs.servicestack.net/admin-ui) at:

:::{.text-4xl .text-center .text-indigo-800}
/admin-ui/apikeys
:::

![](/img/pages/auth/apikeys/admin-ui-apikeys.png)

This will let you view and manage all API Keys in your App, including the ability to revoke API Keys, extend their 
Expiration date as well as manage any Scopes and Features assigned to API Keys.

### Customizing API Key UIs

The `ApiKeysFeature` plugin can be configured to specify which **Scopes** and **Features** can be assigned to API Keys
as well as the different Expiration Options you want available in the API Key management UIs, e.g:

```csharp
services.AddPlugin(new ApiKeysFeature {
    // Optional: Available Scopes Admin Users can assign to any API Key
    Features = [
        Features.Paid,
        Features.Tracking,
    ],
    // Optional: Available Features Admin Users can assign to any API Key
    Scopes = [
        Scopes.TodoRead,
        Scopes.TodoWrite,
    ],
    // Optional: Limit available Expiry options that can be assigned to API Keys
    // ExpiresIn = [
    //     new("", "Never"),
    //     new("7", "7 days"),
    //     new("30", "30 days"),
    //     new("365", "365 days"),
    // ],
});
```

### Admin User API Keys

When the `ApiKeysFeature` plugin is registered, the [User Admin UI](https://docs.servicestack.net/admin-ui-identity-users) 
will be enhanced to include the ability to create and manage API Keys for the user at the bottom of the **Edit User** form:   

![](/img/pages/auth/apikeys/admin-ui-user-apikeys.png)

#### Creating User API Keys

When creating API Keys, you can assign them a **Name**, its **Expiration** date and any **Scopes**, **Features** and **Notes**.

![](/img/pages/auth/apikeys/admin-ui-user-apikeys-create.png)

### Restrict to APIs

`Scopes` provide a simple way to logically group a collection of related APIs behind UX-friendly names without Users 
needing to know the behavior of each individual API. 

In addition, Users who want fine-grained control can also restrict API Keys to only be able to access specific APIs that 
their systems make use of by selecting them from the **Restrict to APIs** option:

![](/img/pages/auth/apikeys/apikeys-restrict-to.png)

#### One Time only access of generated API Key

All UIs limit access to the generated API Key token so that it's only accessible at the time of creation:

![](/img/pages/auth/apikeys/admin-ui-user-apikeys-create-dialog.png)

#### Editing User API Keys

Everything about the API Key can be edited after it's created except for the generated API Key token itself, in addition
to be able to cancel and revoke the API Key:

![](/img/pages/auth/apikeys/admin-ui-user-apikeys-edit.png)

Invalid API Keys that have expired or have been disabled will appear disabled in the UI:

![](/img/pages/auth/apikeys/admin-ui-user-apikeys-disabled.png)

## User Management API Keys

In addition to the built-in Admin UIs to manage API Keys, all Identity Auth Tailwind templates have also been updated
to include support for managing API Keys in their User Account pages:

<div class="not-prose mt-8 grid grid-cols-2 gap-4">
    <a class="block group border dark:border-gray-800 hover:border-indigo-700 dark:hover:border-indigo-700 flex flex-col justify-between" href="https://blazor.web-templates.io">
        <img class="p-2" src="https://raw.githubusercontent.com/ServiceStack/Assets/master/csharp-templates/blazor.png">
        <div class="bg-gray-50 dark:bg-gray-800 text-gray-600 dark:text-gray-300 font-semibold group-hover:bg-indigo-700 group-hover:text-white text-center py-2">blazor.web-templates.io</div>
    </a>
    <a class="block group border dark:border-gray-800 hover:border-indigo-700 dark:hover:border-indigo-700" href="https://blazor-vue.web-templates.io">
        <div style="max-height:350px;overflow:hidden">
        <img class="p-2" src="https://raw.githubusercontent.com/ServiceStack/Assets/master/csharp-templates/blazor-vue.png"></div>
        <div class="bg-gray-50 dark:bg-gray-800 text-gray-600 dark:text-gray-300 font-semibold group-hover:bg-indigo-700 group-hover:text-white text-center py-2">blazor-vue.web-templates.io</div>
    </a>
    <a class="block group border dark:border-gray-800 hover:border-indigo-700 dark:hover:border-indigo-700" href="https://blazor-wasm.web-templates.io">
        <div style="max-height:350px;overflow:hidden">
        <img class="p-2" src="https://raw.githubusercontent.com/ServiceStack/Assets/master/csharp-templates/blazor-wasm.png"></div>
        <div class="bg-gray-50 dark:bg-gray-800 text-gray-600 dark:text-gray-300 font-semibold group-hover:bg-indigo-700 group-hover:text-white text-center py-2">blazor-wasm.web-templates.io</div>
    </a>
    <a class="block group border dark:border-gray-800 hover:border-indigo-700 dark:hover:border-indigo-700" href="https://razor.web-templates.io">
        <div style="max-height:350px;overflow:hidden">
        <img class="p-2" src="https://raw.githubusercontent.com/ServiceStack/Assets/master/csharp-templates/razor.png"></div>
        <div class="bg-gray-50 dark:bg-gray-800 text-gray-600 dark:text-gray-300 font-semibold group-hover:bg-indigo-700 group-hover:text-white text-center py-2">razor.web-templates.io</div>
    </a>
    <a class="block group border dark:border-gray-800 hover:border-indigo-700 dark:hover:border-indigo-700" href="https://mvc.web-templates.io">
        <div style="max-height:350px;overflow:hidden">
        <img class="p-2" src="https://raw.githubusercontent.com/ServiceStack/Assets/master/csharp-templates/mvc.png"></div>
        <div class="bg-gray-50 dark:bg-gray-800 text-gray-600 dark:text-gray-300 font-semibold group-hover:bg-indigo-700 group-hover:text-white text-center py-2">mvc.web-templates.io</div>
    </a>
</div>

The templates aren't configured to use API Keys by default, but new projects can be configured to use API Keys by 
selecting the **API Keys** feature on the [Start Page](/start):

[![](/img/pages/auth/apikeys/start-apikeys.png)](/start)

Or by mixing the `apikeys` project in your host project:

:::sh
x mix apikeys
:::

Which add the `Configure.ApiKeys.cs` modular startup to your Host project, which registers the `ApiKeysFeature` plugin
where you'd use the `UserScopes` and `UserFeatures` collections instead to control which scopes and features Users
can assign to their own API Keys, e.g:

```csharp
services.AddPlugin(new ApiKeysFeature {
    // Optional: Available Scopes Admin Users can assign to any API Key
    Features = [
        Features.Paid,
        Features.Tracking,
    ],
    // Optional: Available Features Admin Users can assign to any API Key
    Scopes = [
        Scopes.TodoRead,
        Scopes.TodoWrite,
    ],
    
    // Optional: Limit available Scopes Users can assign to their own API Keys
    UserScopes = [
        Scopes.TodoRead,
    ],
    // Optional: Limit available Features Users can assign to their own API Keys
    UserFeatures = [
        Features.Tracking,
    ],
});
```

### Identity Auth API Keys

When enabled users will be able to create and manage their own API Keys from their Identity UI pages
which will use any configured `UserScopes` and `UserFeatures`:

![](/img/pages/auth/apikeys/identity-auth-apikeys.png)

### Client Usage

Like most API Key implementations, API Keys can be passed in a [HTTP Authorization Bearer Token](https://datatracker.ietf.org/doc/html/rfc6750#section-2.1)
that can be configured in ServiceStack Service Clients with: 

#### C#

```csharp
var client = new JsonApiClient(BaseUrl) {
    BearerToken = apiKey
};
```

#### TypeScript

```ts
const client = new JsonServiceClient(BaseUrl)
client.bearerToken = apiKey
```

### API Key HTTP Header

Alternatively, API Keys can also be passed in the `X-Api-Key` HTTP Header which allows clients to be configured
with an alternative Bearer Token allowing the same client to call both **Authenticated** and **API Key** protected APIs, e.g:

#### C#

```csharp
var client = new JsonApiClient(BaseUrl) {
    BearerToken = jwt,
    Headers = {
        [HttpHeaders.XApiKey] = apiKey
    }
};
```

#### TypeScript

```ts
const client = new JsonServiceClient(BaseUrl)
client.bearerToken = apiKey
client.headers.set('X-Api-Key', apiKey)
```

Or use a different HTTP Header by configuring `ApiKeysFeature.HttpHeader`, e.g:

```csharp
services.AddPlugin(new ApiKeysFeature {
    HttpHeader = "X-Alt-Key"
});
```


# Simple Auth for .NET 8 Apps
Source: https://docs.servicestack.net/auth/admin-apikeys

With ServiceStack now fully [integrated with ASP.NET Identity Auth](/auth/identity-auth),
our latest [.NET 8 Tailwind Templates](/start) offer a full-featured Auth Configuration complete with User Registration, 
Login, Password Recovery, Two Factory Auth, and more.

Whilst great for Web Applications that need it, it neglects the class of Apps which don't need User Auth and
the additional complexity it brings inc. Identity and Password Management, EF Migrations, Token Expirations, OAuth Integrations, etc. 

For these stand-alone Apps, Microservices and Docker Appliances that would still like to restrict Access to their APIs
but don't need the complexity of ASP .NET Core's Authentication machinery, a simpler Auth Story would be preferred.

With the introduction of API Keys in this release we're able to provide a simpler Auth Story for .NET 8 Microservices 
that's easy for **Admin** Users to manage and control which trusted clients and B2B Integrations can access their functionality.

:::youtube 0ceU91ZBhTQ
Simple Auth Story with API Keys ideal for .NET 8 Microservices
:::

The easiest way to get started is by creating a new Empty project with API Keys enabled with your preferred database to store the API Keys in. SQLite is a good choice for stand-alone Apps as it doesn't require any infrastructure dependencies.

<div class="not-prose mx-auto">
  <h3 id="template" class="mb-4 text-4xl tracking-tight font-extrabold text-gray-900">
      Create a new Empty project with API Keys
  </h3>
  <auth-templates></auth-templates>
</div>

### Existing Projects

Existing projects not configured with Authentication can enable this simple Auth configuration by running:

:::sh
x mix apikeys-auth
:::

Which will add the [ServiceStack.Server](https://nuget.org/packages/ServiceStack.Server) dependency and the [Modular Startup](/modular-startup) configuration below:

```csharp
public class ConfigureApiKeys : IHostingStartup
{
    public void Configure(IWebHostBuilder builder) => builder
        .ConfigureServices(services =>
        {
            services.AddPlugin(new AuthFeature([
                new ApiKeyCredentialsProvider(),
                new AuthSecretAuthProvider("p@55wOrd"),
            ]));
            services.AddPlugin(new SessionFeature());
            services.AddPlugin(new ApiKeysFeature
            {
                // Optional: Available Scopes Admin Users can assign to any API Key
                // Features = [
                //     "Paid",
                //     "Tracking",
                // ],
                // Optional: Available Features Admin Users can assign to any API Key
                // Scopes = [
                //     "todo:read",
                //     "todo:write",
                // ],
            });
        })
        .ConfigureAppHost(appHost =>
        {
            using var db = appHost.Resolve<IDbConnectionFactory>().Open();
            var feature = appHost.GetPlugin<ApiKeysFeature>();
            feature.InitSchema(db);
        });
}
```

Which configures the **AuthSecretAuthProvider** with the **Admin** password and **ApiKeysFeature** to enable [API Keys](/auth/apikeys) support.

### Admin UI

The **Admin** password will give you access to the [Admin UI](/admin-ui) at:

:::{.text-4xl .text-center .text-indigo-800}
/admin-ui
:::

![](/img/pages/auth/simple/admin-ui-signin.png)

![](/img/pages/auth/simple/admin-ui-dashboard.png)

### API Keys Admin UI

Clicking on **API Keys** menu item will take you to the API Keys Admin UI where you'll be able to create new API Keys 
that you can distribute to different API consumers you want to be able to access your APIs:

![](/img/pages/auth/simple/admin-ui-apikeys.png)

The **ApiKeysFeature** plugin will let you control different parts of the UI, including what **Features** you want to
assign to API Keys and what **Scopes** you want individual API Keys to be able to have access to.

```csharp
services.AddPlugin(new ApiKeysFeature
{
    Features = [
        "Paid",
        "Tracking",
    ],
    Scopes = [
        "todo:read",
        "todo:write",
    ],
    // ExpiresIn =[
    //     new("", "Never"),
    //     new("30", "30 days"),
    //     new("365", "365 days"),
    // ],    
    // Hide = ["RestrictTo","Notes"],
});
```

Any configuration on the plugin will be reflected in the UI:

![](/img/pages/auth/simple/admin-ui-apikeys-new.png)

The API Keys Admin UI also lets you view and manage all API Keys in your App, including the ability to revoke API Keys, 
extend their Expiration date as well as manage any Scopes and Features assigned to API Keys.

![](/img/pages/auth/simple/admin-ui-apikeys-edit.png)

### Protect APIs with API Keys

You'll now be able to protect APIs by annotating Request DTOs with the `[ValidateApiKey]` attribute:

```csharp
[ValidateApiKey]
public class Hello : IGet, IReturn<HelloResponse>
{
    public required string Name { get; set; }
}
```

Which only allows requests with a **valid API Key** to access the Service.

### Scopes

We can further restrict API access by assigning them a scope which will only allow access to Valid API Keys configured 
with that scope, e.g:

```csharp
[ValidateApiKey("todo:read")]
public class QueryTodos : QueryDb<Todo>
{
    public long? Id { get; set; }
    public List<long>? Ids { get; set; }
    public string? TextContains { get; set; }
}

[ValidateApiKey("todo:write")]
public class CreateTodo : ICreateDb<Todo>, IReturn<Todo>
{
    [ValidateNotEmpty]
    public required string Text { get; set; }
    public bool IsFinished { get; set; }
}

[ValidateApiKey("todo:write")]
public class UpdateTodo : IUpdateDb<Todo>, IReturn<Todo>
{
    public long Id { get; set; }
    [ValidateNotEmpty]
    public required string Text { get; set; }
    public bool IsFinished { get; set; }
}

[ValidateApiKey("todo:write")]
public class DeleteTodos : IDeleteDb<Todo>, IReturnVoid
{
    public long? Id { get; set; }
    public List<long>? Ids { get; set; }
}
```

### Restrict To APIs

Scopes allow for coarse-grained access control allowing a single scope to access a logical group of APIs. For more 
fine-grained control you can use **Restrict To APIs** to specify just the APIs an API Key can access:

![](/img/pages/auth/simple/admin-ui-apikeys-restrict-to.png)

Unlike scopes which can access APIs with the **same scope** or **without a scope**, Valid API Keys configured with
**Restrict To APIs** can only access those specific APIs.

### Features

Features are user-defined strings accessible within your Service implementation to provide different behavior
based on Features assigned to the API Key, e.g:

```csharp
public object Any(QueryTodos request)
{
    if (Request.GetApiKey().HasFeature("Paid"))
    {
        //...
    }
}
```

### Admin Only APIs

For APIs that should only be accessible to Admin Users (using AuthSecret) use `[ValidateIsAdmin]`, e.g:

```csharp
[ValidateIsAdmin]
public class AdminResetTodos : IPost, IReturnVoid {}
```

### API Explorer

Support for API Keys is also integrated into the [API Explorer](/api-explorer) allowing
users to use their API Keys to access API Key protected Services which are highlighted with a **Key** Icon:

![](/img/pages/auth/simple/apiexplorer-requires-apikey.png)

Users can enter their API Key by clicking on the **Key** Icon in the top right, or the link in the Warning alert
when trying to access an API Key protected Service:

![](/img/pages/auth/simple/apiexplorer-apikey-dialog.png)

## API Keys and Admin Secret Credentials Auth Provider

The usability of Simple Admin API Keys is greatly improved with the `ApiKeyCredentialsProvider` which enables .NET Microservices to provide persistent UserSession-like behavior for API Keys and Admin Auth Secrets to enable a Credentials Auth implementation which users can use with their API Keys or Admin AuthSecret.

When registered a **Credentials** SignIn dialog will appear for [ServiceStack Built-in UIs](https://servicestack.net/auto-ui) allowing users to Sign In with their **API Keys** or Admin **Auth Secret**.

![](/img/pages/auth/simple/ai-server-auth-apiexplorer.png)

### Session Auth with API Keys

Behind the scenes this creates a Server [Auth Session](/auth/sessions)
but instead of maintaining an Authenticated User Session it saves the API Key in the session then attaches the API Key to each request. This makes it possible to make API Key validated requests with just a session cookie instead of requiring resubmission of API Keys for each request.

### Secure .NET Microservices and Docker Appliances

This is an ideal Auth Configuration for .NET Docker Appliances and Microservices like [AI Server](/ai-server/) that don't need the complexity of ASP .NET Core's Identity Auth machinery and just want to restrict access to their APIs with API Keys and restrict Admin functionality to Administrator's with an Auth Secret.

The benefit of `ApiKeyCredentialsProvider` is that it maintains a persistent Session so that end users
only need to enter their API Key a single time and they'll be able to navigate to all of AI Server's protected pages using their API Key maintained in their Server User Session without needing to re-enter it for each UI and every request.

### User Access with API Keys

AI Server uses **API Keys** to restrict Access to their AI Features to **authorized Users** with Valid API Keys who
are able to use its Built-in UIs for its AI Features with the Users preferred Name and issued API Key:

![](/img/pages/auth/simple/ai-server-auth-user.png)

After signing in a single time they'll be able to navigate to any protected page and start using AI Server's AI features:

![](/img/pages/auth/simple/ai-server-auth-user-chat.png)

### User Access to API Explorer

This also lets users use their existing Auth Session across completely different UIs
like [API Explorer](/api-explorer)
where they'll have the same access to APIs as they would when calling APIs programatically with their API Keys, e.g:

![](/img/pages/auth/simple/ai-server-auth-apiexplorer-api.png)

## Admin Access

AI Server also maintains an Admin UI and Admin APIs that are only accessible to **Admin** users who 
Authenticate with the App's configured Admin Auth Secret who are able to access AI Server's Admin
UIs to monitor Live AI Requests, create new User API Keys, Manage registered AI Providers, etc. 

![](/img/pages/auth/simple/ai-server-auth-admin-jobs.png)

### Admin Restricted APIs

You can restrict APIs to Admin Users by using `[ValidateAuthSecret]`: 

```csharp
[Tag(Tags.Admin)]
[ValidateAuthSecret]
[Api("Add an AI Provider to process AI Requests")]
public class CreateAiProvider : ICreateDb<AiProvider>, IReturn<IdResponse>
{
    //...
}
```

Which are identified in API Explorer with a **padlock** icon whilst APIs restricted by API Key are 
identified with a **key** icon:

![](/img/pages/auth/simple/ai-server-auth-apiexplorer-admin.png)


### Client Usage

All HTTP and existing [Service Clients](https://docs.servicestack.net/clients-overview) can be configured to use API Keys
for machine-to-machine communication, which like most API Key implementations can be passed in a [HTTP Authorization Bearer Token](https://datatracker.ietf.org/doc/html/rfc6750#section-2.1)
that can be configured in Service Clients with:

#### C#

```csharp
var client = new JsonApiClient(BaseUrl) {
    BearerToken = apiKey
};
```

#### TypeScript

```ts
const client = new JsonServiceClient(BaseUrl)
client.bearerToken = apiKey
```

### API Key HTTP Header

Alternatively, API Keys can also be passed in the `X-Api-Key` HTTP Header which allows clients to be configured
with an alternative Bearer Token allowing the same client to call both **Authenticated** and **API Key** protected APIs, e.g:

#### C#

```csharp
var client = new JsonApiClient(BaseUrl) {
    BearerToken = AuthSecret,
    Headers = {
        [HttpHeaders.XApiKey] = apiKey
    }
};
```

#### TypeScript

```ts
const client = new JsonServiceClient(BaseUrl)
client.bearerToken = AuthSecret
client.headers.set('X-Api-Key', apiKey)
```

## Development

You can avoid having to re-renter AuthSecret and API Keys during Development by populating every request with
the configured Admin AuthSecret which allows you to call both `[ValidateApiKey]` and `[ValidateIsAdmin]` protected APIs:

```csharp
#if DEBUG
PreRequestFilters.Add((req, res) =>
{
    req.Items[Keywords.AuthSecret] = authSecret;
    req.Items[Keywords.Authorization] = "Bearer " + authSecret;
});
#endif
```

### Summary

We hope this shows how stand-alone .NET 8 Microservices and self-contained Docker Apps can use the 
simple **Admin** and **API Keys** configuration to easily secure their APIs, complete with **Management UI** 
and **typed Service Client** integrations.


# Migrate to ASP.NET Core Identity Auth
Source: https://docs.servicestack.net/auth/migrate-to-identity-auth

## Migrate from ServiceStack Auth to Identity Auth

Migrating from ServiceStack Auth to Identity Auth should be relatively straight-forward as ServiceStack uses a compatible
Identity v2 password hashing format, which should let you migrate your users to Identity Auth without them noticing.

:::info TIP
Please ensure your App database is backed up before performing any migrations
:::

### 1. Rename old AppUser table

You'll want to use a different name so it doesn't conflict with the new Identity `ApplicationUser`. This is only needed
to query the User data to migrate to Identity Auth, you'll be able to remove it after successfully migrating all Users.

You don't need to include all the properties of the `UserAuth` base table, just the ones you want to migrate to Identity Auth,
which for Blazor Diffusion was only:

```csharp
// Used by OrmLite to fetch User data to migrate from old ServiceStack `AppUser` table
[Alias("AppUser")]
public class OldAppUser
{
    [AutoIncrement]
    public int Id { get; set; }
    public string UserName { get; set; }
    public string DisplayName { get; set; }
    public string FirstName { get; set; }
    public string LastName { get; set; }
    public string? Handle { get; set; }
    public string Email { get; set; }
    public string PasswordHash { get; set; }
    public string? ProfileUrl { get; set; }
    public string? Avatar { get; set; } //overrides ProfileUrl
    public string? LastLoginIp { get; set; }
    public DateTime? LastLoginDate { get; set; }
    public string RefIdStr { get; set; }
    public DateTime? LockedDate { get; set; }
    public DateTime CreatedDate { get; set; }
    public DateTime ModifiedDate { get; set; }
}
```

### 2. Create Identity Auth Data Model

If you have a lot of existing references to the `AppUser` name you'll want to retain the same name so the existing references
wont need to be updated. Essentially your custom EF IdentityUser will want a copy of all the properties you want to migrate
other than `Id`, `Email`, and `PasswordHash` that's already defined in the base `IdentityUser` class:

```csharp
[Alias("AspNetUsers")] // Tell OrmLite which table this EF Data Model maps to
public class AppUser : IdentityUser<int>
{
    public string? FirstName { get; set; }
    public string? LastName { get; set; }
    public string? DisplayName { get; set; }
    public string? ProfileUrl { get; set; }
    [Input(Type = "file"), UploadTo("avatars")]
    public string? Avatar { get; set; } //overrides ProfileUrl
    public string? Handle { get; set; }
    public int? RefId { get; set; }
    public string RefIdStr { get; set; } = Guid.NewGuid().ToString();
    public bool IsArchived { get; set; }
    public DateTime? ArchivedDate { get; set; }
    public string? LastLoginIp { get; set; }
    public DateTime? LastLoginDate { get; set; }
    public DateTime CreatedDate { get; set; } = DateTime.UtcNow;
    public DateTime ModifiedDate { get; set; } = DateTime.UtcNow;
}
```

The `AppUser` Data Model and `int` primary key would also need to be registered in your
[Configure.Auth.cs](https://github.com/NetCoreApps/BlazorDiffusionVue/blob/main/BlazorDiffusion/Configure.Auth.cs):

```csharp
public class ConfigureAuth : IHostingStartup
{
    public void Configure(IWebHostBuilder builder) => builder
        .ConfigureAppHost(appHost => {
            appHost.Plugins.Add(new AuthFeature(IdentityAuth.For<AppUser,int>(
                options => {
                    // options.SessionFactory = () => new CustomUserSession(); //optional
                    options.CredentialsAuth();
                })
            ));
        });
}
```

### 3. Add Authentication Configuration

You'll need to configure Entity Framework and add your desired ASP.NET Identity Auth configuration to your **Program.cs**.

We recommend copying from a new Microsoft or ServiceStack .NET 8 Project which closely matches the Authentication
options you want to enable.

#### Using Identity Auth Application Cookie

For example you can start with the recommended Authentication for a new Blazor Project from its [Program.cs](https://github.com/NetCoreTemplates/blazor/blob/main/MyApp/Program.cs):

```csharp
services.AddAuthentication(IdentityConstants.ApplicationScheme)
    .AddIdentityCookies();
services.AddDataProtection()
    .PersistKeysToFileSystem(new DirectoryInfo("App_Data"));

// $ dotnet ef migrations add CreateIdentitySchema
// $ dotnet ef database update
var connectionString = config.GetConnectionString("DefaultConnection") ?? throw new InvalidOperationException("Connection string 'DefaultConnection' not found.");
services.AddDbContext<ApplicationDbContext>(options =>
    options.UseSqlite(connectionString, b => b.MigrationsAssembly(nameof(MyApp))));
services.AddDatabaseDeveloperPageExceptionFilter();

services.AddIdentityCore<ApplicationUser>(options => options.SignIn.RequireConfirmedAccount = true)
    .AddRoles<IdentityRole>()
    .AddEntityFrameworkStores<ApplicationDbContext>()
    .AddSignInManager()
    .AddDefaultTokenProviders();

services.AddSingleton<IEmailSender, NoOpEmailSender>();
services.AddScoped<IUserClaimsPrincipalFactory<ApplicationUser>, AdditionalUserClaimsPrincipalFactory>();
```

#### Using Identity Auth OAuth Providers

Alternatively if you want to add support for external OAuth logins you can copy from the **MVC Tailwind** Authentication
configuration in its [Program.cs](https://github.com/NetCoreTemplates/mvc/blob/main/MyApp/Program.cs) which will
also require adding the NuGet dependencies of the OAuth providers you want to support which you can get from its
[MyApp.csproj](https://github.com/NetCoreTemplates/mvc/blob/main/MyApp/MyApp.csproj)

### 4. Create and Run EF Migrations

After your App is properly configured you'll want to create the EF Migrations for your the Identity Auth User tables
by installing the [dotnet-ef tool](https://learn.microsoft.com/en-us/ef/core/cli/dotnet) and running:

:::sh
dotnet ef migrations add CreateIdentitySchema
:::

Which should create the EF Migrations in the `/Migrations` folder, you can then run the migrations to create the
Identity Auth tables in your App's configured database:

:::sh
dotnet ef database update
:::

### 5. Implement the Migrate Users Task

This could be implemented in a separate Application or Unit Test although we've found the easiest way to migrate existing users
is to implement a custom [App Task](https://docs.servicestack.net/app-tasks) as it's able to make use of your App's configured Authentication, EF and OrmLite dependencies
that can then be run from the command-line.

The implementation should be fairly straight-forward, you'll basically just need to create a new Identity Auth User
using the `UserManager<AppUser>` dependency for each of your existing users:

```csharp
public class ConfigureDbMigrations : IHostingStartup
{
    public void Configure(IWebHostBuilder builder) => builder
        .ConfigureAppHost(appHost => {
            AppTasks.Register("migrate.users", _ => {
                var log = appHost.GetApplicationServices().GetRequiredService<ILogger<ConfigureDbMigrations>>();

                log.LogInformation("Running migrate.users...");
                var scopeFactory = appHost.GetApplicationServices().GetRequiredService<IServiceScopeFactory>();
                using var scope = scopeFactory.CreateScope();
                using var dbContext = scope.ServiceProvider.GetRequiredService<ApplicationDbContext>();
                using var db = scope.ServiceProvider.GetRequiredService<IDbConnectionFactory>().Open();
                var migrateUsers = db.Select(db.From<OldAppUser>().OrderBy(x => x.Id));

                log.LogInformation("Migrating {Count} Existing ServiceStack Users to Identity Auth Users...", migrateUsers.Count);
                MigrateExistingUsers(dbContext, scope.ServiceProvider, migrateUsers).Wait();
            });
            AppTasks.Run();
        });

    private async Task MigrateExistingUsers(ApplicationDbContext dbContext, IServiceProvider services, 
        List<OldAppUser> migrateUsers, string tempPassword="p@55wOrd")
    {
        var userManager = services.GetRequiredService<UserManager<AppUser>>();
        var now = DateTime.UtcNow;

        foreach (var user in migrateUsers)
        {
            var appUser = new AppUser
            {
                Id = user.Id,
                UserName = user.Email,
                Email = user.Email,
                DisplayName = user.DisplayName,
                FirstName = user.FirstName,
                LastName = user.LastName,
                Handle = user.Handle,
                ProfileUrl = user.ProfileUrl,
                Avatar = user.Avatar,
                RefIdStr = user.RefIdStr ?? Guid.NewGuid().ToString(),
                LockoutEnabled = true,
                LockoutEnd = user.LockedDate != null ? now.AddYears(10) : now,
                LastLoginDate = user.LastLoginDate,
                LastLoginIp = user.LastLoginIp,
                CreatedDate = user.CreatedDate,
                ModifiedDate = user.ModifiedDate,
                // Verify you want existing Users emails to be confirmed
                EmailConfirmed = true,
            };
            await userManager.CreateAsync(appUser, tempPassword);

            // Update raw Password Hash using EF
            if (user.PasswordHash != null)
            {
                dbContext.Users
                    .Where(x => x.Id == user.Id)
                    .ExecuteUpdate(setters => setters.SetProperty(x => x.PasswordHash, user.PasswordHash));
            }
        }
    }
}    
```

As there's no official API for updating the raw `PasswordHash` you'll need to use EF's `ExecuteUpdate()` API to update it
on the `AspNetUsers` table directly.

It should be noted that ServiceStack Auth still uses ASP.NET Core's previous Identity v2 format for hashing its passwords,
this will be automatically re-hashed using the latest ASP.NET Identity v3 format after users successfully sign in.

#### Optimizing the PasswordHash Update

Whilst migrating users should be a once-off task, if you have a lot of users you may want to optimize the `PasswordHash` update
from a **N+1** query per user to a single query that updates all users in a single command.

You'll need to use the **UPDATE FROM** syntax that's supported by your RDBMS's, here's an example of how to do it in SQLite:

```sql
UPDATE AspNetUsers
SET PasswordHash = u.PasswordHash
FROM (SELECT Email, PasswordHash FROM AppUser WHERE PasswordHash is NOT NULL) AS u
WHERE u.Email = AspNetUsers.Email;
```

#### Migrating Roles

Migrating Roles will depend how their stored in your App, you'll first need to ensure each role is created in the `AspNetRoles`
table with:

```csharp
string[] allRoles = [...]; // All Roles in your App
var roleManager = services.GetRequiredService<RoleManager<IdentityRole>>();
foreach (var roleName in allRoles)
{
    var roleExist = await roleManager.RoleExistsAsync(roleName);
    if (!roleExist)
    {
        await roleManager.CreateAsync(new IdentityRole(roleName));
    }
}
```

You can then assign Roles to Users using the `UserManager<AppUser>`, e.g:

```csharp
string[] roles = [...]; // Roles to assign to User 
var newUser = await userManager.FindByEmailAsync(user.Email!);
await userManager.AddToRolesAsync(user, roles);
```

### 6. Run the migrate.users Task

With everything in place, all that's left is to run the `migrate.users` App Task from the command-line:

:::sh
dotnet run --AppTasks=migrate.users
:::

### 7. Verify Users can Sign In

After successfully migrating all your users you should check the new `IdentityUser` table to verify all the User data
you want has been migrated as well as verifying they can sign in with their existing credentials.

The easiest way to include the Identity Auth UI Pages to your App is to copy your Application into a new .NET 8 Project
that already includes them, you can create a new Blazor App with:

:::sh
x new blazor ProjectNamespace
:::

Or create a new MVC App with:

:::sh
x new mvc ProjectNamespace
:::

Alternatively you can manually copy the pages from the project template repositories, for Blazor most of the Identity Auth
UI Pages are in the
[Components/Identity](https://github.com/NetCoreTemplates/blazor/tree/main/MyApp/Components/Identity) and
[Pages/Account](https://github.com/NetCoreTemplates/blazor/tree/main/MyApp/Components/Pages/Account) folders.

For MVC, most of the Identity UI are in the
[Account](https://github.com/NetCoreTemplates/mvc/blob/main/MyApp/Controllers/AccountController.cs)
and [Manage](https://github.com/NetCoreTemplates/mvc/blob/main/MyApp/Controllers/ManageController.cs) controllers
as well as their
[Views/Account](https://github.com/NetCoreTemplates/mvc/tree/main/MyApp/Views/Account) and
[Views/Manage](https://github.com/NetCoreTemplates/mvc/tree/main/MyApp/Views/Manage) folders.

### SMTP IEmailSender

The .NET 8 Templates include a nice solution for sending Identity Auth emails through the `IEmailSender` interface
which drops the Email Request in the registered Background MQ in
[Configure.Mq.cs](https://github.com/NetCoreTemplates/blazor/blob/main/MyApp/Configure.Mq.cs)
which uses it to invoke the `SendEmail` API in
[EmailServices](https://github.com/NetCoreTemplates/blazor/blob/main/MyApp.ServiceInterface/EmailServices.cs) in a
managed background worker:

```csharp
public class EmailSender(IMessageService messageService) : IEmailSender
{
    public Task SendEmailAsync(string email, string subject, string htmlMessage)
    {
        using var mqClient = messageService.CreateMessageProducer();
        mqClient.Publish(new SendEmail
        {
            To = email,
            Subject = subject,
            BodyHtml = htmlMessage,
        });

        return Task.CompletedTask;
    }
}
```

To enable it you'll need to register your preferred SMTP Server in your App's `appsettings.json`:

```json
{
  "SmtpConfig": {
    "Username": "username",
    "Password": "password",
    "Host": "smtp.mailtrap.io",
    "Port": 587,
    "FromEmail": "mail@example.org"
  }
}
```

Then replace the `IEmailSender` registration in your `Program.cs`

```csharp
services.AddSingleton<IEmailSender, EmailSender>();
```


# Using IdentityServer4 Auth in ServiceStack
Source: https://docs.servicestack.net/auth/identityserver

[mvcidentityserver](https://github.com/NetCoreTemplates/mvcidentityserver) .NET 6.0 MVC Website integrated with IdentityServer4 Auth and ServiceStack:

[![](https://raw.githubusercontent.com/ServiceStack/Assets/master/csharp-templates/mvcidentityserver.png)](https://github.com/NetCoreTemplates/mvcidentityserver)

The [mvcidentityserver](https://github.com/NetCoreTemplates/mvcidentityserver) builds upon Identity Server's 
[OpenID Connect Hybrid Flow Authentication and API Access Tokens](https://github.com/IdentityServer/IdentityServer4.Samples/tree/master/Quickstarts/5_HybridFlowAuthenticationWithApiAccess)
Quickstart project to include integration with ServiceStack and additional OAuth providers.

The home page has also been customized to contain the same functionality as the other 2 templates with some additional features to validate against custom
OAuth App scopes and **Delegation Auth Pages** showing how to make Authenticated API requests to our remote microservices from within MVC Controllers.

In contrast to integrating Authentication into our App directly, [mvcidentityserver](https://github.com/NetCoreTemplates/mvcidentityserver) configures a central 
**remote IdentityServer instance** with the Auth Features and OAuth providers we want available to our Apps. 

Then when non Authenticated users go to a protected resource they're redirected to the Sign In page on IdentityServer:

[![](https://raw.githubusercontent.com/ServiceStack/Assets/master/csharp-templates/mvcidentityserver-is4.png)](https://github.com/NetCoreTemplates/mvcidentityserver)

Users can sign in using the same Credentials or external OAuth Providers but are presented with an additional **consent** screen to grant the App permission to access their
User profile information and access to custom features the App needs:

[![](https://raw.githubusercontent.com/ServiceStack/Assets/master/csharp-templates/mvcidentityserver-is4-allow.png)](https://github.com/NetCoreTemplates/mvcidentityserver)

Once granted the Auth information is captured in a stateless IdentityServer Token, stored in a cookie and redirected back to the App.

## Physical Project Structure

[mvcidentityserver](https://github.com/NetCoreTemplates/mvcidentityserver) is pre-configured with **3 Host projects**:

 - [/IdentityServer](https://github.com/NetCoreTemplates/mvcidentityserver/tree/master/IdentityServer) - The Central IdentityServer Auth Server (port **5000**)
 - [/ProjectName](https://github.com/NetCoreTemplates/mvcidentityserver/tree/master/MyApp) - Our Hybrid MVC + ServiceStack App (port **5002**)
 - [/ProjectName.Api](https://github.com/NetCoreTemplates/mvcidentityserver/tree/master/MyApp.Api) - Example Microservice API used by Hybrid App (port **5001**)

## IdentityServer

The IdentityServer instance is configured in [Startup.cs](https://github.com/NetCoreTemplates/mvcidentityserver/blob/master/IdentityServer/Startup.cs) 
which contains all **external OAuth providers** we want to allow Sign Ins from, the **OpenId Connect Endpoint** which allows Sign Ins from another external 
IdentityServer on [demo.identityserver.io](https://demo.identityserver.io/) and all its pre-configured Users, Identity Resources, API Resources and Clients 
defined in [Config.cs](https://github.com/NetCoreTemplates/mvcidentityserver/blob/master/IdentityServer/Config.cs).

## App

The App's [Startup.cs](https://github.com/NetCoreTemplates/mvcidentityserver/blob/master/MyApp/Startup.cs) consists of configuring the OpenId Connect Endpoint
to our Central **IdentityServer** containing additional customizations to control what `Claims` the Authenticated `ClaimsPrincipal` will have:

```csharp
services.AddAuthentication(options =>
    {
        options.DefaultScheme = "Cookies";
        options.DefaultChallengeScheme = "oidc";
    })
    .AddCookie("Cookies")
    .AddOpenIdConnect("oidc", options =>
    {
        options.SignInScheme = "Cookies";

        options.Authority = "https://localhost:5000";
        options.RequireHttpsMetadata = false;

        options.ClientId = "mvc";
        options.ClientSecret = "secret";
        options.ResponseType = "code id_token";

        options.SaveTokens = true;
        options.GetClaimsFromUserInfoEndpoint = true;

        options.Scope.Add("api1");
        options.Scope.Add("offline_access");
        
        options.ClaimActions.MapJsonKey("website", "website");
        options.ClaimActions.MapJsonKey("role", "role");
        options.ClaimActions.Add(new AdminRolesClaimAction("Manager", "Employee"));
        
        options.TokenValidationParameters = new TokenValidationParameters
        {
            NameClaimType = "name",
            RoleClaimType = "role"
        };

        options.Events = new OpenIdConnectEvents {
            OnRemoteFailure = CustomHandlers.HandleCancelAction,
            OnTokenResponseReceived = CustomHandlers.CopyAllowedScopesToUserClaims,                        
        };
    });
```

## ASP.NET Core Identity Auth Adapter

The only customization needed in ServiceStack is to specify the different custom name being used for `RoleClaimType`:

```csharp
Plugins.Add(new AuthFeature(() => new CustomUserSession(), 
    new IAuthProvider[] {
        // Adapter to enable ASP.NET Core Identity Auth in ServiceStack
        new NetCoreIdentityAuthProvider(AppSettings) {
            RoleClaimType = "role"
        }, 
    }));
```

The `MapJsonKey` contains a whitelist of properties in Identity Server's Token we want propagated to `Claims`. 
The `AdminRolesClaimAction` is a custom `ClaimAction` we can use to add additional `AdminRoles` to users with the `RoleNames.Admin` role:

```csharp
/// <summary>
/// Use this class to assign additional roles to Admin Users
/// </summary>
public class AdminRolesClaimAction : ClaimAction
{
    string[] AdminRoles { get; }
    public AdminRolesClaimAction(params string[] adminRoles) : base("role", null) => AdminRoles = adminRoles;

    public override void Run(JObject userData, ClaimsIdentity identity, string issuer)
    {
        if (!HasAdminRole(userData)) return;
        foreach (var role in AdminRoles)
        {
            identity.AddClaim(new Claim("role", role));
        }
    }

    private bool HasAdminRole(JObject userData)
    {
        var jtoken = userData?[this.ClaimType];
        if (jtoken is JValue)
        {
            if (jtoken?.ToString() == RoleNames.Admin)
                return true;
        }
        else if (jtoken is JArray)
        {
            foreach (var obj in jtoken)
                if (obj?.ToString() == RoleNames.Admin)
                    return true;
        }
        return false;
    }
}
```

The `OpenIdConnectEvents` lets us intercept the original IdentityServer token so we can extract the custom **OAuth scopes** the User 
has granted the App and add them to `scope` Claims:

```csharp
public static class CustomHandlers
{
    /// <summary>
    /// Use this handler to copy requested Scopes to User Claims so they can be validated using a Policy  
    /// </summary>
    public static Task CopyAllowedScopesToUserClaims(TokenResponseReceivedContext context)
    {
        var scopes = context.ProtocolMessage.Scope?.Split(' ');
        if (scopes != null && context.Principal.Identity is ClaimsIdentity identity)
        {
            foreach (var scope in scopes)
            {
                identity.AddClaim(new Claim("scope", scope));
            }
        }
        return Task.CompletedTask;
    }

    public static Task HandleCancelAction(RemoteFailureContext context)
    {
        context.Response.Redirect("/");
        context.HandleResponse();
        return Task.CompletedTask;
    }
}
```

Now that our populated claims contains the granted OAuth scopes we can validate against it in ServiceStack Services using the new `[RequiredClaim]` attribute:

```csharp
[RequiredClaim("scope", "profile")]
public object Any(RequiresScope request)
{
    return new RequiresScopeResponse { Result = $"Hello, {request.Name}!" };
}
```

In MVC we need create a custom Auth Policy:

```csharp
services.AddAuthorization(options => {
    options.AddPolicy("ProfileScope", policy =>
        policy.RequireClaim("scope", "profile"));
});
```

That can then be used in our MVC Controllers using the `[Authorize]` attribute, referencing our custom policy: 

```csharp
[Authorize(Policy = "ProfileScope")]
public async Task<IActionResult> RequiresScope()
{
    var accessToken = await HttpContext.GetTokenAsync("access_token");

    return View();
}
```

### Delegated Auth Pages

[mvcidentityserver](https://github.com/NetCoreTemplates/mvcidentityserver) also contains examples showing how to make
Authenticated API Requests to a remote Web API Service using `HttpClient`:

```csharp
public async Task<IActionResult> CallWebApi()
{
    var accessToken = await HttpContext.GetTokenAsync("access_token");

    var client = new HttpClient();
    client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", accessToken);
    var content = await client.GetStringAsync("https://localhost:5001/webapi-identity");

    ViewBag.Json = JArray.Parse(content).ToString();
    return View("json");
}
```

The same `HttpClient` request to call an Authenticated ServiceStack Service:

```csharp
public async Task<IActionResult> CallServiceStack()
{
    var accessToken = await HttpContext.GetTokenAsync("access_token");

    var client = new HttpClient();
    client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", accessToken);
    client.DefaultRequestHeaders.Accept.Add(new MediaTypeWithQualityHeaderValue(MimeTypes.Json)); 
    var json = await client.GetStringAsync("https://localhost:5001/servicestack-identity");

    ViewBag.Json = json.IndentJson();
    return View("json");
}
```

We need the additional `Accept` JSON HTTP header to tell ServiceStack which of the registered Content Types 
we want to receive the response in.

Alternatively we can make Authenticated Requests using the more typed and terse [C#/.NET Service Client](/csharp-client):

```csharp
public async Task<IActionResult> CallServiceClient()
{
    var accessToken = await HttpContext.GetTokenAsync("access_token");

    var client = new JsonApiClient("https://localhost:5001/") {
        BearerToken = accessToken
    };
    var response = await client.GetAsync(new GetIdentity());

    ViewBag.Json = response.ToJson().IndentJson();
    return View("json");
}
```

## API

The API's [Startup.cs](https://github.com/NetCoreTemplates/mvcidentityserver/blob/master/MyApp.Api/Startup.cs) is configured to accept 
Bearer Tokens issued by our central **IdentityServer**:

```csharp
services.AddAuthentication("Bearer")
    .AddJwtBearer("Bearer", options => {
        options.Authority = "https://localhost:5000";
        options.RequireHttpsMetadata = false;

        options.Audience = "api1";
    });
```

Nothing special is needed for ServiceStack here other than registering the Identity Auth Provider adapter:

```csharp
Plugins.Add(new AuthFeature(() => new AuthUserSession(), 
    new IAuthProvider[] {
        new NetCoreIdentityAuthProvider(AppSettings), 
    }));
```

The `GetIdentity` ServiceStack Service then returns the populated `AuthUserSession` and all claims contained in the Bearer Token:

```csharp
[Route("/servicestack-identity")]
public class GetIdentity : IReturn<GetIdentityResponse> { }

public class GetIdentityResponse
{
    public List<Property> Claims { get; set; }
    public AuthUserSession Session { get; set; }
}

[Authenticate]
public class IdentityService : Service
{
    public object Any(GetIdentity request)
    {
        return new GetIdentityResponse {
            Claims = Request.GetClaims().Map(x => new Property { Name = x.Type, Value = x.Value }),
            Session = SessionAs<AuthUserSession>(),
        };
    }
}
```


# Authentication and Authorization
Source: https://docs.servicestack.net/auth/authentication-and-authorization

Built into ServiceStack is a simple and extensible Authentication Model that implements standard HTTP Session Authentication where 
[Session Cookies](/auth/sessions) are used to send Authenticated Requests which reference Users Custom UserSession POCO's in your App's 
registered [Caching Provider](/caching). 

ServiceStack also includes a number of Auth Providers which "Authenticate per-request" in this case the Authenticated User Session
is only attached to and lasts during the lifetime of the current `IRequest`. The implementation details of each Auth Provider are 
transparent to your Application where the same Attributes and APIs are used to retrieve, validate, authenticate and authorize Users.

ServiceStack's Authentication support is encapsulated in the optional `AuthFeature` plugin which provides an easy way to declaratively 
register and configure multiple Auth Providers you want to allow in your Application. It's highly configurable with a number of 
additional features like whether to enable built-in Registration for Registering new Users as well as Assign/UnAssign Roles Services
that Admins can use to assign Roles/Permissions to existing users.

<lite-youtube class="w-full mx-4 my-4" width="560" height="315" videoid="XKq7TkZAzeg" style="background-image: url('https://img.youtube.com/vi/XKq7TkZAzeg/maxresdefault.jpg')"></lite-youtube>

<div class="not-prose mx-auto px-8">
  <h3 id="identityauth-template" class="mb-4 text-4xl tracking-tight font-extrabold text-gray-900">
      Create a Project with ServiceStack Auth
  </h3>
  <servicestack-auth-templates></servicestack-auth-templates>
</div>

### Highly customizable and versatile

ServiceStack's Authentication is also highly customizable and versatile from being able to choose from the plethora of Auth Providers
available or inheriting from them to create your own customized Auth Provider, inheriting `AuthUserSession` to use your own Custom POCO
with additional info you want to maintain for your Users, storing User Sessions in any of the available [Caching Providers](/caching), 
adding custom logic by handling any of the [Auth and Session Events](/auth/sessions#session-events) raised throughout the Auth lifecycle,
to specifying which back-end [Auth Repository](/auth/auth-repository) you want to persist your Authenticated Users in - supporting most popular RDBMS's and 
popular NoSQL data stores as seen in the high-level overview below:

### High Level Overview

![Authentication Overview](/img/pages/security/auth-highlevel-overview.svg?sanitize=true)

The `AuthenticateService` is the primary Service that manages Authentication which delegates to the specified Auth Provider that 
performs the Authentication, made available via its following endpoints:

 - `/auth/{provider}` - Authenticate against a specific Auth Provider
 - `/auth` - API to check if a Request is authenticated: returns **200** with basic session info if authenticated or **401** if not.
 - `/auth/logout` - Removes the Authenticated Session from the registered cache and clears Session Cookies.

### Credentials Auth Providers

If you would like ServiceStack to manage your Apps entire Authentication and persistence of Users you would use one of the available Auth Repositories
and authenticate against one of the following Auth Providers:

| Provider          | Class Name                  | Route                    | Description |
|-|-|-|-|
| **Credentials**   | `CredentialsAuthProvider`   | **/auth/credentials**    | Standard Authentication using Username/Password |
| **Basic Auth**    | `BasicAuthProvider`         | HTTP Basic Auth          | Username/Password sent via [HTTP Basic Auth](https://en.wikipedia.org/wiki/Basic_access_authentication) |
| **Digest Auth**   | `DigestAuthProvider`        | HTTP Digest Auth         | Username/Password hash via [HTTP Digest Auth](https://en.wikipedia.org/wiki/Digest_access_authentication) |

New Users can be created via the `/register` Registration Service which be enabled with:

```csharp
Plugins.Add(new RegistrationFeature());
```

### OAuth Providers

The following OAuth Providers are built into ServiceStack and can be used in both ASP.NET Core and .NET Framework Apps:

| Provider          | Class Name                   | Route                    | Create OAuth App Link |
|-|-|-|-|
| **Facebook**      | `FacebookAuthProvider`       | **/auth/facebook**       | [developers.facebook.com/apps](https://developers.facebook.com/apps) |
| **Twitter**       | `TwitterAuthProvider`        | **/auth/twitter**        | [dev.twitter.com/apps](https://dev.twitter.com/apps) |
| **Google**        | `GoogleAuthProvider`         | **/auth/google**         | [console.developers.google.com](https://console.developers.google.com/apis/credentials) |
| **GitHub**        | `GithubAuthProvider`         | **/auth/github**         | [github.com/settings/applications/new](https://github.com/settings/applications/new) |
| **Microsoft**     | `MicrosoftGraphAuthProvider` | **/auth/microsoftgraph** | [apps.dev.microsoft.com](https://apps.dev.microsoft.com) |
| **LinkedIn**      | `LinkedInAuthProvider`       | **/auth/linkedin**       | [www.linkedin.com/secure/developer](https://www.linkedin.com/secure/developer) |
| **Yammer**        | `YammerAuthProvider`         | **/auth/yammer**         | [www.yammer.com/client_applications](http://www.yammer.com/client_applications) |
| **Yandex**        | `YandexAuthProvider`         | **/auth/yandex**         | [oauth.yandex.ru/client/new](https://oauth.yandex.ru/client/new) |
| **VK**            | `VkAuthProvider`             | **/auth/vkcom**          | [vk.com/editapp?act=create](http://vk.com/editapp?act=create) |
| **Odnoklassniki** | `OdnoklassnikiAuthProvider`  | **/auth/odnoklassniki**  | [www.odnoklassniki.ru/devaccess](http://www.odnoklassniki.ru/devaccess) |

<lite-youtube class="w-full mx-4 my-4" width="560" height="315" videoid="aQqF3Sf2fco" style="background-image: url('https://img.youtube.com/vi/aQqF3Sf2fco/maxresdefault.jpg')"></lite-youtube>

### Session Authentication Overview

The diagram below outlines how standard session based Authentication works and how the different providers interact in more detail:

![Session Based Authentication](/img/pages/security/auth-session-auth.svg?sanitize=true)

Where the **Auth Provider** are unique for each Auth Provider but otherwise adopt the same Authentication process that results
in the same end result where an Authenticated `AuthUserSession` is persisted in the registered `ICacheClient` against the `ss-pid` Permanent Cookie
if the `Authenticate` request `RememberMe=true` otherwise against `ss-id` Temporary Session Cookie if not.

After a Request is Authenticated its Session Cookies are sent on subsequent requests and validated by ServiceStack's built in `[Authenticate]` and 
other `[Require*]` attributes to restrict access to valid users:

![Session Requests](/img/pages/security/auth-session-requests.svg?sanitize=true)

Once authenticated the Users Session can be accessed in your **Services** using the Typed and minimal `IAuthSession` APIs:

```csharp
AuthUserSession session = base.SessionAs<AuthUserSession>();
IAuthSession session = base.GetSession();
```

Of if you've registered to use a Custom UserSession POCO in the `AuthFeature` constructor use that instead of `AuthUserSession`.

Typed User Sessions also accessible in all Filters and handlers that have access to the current `IRequest` with:

```csharp
AuthUserSession session = req.SessionAs<AuthUserSession>();
IAuthSession session = req.GetSession();
```

See the [Session docs](/auth/sessions) for more info about customizing Sessions and handling different Session and Auth events.

### Authentication per Request Auth Providers

These Auth Providers include authentication with each request so the Authenticated User Session is only populated on the HTTP `IRequest` and not saved in the registered Cache Client. Unlike traditional Auth Providers above where there is a separate "Authentication" request to establish authentication, 
Auth Providers that implement `IAuthWithRequest` instead send their Authentication "per-request" where it's only populated on the current `IRequest`:

![Auth with Request Auth Providers](/img/pages/security/auth-auth-with-request-providers.svg?sanitize=true)

Whilst the Authentication Process is different you'd continue to use the same APIs and Attributes to access and validate the Users Session. 

The following Auth Providers below implement `IAuthWithRequest` and Authenticate per-request:

| Provider          | Class Name                   | Auth Method  | Description |
|-|-|-|-|
| **JWT**           | `JwtAuthProvider`            | Bearer Token | Stateless Auth Provider using [JSON Web Tokens](/auth/jwt-authprovider)  |
| **API Keys**      | `ApiKeyAuthProvider`         | Bearer Token | Allow 3rd Parties access to [authenticate without a password](/auth/api-key-authprovider) |
| **Basic Auth**    | `BasicAuthProvider`          | Basic Auth   | Authentication using [HTTP Basic Auth](https://en.wikipedia.org/wiki/Basic_access_authentication) |
| **Digest Auth**   | `DigestAuthProvider`         | Digest Auth  | Authentication using [HTTP Digest Auth](https://en.wikipedia.org/wiki/Digest_access_authentication) |

<lite-youtube class="w-full mx-4 my-4" width="560" height="315" videoid="NTCUT7atoLo" style="background-image: url('https://img.youtube.com/vi/NTCUT7atoLo/maxresdefault.jpg')"></lite-youtube>

Some other special Auth Providers that Authenticate per-request include:

 - **Windows Auth** in `AspNetWindowsAuthProvider`  - Authentication using [Windows Auth](https://support.microsoft.com/en-us/help/323176/how-to-implement-windows-authentication-and-authorization-in-asp-net) built into ASP.NET.
 - **Claims Auth** in `NetCoreIdentityAuthProvider` - Pass through Auth Provider that delegates to ASP.NET Core Identity Auth or Identity Server.

### Integrated ASP.NET Core Authentication

The `NetCoreIdentityAuthProvider` is a bi-directional Authentication adapter that enables ServiceStack to use the same Authentication as the 
rest of your ASP.NET Core and MVC Application where it enables the following popular scenarios:

 - [Using ServiceStack Auth in MVC](/auth/identity-servicestack) - Use ServiceStack Auth to power ASP.NET Identity Auth, pre-configured in the [mvcauth](https://github.com/NetCoreTemplates/mvcauth) project template. 
 - [Using IdentityServer4 Auth in ServiceStack](/auth/identityserver) - Use IdentityServer4 to Authenticate ASP.NET Core and ServiceStack Services, 
pre-configured in the [mvcidentityserver](https://github.com/NetCoreTemplates/mvcidentityserver) project template.

### Community Auth Providers

  - [Azure Active Directory](https://github.com/jfoshee/ServiceStack.Authentication.Aad) - Allow Custom App to login with Azure Active Directory
  - [Azure Active Directory via Azure Graph for ServiceStack](https://github.com/ticky74/ServiceStack.Authentication.Azure)
  - [ServiceStack.Authentication.IdentityServer](https://github.com/MacLeanElectrical/servicestack-authentication-identityserver) - Integration with ASP.NET IdentityServer and provides OpenIDConnect / OAuth 2.0 Single Sign-On Authentication

### Basic Configuration

A minimal configuration needed to get Basic Authentication up and running is the following in `AppHost.Config()` (derived from the [AuthTests unit test](https://github.com/ServiceStack/ServiceStack/blob/master/tests/ServiceStack.WebHost.Endpoints.Tests/AuthTests.cs)):

```csharp 
public override void Configure(Container container)
{
    Plugins.Add(new AuthFeature(() => new AuthUserSession(),
        new IAuthProvider[] { 
            new BasicAuthProvider(),       //Sign-in with HTTP Basic Auth
            new CredentialsAuthProvider(), //HTML Form post of UserName/Password credentials
        }));

    container.Register<ICacheClient>(new MemoryCacheClient());

    var userRepo = new InMemoryAuthRepository();
    container.Register<IAuthRepository>(userRepo);
    
    //The IAuthRepository is used to store the user credentials etc.
    //Implement this interface to adjust it to your app's data storage
}
```

[AuthWebTests](https://github.com/ServiceStack/ServiceStack/blob/master/tests/ServiceStack.AuthWeb.Tests/) is a simple project that shows all Auth Providers configured and working in the same app. See the [AppHost](https://github.com/ServiceStack/ServiceStack/blob/master/tests/ServiceStack.AuthWeb.Tests/AppHost.cs) for an example of the code and the [Web.config](https://github.com/ServiceStack/ServiceStack/blob/master/tests/ServiceStack.AuthWeb.Tests/Web.config) for an example of the configuration required to enable each Auth Provider.

### OAuth Configuration

Once you have the `ConsumerKey` and `ConsumerSecret` you need to configure it with your ServiceStack host, via [Web.config](https://github.com/ServiceStack/ServiceStack/blob/master/tests/ServiceStack.AuthWeb.Tests/Web.config), e.g:

```xml
<add key="oauth.RedirectUrl"            value="https://yourhostname.com"/>
<add key="oauth.CallbackUrl"            value="https://yourhostname.com/auth/{0}"/>    
<add key="oauth.twitter.ConsumerKey"    value="3H1FHjGbA1N0n0aT5yApA"/>
<add key="oauth.twitter.ConsumerSecret" value="MLrZ0ujK6DwyjlRk2YLp6HwSdoBjtuqwXeHDQLv0Q"/>
```

For [.NET Core](/web-new) or [ASP.NET Core Apps](/templates/corefx) you can add the same keys to your `appsettings.json`, e.g:

```json
{
    "oauth.RedirectUrl":            "https://yourhostname.com",
    "oauth.CallbackUrl":            "https://yourhostname.com/auth/{0}",
    "oauth.twitter.ConsumerKey":    "3H1FHjGbA1N0n0aT5yApA",
    "oauth.twitter.ConsumerSecret": "MLrZ0ujK6DwyjlRk2YLp6HwSdoBjtuqwXeHDQLv0Q",
}
```

Each OAuth Config option fallbacks to the configuration without the provider name. If needed you provide OAuth specific configuration
by including the Auth Provider Name in the configuration, e.g:

```xml
<add key="oauth.twitter.RedirectUrl"    value="https://yourhostname.com"/>
<add key="oauth.twitter.CallbackUrl"    value="https://yourhostname.com/auth/twitter"/>    
```

Configuration can also be specified in code when registering the Auth Provider in the `AuthFeature` plugin in your AppHost, e.g:

```csharp
Plugins.Add(new AuthFeature(() => new AuthUserSession(), new IAuthProvider[] {
    new TwitterAuthProvider(appSettings) { 
        RedirectUrl = "http://yourhostname.com/",
        CallbackUrl = "http://yourhostname.com/auth/twitter",
        ConsumerKey = "3H1FHjGbA1N0n0aT5yApA",
        ConsumerSecret = "MLrZ0ujK6DwyjlRk2YLp6HwSdoBjtuqwXeHDQLv0Q",
    },
}));
```

::: info
The Callback URL in each Application should match the CallbackUrl for your application which is typically: http://yourhostname.com/auth/{Provider}, e.g. http://yourhostname.com/auth/twitter for Twitter.
:::

### Allowing External Redirects

External Redirects used in the `?continue` params of `/auth` requests are disabled by default, they can be re-enabled with:

```csharp
new AuthFeature(...) {
    ValidateRedirectLinks = AuthFeature.AllowAllRedirects 
}
```

### Auth Repository

ServiceStack supports managing Users in multiple data stores via its [Auth Repository](/auth/auth-repository) abstraction and built-in providers.

### Session Persistence

Once authenticated the **AuthUserSession** model is populated and stored in the Cache using one of ServiceStack's [supported Caching providers](/caching). ServiceStack's Sessions simply uses the 
[ICacheClient](https://github.com/ServiceStack/ServiceStack/blob/master/src/ServiceStack.Interfaces/Caching/ICacheClient.cs)
API so any new provider added can be used for both Session and Caching, which currently includes:

  - **Memory**: `MemoryCacheClient` in [ServiceStack](https://nuget.org/packages/ServiceStack)
  - **Redis**: `RedisClient`, `PooledRedisClientManager` or `BasicRedisClientManager` in [ServiceStack.Redis](https://nuget.org/packages/ServiceStack.Redis)
  - **OrmLite**: `OrmLiteCacheClient` in [ServiceStack.Server](https://nuget.org/packages/ServiceStack.Server)
  - **AWS DynamoDB**: `DynamoDbCacheClient` in [ServiceStack.Aws](https://nuget.org/packages/ServiceStack.Aws)
  - **Memcached**: `MemcachedClientCache` in [ServiceStack.Caching.Memcached](https://nuget.org/packages/ServiceStack.Caching.Memcached)
  - **Azure**: `AzureTableCacheClient` in [ServiceStack.Azure](https://nuget.org/packages/ServiceStack.Azure)

The Auth Feature also allows you to specify your own custom `IUserAuthSession` type where you can capture additional metadata with your users session which will also get persisted and hydrated from the cache, e.g: 

```csharp
Plugins.Add(new AuthFeature(() => new CustomUserSession(), 
    ...
));
```

::: info
If you're using Custom Sessions and have `JsConfig.ExcludeTypeInfo=true`, you need to [explicitly enable it](http://stackoverflow.com/q/18842685/85785) with `JsConfig<TCustomSession>.IncludeTypeInfo=true`.
:::

After authentication the client will receive a cookie with a session id, which is used to fetch the correct session from the `ICacheClient` internally by ServiceStack. Thus, you can access the current session in a service:

```csharp
public class SecuredService : Service
{
    public object Get(Secured request)
    {
        var session = this.SessionAs<AuthUserSession>();
        return new SecuredResponse() { Test = "You're" + session.FirstName };
    }
}
```

ServiceStack's Authentication, Caching and Session providers are completely new, clean, dependency-free testable APIs that doesn't rely on and is devoid of ASP.NET's existing membership, caching or session provider models. 

### AuthSecret Admin Session

Super User Requests using [Config.AdminAuthSecret](/debugging#authsecret) return an Authenticated Admin UserSession 
whose default values can be modified at `AuthFeature.AuthSecretSession`:

 - `DisplayName`: Admin
 - `UserName`: authsecret
 - `AuthProvider`: authsecret
 - `Roles`: Admin
 - `UserAuthId`: 0

### Embedded Login Page

`AuthFeature` adds a fallback **/login.html** page if the `HtmlRedirect` remains unchanged and no `/login.html` exists, otherwise
if using a custom `/login` page in either **Razor** or **Script Pages** they'll continue to be used instead.

The default `/login.html` page provides an auto Login page that supports authentication via Credentials as well as a generating a dynamic 
list of OAuth providers, e.g the [NorthwindCrud](https://github.com/NetCoreApps/NorthwindCrud) `/login` page with Facebook OAuth looks like:

![](/img/pages/release-notes/v5.9/auth-login.png)

If you're using an SPA App with client side routing to implement `/login`, the default login page can be disabled with:

```csharp
new AuthFeature {
    IncludeDefaultLogin = false
}
```

The login page supports same `continue` or `ReturnUrl` redirect params as [Logout API](#logout).

## World Validation

See the annotated [World Validation Docs](/world-validation) for a detailed walks through and showcases the implementation 
of how the most popular **Server HTML rendered** approaches and **Client UI rendered** technologies use the same built-in
Authentication, Registration and protected Services.

## Project Templates

Most of [ServiceStack's Project Templates](/dotnet-new) are configured with Auth out-of-the-box or can be easily added to an empty [web](https://github.com/NetCoreTemplates/web)
project template:

:::sh
x new web ProjectName
:::

By [mixing in your desired auth](/mix-tool#mix-in-auth-repository) features, e.g. to configure your App to enable auth & maintain in SQL Server run:

:::sh
x mix auth auth-db sqlserver
:::

Checkout the [Bookings CRUD YouTube demo](https://youtu.be/XpHAaCTV7jE) for a quick preview of this in action.

## Live Demos

To illustrate Authentication integration with ServiceStack, see the authentication-enabled 
[Live Demos](https://github.com/NetCoreApps/LiveDemos) below:

### .NET Core

  - [Apple Sign In](https://github.com/NetCoreApps/AppleSignIn)
    - Apple Auth
  - [Bookings CRUD](https://github.com/NetCoreApps/BookingsCrud)
    - Credentials, Facebook, Google, Microsoft Auth
  - [New TechStacks](https://github.com/NetCoreApps/TechStacks)
    - GitHub, Twitter and JWT Auth
  - [SimpleAuth.Mvc](https://github.com/NetCoreApps/SimpleAuth.Mvc)
    - Twitter, Facebook, GitHub, VK, Yandex and Credentials Auth
  - [Chat](https://github.com/NetCoreApps/Chat)
    - Twitter, Facebook and GitHub Auth

### Mobile

  - [Android Java Chat](https://github.com/ServiceStackApps/AndroidJavaChat)
    - Facebook, Twitter and Google Auth
  - [Android Xamarin Chat](https://github.com/ServiceStackApps/AndroidXamarinChat)
    - Twitter Auth

### .NET Framework

  - [HttpBenchmarks Application](https://github.com/ServiceStackApps/HttpBenchmarks)
    - [Step-by-Step Authentication Guide](https://github.com/ServiceStackApps/HttpBenchmarks#authentication)
    - Twitter, Facebook, Google, LinkedIn and Credentials Auth
  - [Angular TechStacks](https://github.com/ServiceStackApps/TechStacks)
    - Twitter, GitHub and JWT Auth
  - [Gistlyn](https://github.com/ServiceStack/Gistlyn)
    - GitHub and JWT Auth
  - [AWS Auth](https://github.com/ServiceStackApps/AwsApps) 
    - Twitter, Facebook, GitHub, Google, Yahoo, LinkedIn, and Credentials Auth
  - [MVC and WebForms Example](/servicestack-integration) 
    - Twitter, Facebook, GitHub, Google, Yahoo, LinkedIn, VK, Credentials and Windows Auth
  - [Chat](https://github.com/ServiceStackApps/LiveDemos#chat)
    - Twitter, Facebook and GitHub Auth
  - [React Chat](https://github.com/ServiceStackApps/ReactChat)
    - Twitter, Facebook and GitHub Auth
  - [SocialBootstrap Api](https://github.com/ServiceStackApps/LiveDemos#social-bootstrap-api)
    - Twitter, Facebook, Yahoo and Credentials Auth

## Custom authentication and authorization

A good starting place to create your own Auth provider that relies on username/password validation is to subclass `CredentialsAuthProvider` and override the `bool TryAuthenticate(service, username, password)` method where you can provide your custom implementation. If you instead wanted to authenticate via HTTP Basic Auth
you would subclass `BasicAuthProvider` instead.

Both the default [BasicAuthProvider](https://github.com/ServiceStack/ServiceStack/blob/master/src/ServiceStack/Auth/BasicAuthProvider.cs) and [CredentialsAuthProvider](https://github.com/ServiceStack/ServiceStack/blob/master/src/ServiceStack/Auth/CredentialsAuthProvider.cs) (which it extends) can be extended, and their behavior overwritten. An example is below:

#### Async Custom AuthProvider

```csharp
using ServiceStack;
using ServiceStack.Auth;

// From v5.10+
public class CustomCredentialsAuthProvider : CredentialsAuthProvider
{
    public override async Task<bool> TryAuthenticateAsync(IServiceBase authService, 
        string userName, string password, CancellationToken token=default)
    {
        //Add here your custom auth logic (database calls etc)
        //Return true if credentials are valid, otherwise false
    }

    public override async Task<IHttpResult> OnAuthenticatedAsync(IServiceBase authService, 
        IAuthSession session, IAuthTokens tokens, Dictionary<string, string> authInfo, 
        CancellationToken token=default)
    {
        //Fill IAuthSession with data you want to retrieve in the app eg:
        session.FirstName = "some_firstname_from_db";
        //...

        //Call base method to Save Session and fire Auth/Session callbacks:
        return await base.OnAuthenticatedAsync(authService, session, tokens, authInfo, token);

        //Alternatively avoid built-in behavior and explicitly save session with
        //session.IsAuthenticated = true;
        //await authService.SaveSessionAsync(session, SessionExpiry, token);
        //authService.Request.Items[Keywords.DidAuthenticate] = true;
        //return null;
    }
}
```

#### Sync Custom AuthProvider

```csharp
using ServiceStack;
using ServiceStack.Auth;

public class CustomCredentialsAuthProvider : CredentialsAuthProviderSync
{
    public override bool TryAuthenticate(IServiceBase authService, 
        string userName, string password)
    {
        //Add here your custom auth logic (database calls etc)
        //Return true if credentials are valid, otherwise false
    }

    public override IHttpResult OnAuthenticated(IServiceBase authService, 
        IAuthSession session, IAuthTokens tokens, 
        Dictionary<string, string> authInfo)
    {
        //Fill IAuthSession with data you want to retrieve in the app eg:
        session.FirstName = "some_firstname_from_db";
        //...

        //Call base method to Save Session and fire Auth/Session callbacks:
        return base.OnAuthenticated(authService, session, tokens, authInfo);

        //Alternatively avoid built-in behavior and explicitly save session with
        //session.IsAuthenticated = true;
        //authService.SaveSession(session, SessionExpiry);
        //authService.Request.Items[Keywords.DidAuthenticate] = true;
        //return null;
    }
}
```
 
Then you need to register your custom credentials auth provider: 
 
```csharp
//Register all Authentication methods you want to enable for this web app.
Plugins.Add(new AuthFeature(() => new AuthUserSession(),
    new IAuthProvider[] {
        new CustomCredentialsAuthProvider(), //HTML Form post of User/Pass
    }
));
```

By default the AuthFeature plugin automatically registers the following (overridable) Service Routes:

```csharp
new AuthFeature = {
  ServiceRoutes = new Dictionary<Type, string[]> {
    { typeof(AuthenticateService),  new[]{ "/auth", "/auth/{provider}" }},
    { typeof(AssignRolesService),   new[]{ "/assignroles" }},
    { typeof(UnAssignRolesService), new[]{ "/unassignroles" }},
  }
};
```

### Logout

You can do a GET or POST to `/auth/logout` to logout the authenticated user or if you're using C# client you can logout with:

```csharp
client.Post(new Authenticate { provider = "logout" });
```

#### Redirect URL

Logging out will remove the Users Session from the Server and Session Cookies from the Client and redirect to the url in 
`continue`, `ReturnUrl` or configured `AuthFeature.HtmlRedirectReturnParam` **QueryString** or **FormData** Request param. 
If no redirect is specified it will fallback to redirect to `session.ReferrerUrl`, `Referer` HTTP Header or configured `AuthProvider.CallbackUrl`.

### Authenticating with .NET Service Clients

On the client you can use the [C#/.NET Service Clients](/csharp-client) to easily consume your authenticated Services.

To authenticate using your `CustomCredentialsAuthProvider` by POST'ing a `Authenticate` Request, e.g:

```csharp
var client = new JsonApiClient(BaseUrl);

var authResponse = client.Post(new Authenticate {
    provider = CredentialsAuthProvider.Name, //= credentials
    UserName = "test@gmail.com",
    Password = "p@55w0rd",
    RememberMe = true,
});
```

If authentication was successful the Service Client `client` instance will be populated with authenticated session cookies which then allows calling Authenticated services, e.g:

```csharp
var response = client.Get(new GetActiveUserId());
```

If you've also registered the `BasicAuthProvider` it will enable your Services to accept [HTTP Basic Authentication](https://en.wikipedia.org/wiki/Basic_access_authentication) which is built-in the Service Clients that you can populate on the Service Client with:

```csharp
client.UserName = "test@gmail.com";
client.Password = "p@55w0rd";
```

Which will also let you access protected Services, e.g:

```csharp
var response = client.Get(new GetActiveUserId());
```

Although behind-the-scenes it ends up making 2 requests, 1st request sends a normal request which will get rejected with a `401 Unauthorized` and if the Server indicates it has the `BasicAuthProvider` enabled it will resend the request with the HTTP Basic Auth credentials. 

You could instead save the latency of the additional auth challenge request by specifying the client should always send the Basic Auth with every request:

```csharp
client.AlwaysSendBasicAuthHeader = true;
```

### Authenticating with HTTP

To Authenticate with your `CustomCredentialsAuthProvider` (which inherits from CredentialsAuthProvider) you would POST:

**POST** localhost:60339/auth/credentials?format=json

```json
{
    "UserName": "admin",
    "Password": "test",
    "RememberMe": true
}
```

When the client now tries to authenticate with the request above and the auth succeeded, the client will retrieve some cookies with a session id which identify the client on each Web Service call.

### Authentication via OAuth AccessTokens 

To improve OAuth Sign In integration from native Mobile or Desktop Apps you can also Authenticate via AccessTokens which can dramatically simplify the Development and User Experience by being able to leverage the Native Facebook, Twitter and Google Client SDK's to Sign In users locally then reuse their local **AccessToken** to Authenticate with back-end ServiceStack Servers. 

Example usage of this feature is in the [Integrated Facebook, Twitter and Google Logins](https://github.com/ServiceStackApps/AndroidJavaChat/#integrated-facebook-twitter-and-google-logins)
in Android Java Chat which is also able to [Automatically Sign In users with saved AccessTokens](https://github.com/ServiceStackApps/AndroidJavaChat#automatically-sign-in-previously-signed-in-users).

This capability is available on the popular OAuth Providers below:

- `FacebookAuthProvider` - Sign in with Facebook
- `TwitterAuthProvider` - Sign in with Twitter
- `GithubAuthProvider` - Sign in with Github
- `GoogleOAuth2Provider` - Sign in with Google

It can also be enabled in other OAuth2 Providers by implementing `VerifyAccessToken` to manually 
validate whether the provided AccessToken is valid with the registered OAuth App. The API to validate Access 
Tokens isn't part of the OAuth2 specification and is different (and often missing) for other OAuth2 providers. 

As an example, the `GoogleOAuth2Provider` uses a `VerifyAccessToken` implementation that's similar to:

```csharp
new GoogleOAuth2Provider {
    VerifyAccessToken = accessToken => {
        var url = $"https://www.googleapis.com/oauth2/v1/tokeninfo?access_token={accessToken}";
        var json = url.GetJsonFromUrl();
        var obj = JsonObject.Parse(json);
        return obj["issued_to"] == ConsumerKey;
    }
}
```

#### Client Authentication with AccessToken

Clients can utilize this feature with the new `AccessToken` and `AccessTokenSecret` properties on the existing
`Authenticate` Request DTO, sent with the **provider** that the AccessToken is for, e.g:

```csharp
var response = client.Post(new Authenticate {
    provider = "facebook",
    AccessToken = facebookAccessToken,
    RememberMe = true,
});
```

::: info
Most OAuth Providers only require sending an `AccessToken` with Twitter being the exception which also requires sending an `AccessTokenSecret`
:::

### User Sessions Cache

ServiceStack uses the [Cache Provider](/caching) which was registered in the IoC container:

```csharp
//Register to use an In Memory Cache Provider (default)
container.Register<ICacheClient>(new MemoryCacheClient());

//Configure an alt. distributed persisted cache, E.g Redis:
//container.Register<IRedisClientsManager>(c => 
//    new RedisManagerPool("localhost:6379"));
```

::: info Tip
If you've got multiple servers which run the same ServiceStack service, you can use Redis to share the sessions between these servers
:::

Please look at [SocialBootstrapApi](https://github.com/ServiceStack/SocialBootstrapApi/tree/master/src/SocialBootstrapApi) to get a full example.

::: info 
Of course you can also implement your own - custom - authentication mechanism. You aren't forced to use the built-in ServiceStack auth mechanism
:::

## Declarative Validation Attributes

The recommended way to protect your APIs is to use the [Declarative Validation](/declarative-validation) attributes which as they're decoupled from any implementation can be safely annotated on Request DTOs without adding any implementation dependencies. In addition by annotating Authorization and Validation attributes on Request DTOs captures this information into your APIs reusable DTOs, filtering this information down to clients where they can provide enriched User Experiences.

### Authorization Attributes

The available Typed Authorization Attributes include:

| Attribute                      | Description                                                             |
|--------------------------------|-------------------------------------------------------------------------|
| `[ValidateIsAuthenticated]`    | Protect access to this API to Authenticated Users only                  |
| `[ValidateIsAdmin]`            | Protect access to this API to Admin Users only                          |
| `[ValidateHasPermission]`      | Protect access to this API to only Users assigned with ALL Permissions  |
| `[ValidateHasRole]`            | Protect access to this API to only Users assigned with ALL Roles        |

Where they can be annotated on **Request DTOs** to protect APIs:

```csharp
[ValidateIsAuthenticated]            // or [ValidateRequest("IsAuthenticated")]
[ValidateIsAdmin]                    // or [ValidateRequest("IsAdmin")]
[ValidateHasRole(role)]              // or [ValidateRequest($"HasRole(`{role}`)")]
[ValidateHasPermission(permission)]  // or [ValidateRequest($"HasPermission(`{permission}`)")
public class Secured {}
```

## The Authenticate attribute

The `[Authenticate]` [Request Filter Attribute](/filter-attributes) tells ServiceStack which Services needs authentication by adding it to your Service implementations, e.g:

```csharp
[Authenticate]
public class SecuredService : Service
{
    public object Get(Secured request)
    {
        IAuthSession session = this.GetSession();
        return new SecuredResponse() { Test = "You're" + session.FirstName };
    }

    public object Put(Secured request)
    {
        return new SecuredResponse() { Test = "Valid!" };
    }

    public object Post(Secured request)
    {
        return new SecuredResponse() { Test = "Valid!" };
    }

    public object Delete(Secured request)
    {
        return new SecuredResponse() { Test = "Valid!" };
    }
}
```

If you want, that authentication is only required for GET and PUT requests for example, you have to provide some extra parameters to the `Authenticate` attribute.

```csharp
[Authenticate(ApplyTo.Get | ApplyTo.Put)] 
```

## RequiredRole and RequiredPermission attributes

ServiceStack also includes a built-in role & permission based authorization attributes where you can apply the `[Required*]` Request Filter Attributes on your Service classes to apply to all Services or limited to a single Service:

```csharp
[Authenticate]
//All HTTP (GET, POST...) methods need "CanAccess"
[RequiredRole("Admin")]
[RequiredPermission("CanAccess")]
public class MyServices : Service
{
    public object Get(Secured request) {}

    [RequiredPermission("CanAdd")]
    public object Put(Secured request) {}
    
    [RequiredPermission("CanAdd")]
    public object Post(Secured request) {}
    
    [RequiredPermission("AdminRights", "CanDelete")]
    public object Delete(Secured request) {}
}
```

Now the client needs the permissions:

- **CanAccess** to make a GET request
- **CanAccess**, **CanAdd** to make a PUT/POST request
- **CanAccess**, **AdminRights** and **CanDelete** to make a DELETE request

If instead you want to allow access to users in **ANY** Role or Permission use: 

```csharp
[RequiresAnyRole("Admin","Member")]
[RequiresAnyRole(ApplyTo.Put | ApplyTo.Post, "Admin","Owner","Member")]
[RequiresAnyPermission(ApplyTo.Delete, "AdminRights", "CanDelete")]
public class MyServices : Service
{
    public object Get(Secured request) {}
    public object Put(Secured request) {}
    public object Post(Secured request) {}
    public object Delete(Secured request) {}
}
```

These attributes can also be applied to Request DTOs however as they would add a dependency to **ServiceStack.dll**, it's recommended to 

## Enabling Authentication at different levels

### Using the [Authenticate] Attribute

You can protect services by adding the `[Authenticate]` attribute on either the Action:

```csharp
class MyService : Service 
{
    [Authenticate] 
    public object Get(Protected request) { ... }
}
```

The Request DTO

```csharp
[Authenticate] 
class Protected { ... }
```

Or the service implementation

```csharp
[Authenticate] 
class MyService : Service 
{
    public object Get(Protected request) { ... }
}
```

Or by inheriting from a base class

```csharp
[Authenticate] 
class MyServiceBase : Service { ... }

class MyService : MyServiceBase {
    public object Get(Protected request) { ... }
}
```

### Using a Global Request Filter

Otherwise you can use a [global Request Filter](/request-and-response-filters) if you wanted to restrict all requests any other way, e.g something like:

```csharp
GlobalRequestFiltersAsync.Add(async (req, res, requestDto) =>
{
    if (ShouldProtectRequest(requestDto)) 
    {
        await new AuthenticateAttribute().ExecuteAsync(req, res, requestDto);
    }
});
```

## Customizing AuthProviders

#### CustomValidationFilter

The `CustomValidationFilter` on all AuthProviders lets you add post verification logic after a user has signed in with an OAuth provider and their OAuth metadata is retrieved. The filter lets you return a `IHttpResult` to control what error response is returned, e.g: 

```csharp
new FacebookAuthProvider(appSettings) { 
    CustomValidationFilter = authCtx => CustomIsValid(authCtx) 
        ? authCtx.Service.Redirect(authCtx.Session.ReferrerUrl
            .AddHashParam("f","CustomErrorCode"))
        : null,
}
```

Or could be used to redirect a network or users to a "Not Available in your Area" page with:

```csharp
Plugins.Add(new AuthFeature(..., 
    new IAuthProvider[] {
        new CredentialsAuthProvider {
            CustomValidationFilter = authCtx => 
                authCtx.Request.UserHostAddress.StartsWith("175.45.17")
                    ? HttpResult.Redirect("http://host.com/are-not-available")
                    : null
        }   
    }));
```

#### UserName Validation

The UserName validation for all Auth Repositories are configurable at:

```csharp
Plugins.Add(new AuthFeature(...){
    ValidUserNameRegEx = new Regex(@"^(?=.{3,20}$)([A-Za-z0-9][._-]?)*$", RegexOptions.Compiled),
})
```

Instead of RegEx you can choose to validate using a Custom Predicate. The example below ensures UserNames don't include specific chars:

```csharp
Plugins.Add(new AuthFeature(...){
    IsValidUsernameFn = userName => userName.IndexOfAny(new[] { '@', '.', ' ' }) == -1
})
```

#### AccountLocked Validator

Use `AccountLockedValidator` to override logic to determine when an account is locked, e.g. by default an Account is Locked when it has a `LockedDate` but
can be changed to allow locking accounts at a future date with:

```csharp
new CredentialsAuthProvider {
    AccountLockedValidator = (authRepo, userAuth, tokens) => 
        userAuth.LockedDate != null && userAuth.LockedDate <= DateTime.UtcNow;
}
```

Alternatively if you're using a Custom Auth Provider you can just override `IsAccountLocked()` to override this behavior.


#### Saving Extended OAuth Metadata

The new `SaveExtendedUserInfo` property (enabled by default) on all OAuth providers let you control whether to save the extended OAuth metadata available (into `UserAuthDetails.Items`) when logging in via OAuth.

#### MaxLoginAttempts

The `MaxLoginAttempts` feature lets you lock a User Account after multiple invalid login attempts, e.g:
 
```csharp
Plugins.Add(new AuthFeature(...) {
    MaxLoginAttempts = 5   // Lock user after 5 Invalid attempts
});
```

### Adding AuthProviders with Plugins

Plugins can register AuthProviders by calling `RegisterAuthProvider()` before the `AuthFeature` plugin is registered, which can be achieved in Plugins by having them implement `IPreInitPlugin`:

```csharp
public class MyPlugin : IPreInitPlugin
{
    public void BeforePluginsLoaded(IAppHost appHost)
    {
        appHost.GetPlugin<AuthFeature>().RegisterAuthProvider(new MyAuthProvider());
    }
}
```

### Auth Response Filter

Auth Providers can customize the `AuthenticateResponse` returned by implementing `IAuthResponseFilter` where 
it will get called back with a populated [AuthFilterContext](https://github.com/ServiceStack/ServiceStack/blob/master/src/ServiceStack/Auth/IAuthProvider.cs) for successful Authenticate Request DTO requests or `AuthResultContext` for successful OAuth requests:

```csharp
public interface IAuthResponseFilter
{
    // Intercept successful Authenticate Request DTO requests
    void Execute(AuthFilterContext authContext);
    
    // Intercept successful OAuth redirect requests
    Task ResultFilterAsync(AuthResultContext authContext, CancellationToken token=default);
}

public class AuthFilterContext
{
    public AuthenticateService AuthService    // Instance of AuthenticateService
    public IAuthProvider AuthProvider         // Selected Auth Provider for Request
    public IAuthSession Session               // Authenticated Users Session
    public Authenticate AuthRequest           // Auth Request DTO
    public AuthenticateResponse AuthResponse  // Auth Response DTO
    public string ReferrerUrl                 // Optimal Session Referrer URL to use redirects
    public bool AlreadyAuthenticated          // If User was already authenticated
    public bool DidAuthenticate               // If User Authenticated in this request
}

public class AuthResultContext
{
    public IHttpResult Result                 // Response returned for this successful Auth Request
    public IServiceBase Service               // Instance of Service used in this Request
    public IRequest Request                   // Current HTTP Request Context
    public IAuthSession Session               // Authenticated Users Session
}
```

The filters can be used to modify properties on the `AuthenticateResponse` DTO or OAuth successful redirect requests.
To completely replace the `AuthenticateResponse` returned, you can specify a `AuthFeature.AuthResponseDecorator`.

### ICustomUserAuth

The `ICustomUserAuth` interface can be implemented on User Auth Repositories that allow replacing the custom 
`UserAuth` and `UserAuthDetails` tables by returning the concrete Type that should be used instead:

```csharp
public interface ICustomUserAuth
{
    IUserAuth CreateUserAuth();
    IUserAuthDetails CreateUserAuthDetails();
}
```

This allows using the same `RegistrationFeature` and `RegisterService` to handle registering new users
with the substituted `IUserAuth` and `IUserAuthDetails` Types.

#### LoadUserAuthFilter

The LoadUserAuthFilter on `AspNetWindowsAuthProvider` lets you retrieve more detailed information about Windows Authenticated users during Windows Auth Authentication by using the .NET's ActiveDirectory services, e.g:

```csharp
//...
new AspNetWindowsAuthProvider(this) {
    LoadUserAuthFilter = LoadUserAuthInfo
}
//...

public void LoadUserAuthInfo(AuthUserSession userSession, 
    IAuthTokens tokens, Dictionary<string, string> authInfo)
{
    if (userSession == null) return;
    using (PrincipalContext pc = new PrincipalContext(ContextType.Domain))
    {
        var user = UserPrincipal.FindByIdentity(pc, userSession.UserAuthName);
        tokens.DisplayName = user.DisplayName;
        tokens.Email = user.EmailAddress;
        tokens.FirstName = user.GivenName;
        tokens.LastName = user.Surname;
        tokens.FullName = (String.IsNullOrWhiteSpace(user.MiddleName))
            ? $"{user.GivenName} {user.Surname}"
            : $"{user.GivenName} {user.MiddleName} {user.Surname}";
        tokens.PhoneNumber = user.VoiceTelephoneNumber;
    }
}
```

### Customizable PopulateUserRoles on AspNetWindowsAuthProvider

The `AspNetWindowsAuthProvider` uses the public `IPrincipal.IsInRole()` API to determine if a User is in a particular Windows Auth role, however this can be slow when needing to query a large number of roles in LDAP as it would need to make an LDAP lookup for each role. 

Performance of this can now be improved by specifying a custom `PopulateUserRoles` implementation that overrides how User Roles are resolved, e.g:

```csharp
new AspNetWindowsAuthProvider (AppSettings) {
    PopulateUserRoles = (request, user, session) => {
        using (WindowsIdentity userId = request?.LogonUserIdentity)
        {
            List roles = new List();
            if (userId?.Groups != null)
            {
                foreach (var group in userId.Groups)
                {
                    // Remove the domain name from the name of the group, 
                    // if it has it, and you don't need it. 
                    var groupName = new SecurityIdentifier(group.Value)
                        .Translate(typeof(NTAccount)).ToString();
                    if (groupName.Contains("\")) 
                    groupName = groupName.Split('\')[1]; 
                    roles.Add(groupName);
                }
            }
            session.Roles = roles;
        }
    }
}
```

### In Process Authenticated Requests

You can enable the `CredentialsAuthProvider` to allow **In Process** requests to Authenticate without a Password with:

```csharp
new CredentialsAuthProvider {
    SkipPasswordVerificationForInProcessRequests = true,
}
```

When enabled this lets **In Process** Service Requests to login as a specified user without needing to provide their password. 

For example this could be used to create an [Intranet Restricted](/auth/restricting-services) **Admin-Only** Service that lets you login as another user so you can debug their account without knowing their password with:

```csharp
[RequiredRole("Admin")]
[Restrict(InternalOnly=true)]
public class ImpersonateUser 
{
    public string UserName { get; set; }
}

public class MyAdminServices : Service
{
    public async Task<object> Any(ImpersonateUser request)
    {
        using var service = base.ResolveService<AuthenticateService>(); //In Process
        return await service.PostAsync(new Authenticate {
            provider = AuthenticateService.CredentialsProvider,
            UserName = request.UserName,
        });
    }
}
```

::: info
Your Services can use the new `Request.IsInProcessRequest()` to identify Services that were executed in-process
:::

### Custom User Sessions using JWT Tokens

The [JWT Auth Provider](/auth/jwt-authprovider) allows for a more flexible approach to impersonating users as they allow
[Manually creating JWT Tokens](/auth/jwt-authprovider#creating-jwt-tokens-manually) to construct a custom User Session with Custom metadata, 
Roles and Permissions.

### IAuthMetadataProvider

An IAuthMetadataProvider provides a way to customize the authInfo in all AuthProviders. It also allows overriding of how extended Auth metadata like profileUrl is returned.

```csharp
public interface IAuthMetadataProvider
{
   void AddMetadata(IAuthTokens tokens, Dictionary<string,string> authInfo);

   string GetProfileUrl(IAuthSession authSession, string defaultUrl = null);
}
```

::: info
To override with a custom implementation, register `IAuthMetadataProvider` in the IOC
:::

### Generate New Session Cookies on Authentication 

The AuthFeature also regenerates new Session Cookies each time users login, this behavior can be disabled with:

```csharp
Plugins.Add(new AuthFeature(...) {
    GenerateNewSessionCookiesOnAuthentication = false
});
```

### ClientId and ClientSecret OAuth Config Aliases
 
OAuth Providers can use `ClientId` and `ClientSecret` aliases instead of `ConsumerKey` and `ConsumerSecret`, e.g:

```xml 
<appSettings>
    <add key="oauth.twitter.ClientId" value="..." />
    <add key="oauth.twitter.ClientSecret" value="..." />
</appSettings>
```

### Override Authorization HTTP Header

Request Filters can override the Authorization HTTP Header used in Auth Providers with:

```csharp
httpReq.Items[Keywords.Authorization] = $"Bearer {token}";
```

### GET Authenticate Requests are disabled by default

**GET** `/auth/{provider}` requests are disabled by default to discourage sending confidential information in the URL.

The current exceptions which still allow **GET** requests include:

 - `/auth` - Used to check if a User is Authenticated
 - `/auth/logout` - Logging Out
 - All OAuth Providers who starts their OAuth flow by navigating to `/auth/{provider}`

You can allow **GET** Authentication requests with:

```csharp
new AuthFeature {
    AllowGetAuthenticateRequests = req => true
}
```

Although it's recommended to change your code to use `POST` instead of `GET` requests. 
Otherwise you can use the `IRequest req` parameter to check against a white list of known requests types.


<a name="community"></a>

# Community Resources

  - [Simple Web Service Authentication with ServiceStack](https://steveellwoodnlc.medium.com/simple-web-service-authentication-with-servicestack-7294fe5493a2) by [@steveellwood](https://steveellwoodnlc.medium.com)
  - [Using IdentityServer 4 with ServiceStack and Angular](http://estynedwards.com/blog/2016/01/30/ServiceStack-IdentityServer-Angular/) by [@estynedwards](https://twitter.com/estynedwards)
  - [Adding Facebook Authentication using ServiceStack](http://buildclassifieds.com/2016/01/14/facebookauth/) by [@markholdt](https://twitter.com/markholdt)
  - [How to return JSV formatted collection types from SQL Server in OrmLite](http://blog.falafel.com/Blogs/adam-anderson/2013/10/28/how-to-return-jsv-formatted-collection-types-from-sql-server-to-servicestack.ormlite) by [AdamAnderson](http://blog.falafel.com/blogs/AdamAnderson)
  - [How to migrate ASP.NET Membership users to ServiceStack](http://blog.falafel.com/Blogs/adam-anderson/2013/10/23/how-to-migrate-asp.net-membership-users-to-servicestack) by [AdamAnderson](http://blog.falafel.com/blogs/AdamAnderson)
  - [Authentication in ServiceStack REST Services](http://www.binaryforge-software.com/wpblog/?p=242) by [@binaryforge](https://twitter.com/binaryforge)
  - [Building a ServiceStack OAuth2 resource server using DotNetOpenAuth](http://dylanbeattie.blogspot.com/2013/08/building-servicestack-based-oauth2.html) by [@dylanbeattie](https://twitter.com/dylanbeattie)
  - [Declarative authorization in REST services in SharePoint with F#](http://sergeytihon.wordpress.com/2013/06/28/declarative-authorization-in-rest-services-in-sharepoint-with-f-and-servicestack/) by [@sergey_tihon](https://twitter.com/sergey_tihon)
  - [Authenticate ServiceStack services against an Umbraco membership provider](http://stackoverflow.com/a/16845317/85785) by [Gavin Faux](http://stackoverflow.com/users/1664508/gavin-faux)
  - [Using OAuth with ArcGIS Online and ServiceStack](http://davetimmins.com/post/2013/april/oauth-with-arcgisonline-servicestack) by [@davetimmins](https://twitter.com/davetimmins)
  - [LinkedIn Provider for ServiceStack Authentication](http://www.binoot.com/2013/03/30/linkedin-provider-for-servicestack-authentication/) by [@binu_thayamkery](https://twitter.com/binu_thayamkery)
  - [A Step by Step guide to create a Custom IAuthProvider](http://enehana.nohea.com/general/customizing-iauthprovider-for-servicestack-net-step-by-step/) by [@rngoodness](https://twitter.com/rngoodness)
  - [Simple API Key Authentication With ServiceStack](http://rossipedia.com/blog/2013/03/simple-api-key-authentication-with-servicestack/) by [@rossipedia](https://twitter.com/rossipedia)
  - [CORS BasicAuth on ServiceStack with custom authentication](http://joeriks.com/2013/01/12/cors-basicauth-on-servicestack-with-custom-authentication/) by [@joeriks](https://twitter.com/joeriks)
  - [Authenticating ServiceStack REST API using HMAC](https://www.jokecamp.com/blog/authenticating-servicestack-rest-api-using-hmac/) by [@jokecamp](https://twitter.com/jokecamp)
  - ServiceStack Credentials Authentication and EasyHttp: [Part 1](http://blogs.lessthandot.com/index.php/DesktopDev/MSTech/servicestack-credentialsauthentication-and-easyhtpp-of), [Part 2](http://blogs.lessthandot.com/index.php/DesktopDev/MSTech/servicestack-credentialsauthentication-and-easyhtpp-of-1), [Part 3](http://blogs.lessthandot.com/index.php/DesktopDev/MSTech/servicestack-credentialsauthentication-and-easyhtpp-of-2) by [@chrissie1](https://twitter.com/chrissie1)


# Auth Repository
Source: https://docs.servicestack.net/auth/auth-repository

ServiceStack Auth supports using your own persistence back-ends but for the most part you should be able to reuse one of the existing [IAuthRepository](https://github.com/ServiceStack/ServiceStack/blob/master/src/ServiceStack/Auth/IAuthRepository.cs): 

  - **OrmLite**: `OrmLiteAuthRepository` in [ServiceStack.Server](https://nuget.org/packages/ServiceStack.Server)
    - [OrmLiteAuthRepositoryMultitenancy](/multitenancy#multitenancy-rdbms-authprovider)
  - **Redis**: `RedisAuthRepository` in [ServiceStack](https://nuget.org/packages/ServiceStack)
  - **Memory**: `InMemoryAuthRepository` in [ServiceStack](https://nuget.org/packages/ServiceStack)
  - **AWS DynamoDB**: `DynamoDbAuthRepository` in [ServiceStack.Aws](https://nuget.org/packages/ServiceStack.Aws)
  - **Mongo DB**: `MongoDBAuthRepository` in [ServiceStack.Authentication.MongoDB](https://nuget.org/packages/ServiceStack.Authentication.MongoDB)
  - **Raven DB**: `RavenUserAuthRepository` in [ServiceStack.Authentication.RavenDB](https://nuget.org/packages/ServiceStack.Authentication.RavenDB)
  - **Marten**: `MartenAuthRepository` in [ServiceStack.Authentication.Marten](https://www.nuget.org/packages/ServiceStack.Authentication.Marten) - [GitHub project](https://github.com/migajek/ServiceStack.Authentication.Marten)
  - **LiteDB**: `LiteDBAuthRepository` in [ServiceStack.Authentication.LiteDB](https://github.com/CaveBirdLabs/ServiceStack.Authentication.LiteDB)

#### Registering an Auth Repository

The `OrmLiteAuthRepository` is the most common Auth Repository which will let you persist User Info in any of the [RDBMS's that OrmLite supports](/ormlite/#ormlite-rdbms-providers). All Auth Repositories are registered by adding a `IAuthRepository` dependency in your IOC, e.g:

```csharp
container.Register<IDbConnectionFactory>(c =>
    new OrmLiteConnectionFactory(connectionString, SqlServer2012Dialect.Provider));

container.Register<IAuthRepository>(c =>
    new OrmLiteAuthRepository(c.Resolve<IDbConnectionFactory>()));

container.Resolve<IAuthRepository>().InitSchema();
```

Calling `InitSchema()` will create the necessary RDBMS `UserAuth` and `UserAuthDetails` tables if they don't already exist. By default the Users Roles and Permissions are blobbed on the `UserAuth` table, but if preferred they can optionally be maintained in a separate `UserAuthRole` table with:

```csharp
container.Register<IAuthRepository>(c =>
    new OrmLiteAuthRepository(c.Resolve<IDbConnectionFactory>()) {
        UseDistinctRoleTables = true
    });
```

Like the [caching providers](/caching) the `async` Auth Repositories makes use of this existing `IAuthRepository` registration which you can use in your Services to access either `IAuthRepositoryAsync` or `IAuthRepository` APIs above even for your own sync Auth Repos that only implement `IAuthRepository` as it will return a `IAuthRepositoryAsync` wrapper API in its place.

### Auth Repository Admin APIs 

If you're interested in implementing a User Management feature in your own Apps you may want to re-use the Admin APIs in the [User Admin Feature](/admin-ui-users) which enable Service access to many User Auth Repository features.

### Mix in Auth Repository

The easiest way to configure a User Auth Repository in your [Modular Startup](/modular-startup) App that new ASP.NET Core templates support
is to [mix them in](/mix-tool#composable-features), e.g. you can configure to use an OrmLiteAuthRepository using SQL Server with:

:::sh
x mix auth-db sqlserver
:::

You can view other Auth Repository "mix ins" available with:

:::sh
x mix [auth]
:::

Which displays the current list of available Auth Repositories:

```
Results matching tag [auth]:

   1. auth              Configure AuthFeature                        to: $HOST  by @ServiceStack [auth]
   2. auth-db           Use OrmLite Auth Repository (requires auth)  to: $HOST  by @ServiceStack [auth]
   3. auth-redis        Use Redis Auth Repository (requires auth)    to: $HOST  by @ServiceStack [auth]
   4. auth-memory       Use Memory Auth Repository (requires auth)   to: $HOST  by @ServiceStack [auth]
   5. auth-dynamodb     Use DynamoDB Auth Repository (requires auth) to: $HOST  by @ServiceStack [auth]
   6. auth-mongodb      Use MongoDB Auth Repository (requires auth)  to: $HOST  by @ServiceStack [auth]
   7. auth-ravendb      Use RavenDB Auth Repository (requires auth)  to: $HOST  by @ServiceStack [auth]
   8. auth-marten       Use Marten Auth Repository (requires auth)   to: $HOST  by @ServiceStack [auth]
   9. feature-authrepo  List and Search Users in an Auth Repo        to: $HOST  by @ServiceStack [feature,auth]
```

and search the available RDBMS's and NoSQL Data Stores:

:::sh
x mix [db]
:::

That can be easily configured by a mix in:

```
Results matching tag [db]:

   1. redis      Use ServiceStack.Redis            to: $HOST  by @ServiceStack  [db]
   2. sqlserver  Use OrmLite with SQL Server       to: $HOST  by @ServiceStack  [db]
   3. sqlite     Use OrmLite with SQLite           to: $HOST  by @ServiceStack  [db]
   4. postgres   Use OrmLite with PostgreSQL       to: $HOST  by @ServiceStack  [db]
   5. mysql      Use OrmLite with MySql            to: $HOST  by @ServiceStack  [db]
   6. oracle     Use OrmLite with Oracle           to: $HOST  by @ServiceStack  [db]
   7. firebird   Use OrmLite with Firebird         to: $HOST  by @ServiceStack  [db]
   8. dynamodb   Use AWS DynamoDB and PocoDynamo   to: $HOST  by @ServiceStack  [db]
   9. mongodb    Use MongoDB                       to: $HOST  by @ServiceStack  [db]
  10. ravendb    Use RavenDB                       to: $HOST  by @ServiceStack  [db]
  11. marten     Use Marten NoSQL with PostgreSQL  to: $HOST  by @ServiceStack  [db]
```    

### Sync & Async Auth Repositories

All built-in ServiceStack Auth Repositories implement both `IUserAuthRepository` and `IUserAuthRepositoryAsync` which you can use inside ServiceStack Services with the `AuthRepositoryAsync` property, e.g:

```csharp
//async
public async Task<object> Post(GetUserAuth request)
{
    var userAuth = await AuthRepositoryAsync.GetUserAuthByUserNameAsync(request.UserName);
    if (userAuth == null)
        throw HttpError.NotFound(request.UserName);
    return userAuth;
}

//sync
public object Post(GetUserAuth request)
{
    var userAuth = AuthRepository.GetUserAuthByUserName(request.UserName);
    if (userAuth == null)
        throw HttpError.NotFound(request.UserName);
    return userAuth;
}
```

Outside of ServiceStack you can access it from the AppHost `GetAuthRepositoryAsync()` or `GetAuthRepository()` APIs, e.g:

```csharp
//async
var authRepo = HostContext.AppHost.GetAuthRepositoryAsync();
await using (authRepo as IAsyncDisposable)
{
    //...
}

//sync
var authRepo = HostContext.AppHost.GetAuthRepository();
using (authRepo as IDisposable)
{
    //...
}
```


## Extending UserAuth tables

There are a number of different extensibility options for extending ServiceStack Authentication by linking to external tables with its `RefId` and `RefIdStr` fields or storing custom info in the `Meta` Dictionaries. 

Most Auth Repositories like OrmLite also supports utilizing custom `UserAuth` tables with extended fields which can be configured using its generic Constructor, e.g:

```csharp
public class MyUserAuth : UserAuth { .... }
public class MyUserAuthDetails : UserAuthDetails { .... }
```

```csharp
container.Register<IAuthRepository>(c =>
    new OrmLiteAuthRepository<MyUserAuth, MyUserAuthDetails>(c.Resolve<IDbConnectionFactory>()) {
        UseDistinctRoleTables = true
    });
```

The [Auth Repository mix gists](/mix-tool#mix-in-auth-repository) are configured with an example using a custom `AppUser` table which are populated using the [Session and Auth Events](/auth/sessions#session-events) hooks, e.g:

```csharp
// Custom User Table with extended Metadata properties
public class AppUser : UserAuth
{
    public string ProfileUrl { get; set; }
    public string LastLoginIp { get; set; }
    public DateTime? LastLoginDate { get; set; }
}

public class AppUserAuthEvents : AuthEvents
{
    public override void OnAuthenticated(IRequest req, IAuthSession session, IServiceBase authService, 
        IAuthTokens tokens, Dictionary<string, string> authInfo)
    {
        var authRepo = HostContext.AppHost.GetAuthRepository(req);
        using (authRepo as IDisposable)
        {
            var userAuth = (AppUser)authRepo.GetUserAuth(session.UserAuthId);
            userAuth.ProfileUrl = session.GetProfileUrl();
            userAuth.LastLoginIp = req.UserHostAddress;
            userAuth.LastLoginDate = DateTime.UtcNow;
            authRepo.SaveUserAuth(userAuth);
        }
    }
}
```

#### Custom UserAuth Tables

If you want to add support for custom `UserAuth` and `UserAuthDetails` tables in your own custom Auth Repositories you'll need to implement the 
`ICustomUserAuth` interface by returning the concrete Type that should be used instead:

```csharp
public interface ICustomUserAuth
{
    IUserAuth CreateUserAuth();
    IUserAuthDetails CreateUserAuthDetails();
}
```

If implementing a generic class like `OrmLiteAuthRepository<TUserAuth,TUserAuthDetails>` you can return new instances of the Generic Type Arguments with:

```csharp
IUserAuth CreateUserAuth() => (IUserAuth)typeof(TUserAuth).CreateInstance();

IUserAuthDetails CreateUserAuthDetails() => (IUserAuthDetails)typeof(TUserAuthDetails).CreateInstance();
```

### Adding additional metadata to the Meta dictionary fields

For minor extensions you can use the **Meta** string dictionaries fields on the UserAuth tables to maintain custom metadata. 
They include useful `Get<T>` and `Set<T>` methods which can be used to blob additional complex types with each User, e.g:

```csharp
userAuth.Set(new Address { ... });
var address = userAuth.Get<Address>();
```

### Linking referential data with RefId and RefIdStr fields

The `UserAuth` and `UserAuthDetails` tables also include an `int? RefId` and a `string RefIdStr` fields which you can use to reference external data like your own custom tables against each User Auth record or User OAuth registration.

### Extend UserAuthSession with your own typed Custom Session

In addition to a Custom UserAuth tables you can also use a custom `AuthUserSession` for maintaining typed Users Sessions which get blobbed in a fast [Caching Provider](/caching) where its schema-less persistance characteristics, easily supports fast access to extended types.

```csharp
public class CustomUserSession : AuthUserSession { ... }

appHost.Plugins.Add(new AuthFeature(
    () => new CustomUserSession(), ...);
```

### IAuthRepository APIs

Inside your Services you can access the **async** `base.AuthRepositoryAsync` and **sync** `IAuthRepository` APIs with:

```csharp
await base.AuthRepositoryAsync.CreateUserAuthAsync(...);
```

You can use the Async APIs with every Auth Repository as an async wrapper is returned for Auth Repositories which only support the Sync APIs.

If you need to access the Auth Repository from inside a sync method you can access the **sync** APIs from `base.AuthRepository`, e.g:

```csharp
base.AuthRepository.CreateUserAuth(...);
```

All ServiceStack's built-in Auth Repositories support the extended `IUserAuthRepository` APIs which your Services can use to manage your App's registered users:

```csharp
public interface IUserAuthRepository : IAuthRepository
{
    IUserAuth CreateUserAuth(IUserAuth newUser, string password);
    IUserAuth UpdateUserAuth(IUserAuth existingUser, IUserAuth newUser);
    IUserAuth UpdateUserAuth(IUserAuth existingUser, IUserAuth newUser, string password);
    IUserAuth GetUserAuth(string userAuthId);
    void DeleteUserAuth(string userAuthId);
}

public interface IUserAuthRepositoryAsync : IAuthRepositoryAsync
{
    Task<IUserAuth> CreateUserAuthAsync(IUserAuth newUser, string password, CancellationToken token);
    Task<IUserAuth> UpdateUserAuthAsync(IUserAuth existingUser, IUserAuth newUser, CancellationToken token);
    Task<IUserAuth> UpdateUserAuthAsync(IUserAuth existingUser, IUserAuth newUser, string password);
    Task<IUserAuth> GetUserAuthAsync(string userAuthId, CancellationToken token);
    Task DeleteUserAuthAsync(string userAuthId, CancellationToken token);
}

public interface IAuthRepository
{
    void LoadUserAuth(IAuthSession session, IAuthTokens tokens);
    void SaveUserAuth(IAuthSession authSession);
    List<IUserAuthDetails> GetUserAuthDetails(string userAuthId);
    IUserAuthDetails CreateOrMergeAuthSession(IAuthSession authSession, IAuthTokens tokens);

    IUserAuth GetUserAuth(IAuthSession authSession, IAuthTokens tokens);
    IUserAuth GetUserAuthByUserName(string userNameOrEmail);
    void SaveUserAuth(IUserAuth userAuth);
    bool TryAuthenticate(string userName, string password, out IUserAuth userAuth);
    bool TryAuthenticate(Dictionary<string, string> digestHeaders, 
        string privateKey, int nonceTimeOut, string sequence, out IUserAuth userAuth);
}

public interface IAuthRepositoryAsync
{
    Task LoadUserAuthAsync(IAuthSession session, IAuthTokens tokens, CancellationToken token);
    Task SaveUserAuthAsync(IAuthSession authSession, CancellationToken token);
    Task<List<IUserAuthDetails>> GetUserAuthDetailsAsync(string userAuthId, CancellationToken token);
    Task<IUserAuthDetails> CreateOrMergeAuthSessionAsync(IAuthSession authSession, IAuthTokens tokens);

    Task<IUserAuth> GetUserAuthAsync(IAuthSession authSession, IAuthTokens tokens, CancellationToken token);
    Task<IUserAuth> GetUserAuthByUserNameAsync(string userNameOrEmail, CancellationToken token);
    Task SaveUserAuthAsync(IUserAuth userAuth, CancellationToken token);
    Task<IUserAuth> TryAuthenticateAsync(string userName, string password, CancellationToken token);
    Task<IUserAuth> TryAuthenticateAsync(Dictionary<string, string> digestHeaders, 
        string privateKey, int nonceTimeOut, string sequence, CancellationToken token);
}
```

### Updating UserAuth tables directly

If you need finer-grained access than the shared APIs above, you can update the `UserAuth` and `UserAuthDetails` POCOs 
in your preferred persistence provider directly.

E.g. if you're using the `OrmLiteAuthRepository` to store your Users in an RDBMS back-end you can use 
[OrmLite APIs](https://github.com/ServiceStack/ServiceStack.OrmLite) to update the user details stored in the `UserAuth` and `UserAuthDetails`
tables, e.g:

```csharp
Db.UpdateOnly(() => new UserAuth { DisplayName = newName }, where: q => q.Id == userId);
```

Which will only update the `DisplayName` column for the specified user.

If you're using a [Custom UserAuth Table](/auth/auth-repository#extending-userauth-tables) (e.g. `AppUser`) instead of the default `UserAuth` you would need to update that POCO data model instead.


### IManageRoles API

The [IManageRoles API](https://github.com/ServiceStack/ServiceStack/blob/master/src/ServiceStack/Auth/IAuthRepository.cs#L72) 
can be implemented by any `IAuthRepository` to provide an alternative strategy for querying and managing Users Roles and permissions. 

This API is being used in the `OrmLiteAuthRepository` to provide an alternative way to store Roles and Permission in their own distinct table rather than being blobbed with the rest of the User Auth data. 

This behavior can be enabled in `OrmLiteAuthRepository` by specifying `UseDistinctRoleTables=true` at registration, e.g:

```csharp
container.Register<IAuthRepository>(c =>
    new OrmLiteAuthRepository(c.Resolve<IDbConnectionFactory>()) {
        UseDistinctRoleTables = true,
    });
```

When enabled, roles and permissions are persisted in the distinct **UserAuthRole** table instead of being blobbed on the UserAuth. The `IAuthSession.HasRole()` and `IAuthSession.HasPermission()` on the Users Session should be used to check if a User has a specified Role or Permission.

If you're persisting roles in a different table you'll need to use the `IManageRoles` APIs to access & manage a users role, e.g:

```csharp
var manageRoles = (IManageRolesAsync)base.AuthRepositoryAsync;  // async
var manageRoles = (IManageRoles)base.AuthRepository;            // sync
```

These APIs can be used with `OrmLiteAuthRepository` whether Roles are persisted in external tables or not.

```csharp
public interface IManageRoles
{
    ICollection<string> GetRoles(string userAuthId);
    ICollection<string> GetPermissions(string userAuthId);
    void GetRolesAndPermissions(string userAuthId, out ICollection<string> roles, 
        out ICollection<string> permissions);

    bool HasRole(string userAuthId, string role);
    bool HasPermission(string userAuthId, string permission);

    void AssignRoles(string userAuthId,
        ICollection<string> roles = null, ICollection<string> permissions = null);

    void UnAssignRoles(string userAuthId,
        ICollection<string> roles = null, ICollection<string> permissions = null);
}

public interface IManageRolesAsync
{
    Task<ICollection<string>> GetRolesAsync(string userAuthId, CancellationToken token);
    Task<ICollection<string>> GetPermissionsAsync(string userAuthId, CancellationToken token);
    Task<Tuple<ICollection<string>,ICollection<string>>> GetRolesAndPermissionsAsync(
        string userAuthId, CancellationToken token);

    Task<bool> HasRoleAsync(string userAuthId, string role, CancellationToken token);
    Task<bool> HasPermissionAsync(string userAuthId, string permission, CancellationToken token);

    Task AssignRolesAsync(string userAuthId,
        ICollection<string> roles = null, ICollection<string> permissions = null, CancellationToken token);

    Task UnAssignRolesAsync(string userAuthId,
        ICollection<string> roles = null, ICollection<string> permissions = null, CancellationToken token);
}
```

More examples of this are in [ManageRolesTests.cs](https://github.com/ServiceStack/ServiceStack/blob/master/tests/ServiceStack.Common.Tests/ManageRolesTests.cs).

### Assigning Roles and Permissions

Super Users with the **Admin** role or Requests with an [AdminAuthSecret](/debugging#authsecret) can call the built-in `/assignroles` and `/unassignroles` Services to add Roles/Permissions to existing users from an external Request, e.g:

```csharp
var client = new JsonApiClient(baseUrl);
var response = client.Post(new AssignRoles
{
    UserName = userName,
    Roles = new List<string> { "TheRole" },
    Permissions = new List<string> { "ThePermission" }
});
```

Inside ServiceStack you can use the `AssignRoles` API to add Roles and Permissions to an existing User:

```csharp
var userAuth = await AuthRepositoryAsync.GetUserAuthByUserNameAsync(userName);
if (userAuth == null)
    throw HttpError.NotFound(userName);

await AuthRepositoryAsync.AssignRolesAsync(userAuth, new[]{ "TheRole" }, new[]{ "ThePermission" });
```

Alternatively you can add Roles when creating a new User with:

```csharp
await AssignRolesAsync.CreateUserAuthAsync(new UserAuth
{
    UserName = userName,
    FirstName = "John",
    LastName = "Doe",
    DisplayName = "John Doe",
    Roles = new List<string> { "TheRole" }
}, userPassword);
```

### Customizing User Roles and Permissions

The default implementation of User Roles and Permissions on [AuthUserSession](https://github.com/ServiceStack/ServiceStack/blob/master/src/ServiceStack/AuthUserSession.cs) shows how ServiceStack's `[RequiredRole]` and `[RequiredPermission]` [Roles and Permission attributes](/auth/authentication-and-authorization#the-requiredrole-and-requiredpermission-attributes) are validated:
 
```csharp
public virtual bool HasPermission(string permission)
{
    var managesRoles = HostContext.TryResolve<IAuthRepository>() as IManageRoles;
    if (managesRoles != null)
    {
        return managesRoles.HasPermission(this.UserAuthId, permission);
    }

    return this.Permissions != null && this.Permissions.Contains(permission);
}

public virtual bool HasRole(string role)
{
    var managesRoles = HostContext.TryResolve<IAuthRepository>() as IManageRoles;
    if (managesRoles != null)
    {
        return managesRoles.HasRole(this.UserAuthId, role);
    }

    return this.Roles != null && this.Roles.Contains(role);
}
```

These APIs are `virtual` so they can be overridden in both your Custom `AuthUserSession`. They default to looking at the `Roles` and `Permissions` collections stored on the Session. These collections are normally sourced from the `AuthUserRepository` when persisting the [UserAuth and UserAuthDetails POCO's](https://github.com/ServiceStack/ServiceStack/blob/master/src/ServiceStack/Auth/UserAuth.cs) and are used to populate the `UserAuthSession` on successful Authentication. These collections can be further customized by AuthProviders which is what `AspNetWindowsAuthProvider` does to add [Authenticated WindowsAuth Roles](https://github.com/ServiceStack/ServiceStack/blob/9773b7fccc31ac4d715a02221f396b46cd14d7db/src/ServiceStack/Auth/AspNetWindowsAuthProvider.cs#L126).

As seen above Roles/Permissions can instead be managed by AuthProviders that implement `IManageRoles` API which is what OrmLiteAuthProvider uses to look at distinct RDBMS tables to validate Roles/Permissions.

### Microsoft Graph Roles

[OAuth Providers](/auth#auth-providers) like Microsoft Graph have their own global roles for users managed separately. In order to combine both Microsoft Graph's Azure AD Roles with App-defined roles when using the `OrmLiteAuthRepository` it needs to be configured to persist roles in distinct role tables (required to capture the source of each role):

```csharp
services.AddSingleton<IAuthRepository>(c =>
    new OrmLiteAuthRepository<AppUser, UserAuthDetails>(c.Resolve<IDbConnectionFactory>()) {
        UseDistinctRoleTables = true
    });
```

Once configured you'll be able to manage your App's local User roles via ServiceStack's [Auth Repository](/auth/auth-repository), [Assign Roles APIs](/auth/auth-repository#assigning-roles-and-permissions) or built-in [Admin Users UI](/admin-ui-users) without interfering with Azure AD managed roles:

<div class="block flex justify-center items-center">
    <a href="/admin-ui-users"><img class="max-w-screen-md" src="/img/pages/admin-ui/users-edit-default.png"></a>
</div>


### PBKDF2 Password Hashing implementation

ServiceStack uses the same [PBKDF2](https://en.wikipedia.org/wiki/PBKDF2) password hashing algorithm ASP.NET Identity v3 by default for both new users and successful authentication logins where their password will automatically be re-hashed with the new implementation.

This also means if you wanted to switch, you'll be able to import ASP.NET Identity v3 User Accounts and their Password Hashes into ServiceStack.Auth's `UserAuth` tables and vice-versa.

#### Retain previous Password Hashing implementation

If preferred you can revert to using the existing `SaltedHash` implementation with:

```csharp
SetConfig(new HostConfig { 
    UseSaltedHash = true
});
```

This also supports "downgrading" passwords that were hashed with the new `IPasswordHasher` provider where it will revert to using the older/weaker `SaltedHash` implementation on successful authentication.

#### Override Password Hashing Strength

The new [PasswordHasher](https://github.com/ServiceStack/ServiceStack/blob/master/src/ServiceStack/Auth/PasswordHasher.cs) implementation can also be made to be computationally stronger or weaker by adjusting the iteration count (default 10000), e.g:

```csharp
container.Register<IPasswordHasher>(new PasswordHasher(1000));
```

#### Versionable Password Hashing

The new [IPasswordHasher](https://github.com/ServiceStack/ServiceStack/blob/master/src/ServiceStack.Interfaces/Auth/IPasswordHasher.cs) interface includes support for versioning future Password Hashing algorithms and rehashing:

```csharp
public interface IPasswordHasher
{
    // First byte marker used to specify the format used. The default implementation uses format:
    // { 0x01, prf (UInt32), iter count (UInt32), salt length (UInt32), salt, subkey }
    byte Version { get; }

    // Returns a boolean indicating whether the providedPassword matches the hashedPassword
    // The needsRehash out parameter indicates whether the password should be re-hashed.
    bool VerifyPassword(string hashedPassword, string providedPassword, out bool needsRehash);

    // Returns a hashed representation of the supplied password
    string HashPassword(string password);
}
```

Which is implemented in all ServiceStack Auth Repositories where it will rehash passwords that used a different version or weaker strength, by utilizing the new API for verifying passwords:

```csharp
if (userAuth.VerifyPassword(password, out var needsRehash))
{
    this.RecordSuccessfulLogin(userAuth, needsRehash, password);
    return true;
}
```

If you're using a Custom Auth Repository it will need to use the new password verification APIs, please refer to [OrmLiteAuthRepository](https://github.com/ServiceStack/ServiceStack/blob/bed1d900de93f889cca05299df4c33a04b7ad7a7/src/ServiceStack.Server/Auth/OrmLiteAuthRepository.cs#L325-L359) for a complete concrete example.

#### Fallback PasswordHashers

The list of `Config.FallbackPasswordHashers` can be used for migrating to a new Password Hashing algorithm by registering older Password Hashing implementations that were previously used to hash Users passwords. Failed password verifications will fallback to see if the password was hashed with any of the registered `FallbackPasswordHashers`, if any are valid, the password attempt will succeed and the password re-hashed with the registered `IPasswordHasher` implementation.

### Digest Auth Hashes only created when needed

Digest Auth Hashes are only populated if the `DigestAuthProvider` is registered. If you ever intend to support Digest access authentication in future but don't want to register the DigestAuthProvider just yet, you can force ServiceStack to continue to maintain Digest Auth Hashes with:

```csharp
new AuthFeature {
    CreateDigestAuthHashes = true
}
```

Users that don't have Digest Auth Hashes will require logging in again in order to have it populated. If you don't intend to use Digest Auth you can clear the `DigestHa1Hash` column in your `UserAuth` table which is otherwise unused.


# Using ServiceStack Auth in MVC
Source: https://docs.servicestack.net/auth/identity-servicestack

[mvcauth](https://github.com/NetCoreTemplates/mvcauth) is a .NET 6.0 MVC Website integrated with ServiceStack Auth:

[![](https://raw.githubusercontent.com/ServiceStack/Assets/master/csharp-templates/mvcauth.png)](https://github.com/NetCoreTemplates/mvcauth)

## New Project

Create new `mvcauth` project with:

:::sh
x new mvcauth ProjectName
:::

The ServiceStack Auth is pre-configured to persist users in an OrmLite Auth Repository (default SQLite) and enables both local
Username/Password Credentials Auth as well as external Sign In's via Facebook, Twitter, Google and the new Microsoft Graph OAuth providers:

```csharp
container.Register<IDbConnectionFactory>(c =>
    new OrmLiteConnectionFactory(":memory:", SqliteDialect.Provider));

container.Register<IAuthRepository>(c =>
    new OrmLiteAuthRepository(c.Resolve<IDbConnectionFactory>()) {
        UseDistinctRoleTables = true,
    });
container.Resolve<IAuthRepository>().InitSchema();

// TODO: Replace OAuth App settings in: appsettings.Development.json
Plugins.Add(new AuthFeature(() => new CustomUserSession(), 
    new IAuthProvider[] {
        new NetCoreIdentityAuthProvider(AppSettings) { // Adapter to enable ServiceStack Auth in MVC
            AdminRoles = { "Manager" }, // Automatically Assign additional roles to Admin Users
        },
        new CredentialsAuthProvider(AppSettings), // Sign In with Username / Password credentials 
        new FacebookAuthProvider(AppSettings),    // Create App at: https://developers.facebook.com/apps
        new TwitterAuthProvider(AppSettings),     // Create App at: https://dev.twitter.com/apps
        new GoogleAuthProvider(AppSettings),      // https://console.developers.google.com/apis/credentials
        new MicrosoftGraphAuthProvider(AppSettings), // Create App https://apps.dev.microsoft.com
    }) {
    IncludeRegistrationService = true,
    IncludeAssignRoleServices = false,
});
```

In ServiceStack users with the `Admin` roles are "super users" with unrestricted access to all protected resources whereas in MVC we need to specify 
all the Roles Admin Users should have access to with `AdminRoles` above.

We also see the built-in `Register` and `AssignRoles` Services are enabled to allow new User Registration and assignment of roles/permissions to existing users.

On Startup, 3 users are created to test out the different access levels: 

 1. A basic Authenticated User 
 2. A Manager with the `Manager` role 
 3. A Super User with the `Admin` role

```csharp
if (authRepo.GetUserAuthByUserName("user@gmail.com") == null)
{
    var testUser = authRepo.CreateUserAuth(new UserAuth
    {
        DisplayName = "Test User",
        Email = "user@gmail.com",
        FirstName = "Test",
        LastName = "User",
    }, "p@55wOrd");
}

if (authRepo.GetUserAuthByUserName("manager@gmail.com") == null)
{
    var roleUser = authRepo.CreateUserAuth(new UserAuth
    {
        DisplayName = "Test Manager",
        Email = "manager@gmail.com",
        FirstName = "Test",
        LastName = "Manager",
    }, "p@55wOrd");
    authRepo.AssignRoles(roleUser, roles:new[]{ "Manager" });
}

if (authRepo.GetUserAuthByUserName("admin@gmail.com") == null)
{
    var roleUser = authRepo.CreateUserAuth(new UserAuth
    {
        DisplayName = "Admin User",
        Email = "admin@gmail.com",
        FirstName = "Admin",
        LastName = "User",
    }, "p@55wOrd");
    authRepo.AssignRoles(roleUser, roles:new[]{ "Admin" });
}
```

You can sign in with any of these users and go to the the home page to test the behavior of the different granular protection levels
which contains links to both MVC and ServiceStack Public and Protected Pages and Services.

**mvcauth** also comes complete with User Registration where users can Sign up with either Password or using any of the registered OAuth providers:

![](https://raw.githubusercontent.com/ServiceStack/Assets/master/csharp-templates/mvcauth-login.png)

## Defaults to MVC Auth Redirect Conventions

When using `NetCoreIdentityAuthProvider` we assume you're going to use MVC for your UI so it overrides the HTML Redirects 
that Users will be redirected to when trying to access Pages they don't have access to:

```csharp
authFeature.HtmlRedirect = "~/Account/Login";
authFeature.HtmlRedirectAccessDenied = "~/Account/AccessDenied";
authFeature.HtmlRedirectReturnParam = "ReturnUrl";
authFeature.HtmlRedirectReturnPathOnly = true;
```

Where non-Authenticated Users will be redirected to MVC's convention of `/Account/Login?ReturnUrl=` instead of ServiceStack's `/login?redirect=`.

Alternatively you can retain ServiceStack's HTML redirect defaults with:

```csharp
new NetCoreIdentityAuthProvider(AppSettings) {
    OverrideHtmlRedirect = false
}
```


# Sessions
Source: https://docs.servicestack.net/auth/sessions

The `AuthFeature` (plugin) already enables the SessionFeature, but if you want to make use of sessions and don't want to enable the built-in [Authentication](/auth/authentication-and-authorization), you will need to register it manually in your AppHost with:

```csharp
public override void Configure(Container container)
{
    Plugins.Add(new SessionFeature());
}
```

## Cookie Session Ids

When the `SessionFeature` is enabled, a [Global RequestFilter](/request-and-response-filters) is added to ServiceStack to ensure that all requests have a Temporary `ss-id` and a Permanent `ss-pid` session cookies set. These Session Cookies contain a unique Random Base64-encoded Id. The `ss-opt` cookie stores the users preference on whether they want their current session to be temporary (`ss-opt=temp`) or permanent (`ss-opt=perm`) - i.e. to **RememberMe** or not - The Default is Temporary. 

## Permanent and Temporary Session Ids

The Permanent session cookie `ss-pid` is always created even if `ss-opt` is Temporary - this allows you to link and track subsequent requests together which can be helpful for user request analyzing. In contrast the temporary Session Id `ss-id` uses a temporary cookie that does not persist across a users browser sessions.

If you're interested in the implementation, all the source code for ServiceStack's Sessions are kept in the [ISession](https://github.com/ServiceStack/ServiceStack/blob/master/src/ServiceStack.Interfaces/Caching/ISession.cs), [SessionFeature](https://github.com/ServiceStack/ServiceStack/blob/master/src/ServiceStack/SessionFeature.cs), [SessionFactory](https://github.com/ServiceStack/ServiceStack/blob/master/src/ServiceStack/SessionFactory.cs), [SessionExtensions](https://github.com/ServiceStack/ServiceStack/blob/master/src/ServiceStack/SessionExtensions.cs) and [ServiceExtensions](https://github.com/ServiceStack/ServiceStack/blob/master/src/ServiceStack/ServiceExtensions.cs) classes.

## Can be used with any ICacheClient

ServiceStack's implementation of Sessions are clean, in that they work with all of [ServiceStack's Caching Providers](/caching) and are simply pointers to POCOs in your Cache.

### Formatting of Keys used in Cache Providers

For typed or Custom AuthSession the key is: 

```
urn:iauthsession:{sessionId}
```

When using un-typed **Session Bag** the key is:

```
sess:{sessionId}:{key}
```

The general recommendation is to use typed sessions, which will give you type-safety benefits as well as being able to fetch your entire users session with a single cache call. If you use the dynamic/session bag then it will be a network call for each key accessed - although as caches are designed for fast-access, this isn't too much of a concern.

In code `IRequest.GetSessionId()` returns the right `ss-id/ss-pid` for that request so you can programmatically access the session key and session for a request directly from the registered cache with:

```csharp
var sessionKey = SessionFeature.GetSessionKey(httpReq.GetSessionId());
var session = await httpReq.GetCacheClientAsync().GetAsync<IAuthSession>(sessionKey);
```

## Auth with Request AuthProviders

Auth Providers that authenticate with each request that implement `IAuthWithRequest` like [JWT](/auth/jwt-authprovider), [API Key](/auth/api-key-authprovider) and `BasicAuthProvider` don't persist Users Sessions in the cache, they're only in the `IRequest` and only last for the duration of the Request.

### Overriding a User Session

This alternative solution for populating a Users Session on each request can be utilized by injecting an authenticated UserSession in:

```csharp
IRequest req = base.Request;
req.Items[Keywords.Session] = usersSession;
```

## Using Typed Sessions in ServiceStack

An example of using Typed Sessions is in the [Social Bootstrap Api](https://github.com/ServiceStack/SocialBootstrapApi) demo where a [CustomUserSession](https://github.com/ServiceStack/SocialBootstrapApi/blob/master/src/SocialBootstrapApi/Models/CustomUserSession.cs) is defined as:

```csharp
[DataContract]
public class CustomUserSession : AuthUserSession 
{
    [DataMember]
    public string CustomId { get; set; }
}
```

By inheriting [AuthUserSession](https://github.com/ServiceStack/ServiceStack/blob/master/src/ServiceStack/AuthUserSession.cs) you're able to keep all the users session together in 1 POCO, which allows you to access everything in 1 cache read or write.

::: info
When inheriting from `AuthUserSession` you will need to annotate your properties with `[DataMember]` as AuthUserSession is a DataContract class
:::

::: info
When using JWT and `UseTokenCookie`, sessions are not saved in cache, instead they are encapsulated in the stateless `ss-tok` cookie. JWT only keeps data essential to authentication, any additional data should be resolved only as needed. Custom claims can be added using `PopulateSessionFilter`/`CreatePayloadFilter`. See [JWT docs](/auth/jwt-authprovider#limit-to-essential-info) for more info
:::

To tell ServiceStack to use your Custom Typed Session instead, register it in the `AuthFeature` plugin:

```csharp
Plugins.Add(new AuthFeature(() => new CustomUserSession(), ...));
```

## Session events

Inheriting from the AuthUserSession also lets you add custom logic for different events in the User Session life-cycle:

```csharp
// Fired when a new Session is created
void OnCreated(IRequest httpReq) {}

// Called after new sessions are hydrated, can be used to populate session with more info at runtime
void OnLoad(IRequest httpReq) {}

// Called when the user is registered or on the first OAuth login
void OnRegistered(IRequest httpReq, IAuthSession session, IServiceBase service) {}

// Called after the user has successfully authenticated
void OnAuthenticated(IServiceBase authService, IAuthSession session, IAuthTokens tokens, 
    Dictionary<string, string> authInfo) {}

// Fired before the session is removed after the /auth/logout Service is called
void OnLogout(IServiceBase authService) {}

// Override with Custom Validation logic to Assert if User is allowed to Authenticate. 
// Returning a non-null response invalidates Authentication with IHttpResult response returned to client.
IHttpResult Validate(IServiceBase authService, IAuthSession session, 
    IAuthTokens tokens, Dictionary<string, string> authInfo);
```

### Auth Events

The same authentication hooks that are available in the Custom UserSession above are also available in `IAuthEvents` API: 

```csharp
public interface IAuthEvents
{
    void OnRegistered(IRequest req, IAuthSession session, IServiceBase registerService);
    void OnAuthenticated(IRequest req, IAuthSession session, IServiceBase authService, 
        IAuthTokens tokens, Dictionary<string, string> authInfo);
    void OnLogout(IRequest req, IAuthSession session, IServiceBase authService);
    void OnCreated(IRequest req, IAuthSession session);
}
```

The new AuthEvents API provide a loose-typed way where plugins can tap into the same hooks by registering it with `AuthFeature.AuthEvents`, e.g:

```csharp
public class WebSudoFeature : IPlugin, IAuthEvents
{
    public void Register(IAppHost appHost)
    {
        ...
        var authFeature = appHost.GetPlugin<AuthFeature>();
        authFeature.AuthEvents.Add(this);
    }

    // Add implementations of all `IAuthEvents` handlers
    public void OnCreated(IRequest httpReq, IAuthSession session) { ... }
}
```

An alternative way for accessing `IAuthEvents` is to register it like a normal dependency, e.g:

```csharp
container.RegisterAs<LogAuthEvents,IAuthEvents>();
```

To simplify custom implementations you can inherit from the empty concrete [AuthEvents](https://github.com/ServiceStack/ServiceStack/blob/7eb3a34a2e545a54c2591665328c16c5d398d37a/src/ServiceStack/Auth/AuthEvents.cs#L18-L25) and choose to only implement the callbacks you're interested in, e.g:

```csharp
public class LogAuthEvents : AuthEvents
{
    public static ILog Log = LogManager.GetLogger(typeof(LogAuthEvents));

    public override void OnLogout(IRequest httpReq, IAuthSession session, IServiceBase authService) 
    {
        Log.DebugFormat("User #{0} {1} has logged out", session.UserAuthId, session.UserName);
    }
}
```

## UserSession validation

Custom User Sessions can override `AuthUserSession.Validate()` to add additional logic for validating whether to allow a User to Authenticate, e.g:

```csharp
public class CustomUserSession : AuthUserSession
{
    public override IHttpResult Validate(IServiceBase authService, IAuthSession session, 
        IAuthTokens tokens, Dictionary<string, string> authInfo)
    {
        if (!ValidateEmail(session.Email))
            return HttpError.BadRequest($"{nameof(session.Email)} is invalid") as IHttpResult;
        
        return null;
    }
}
```

Returning any `IHttpResult` will cause Authentication to fail with the returned `IHttpResult` written to the response.

## Accessing Typed Session

You can access your custom UserAuth session inside your service using the `SesssionAs<T>()` extension method, e.g:

```csharp
public abstract class MyService : Service 
{
    public object Get(MyRequest request)
    {
        var typedSession = this.SessionAs<CustomUserSession>();
    }
}
```

## Adding a Convenience wrapper

To provide a typed, Convenient API for your service you can add the following to a base class, here's SocialBootstrapApi's [AppServiceBase](https://github.com/ServiceStack/SocialBootstrapApi/blob/master/src/SocialBootstrapApi/ServiceInterface/AppServiceBase.cs) example:

```csharp
public abstract class AppServiceBase : Service {
    private CustomUserSession userSession;
    protected CustomUserSession UserSession {
        get {
            return base.SessionAs<CustomUserSession>();
        }
    }
}
```

This will then enable you to access your users Session in your ServiceStack services with `base.UserSession`.

## Cookie Filters

Customization of Cookies can be enabled by overriding the host-specific methods in your `AppHost`:

```csharp
//ASP.NET Core
public override void CookieOptionsFilter(Cookie cookie, Microsoft.AspNetCore.Http.CookieOptions cookieOptions) {}

//Classic ASP.NET
public override void HttpCookieFilter(HttpCookie cookie) {}
```

## Enable Same Site Cookies

[Same Site Cookies](https://www.sjoerdlangkemper.nl/2016/04/14/preventing-csrf-with-samesite-cookie-attribute/) are a good default to use 
in your Apps which restricts cookies from being sent cross-site in order to prevent against cross-site request forgery (CSRF) attacks. 

It can be configured in your `AppHost` with:

```csharp
SetConfig(new HostConfig
{
    UseSameSiteCookies = true
});
```

This restriction will prevent features reliant on cross-site cookies from working so you'll need to verify it's safe to enable in your Apps.
This restriction works with most Auth Providers except for `TwitterAuthProvider` who doesn't yet support the OAuth `state` callback that 
could be used instead of Session cookies.

## Secure Cookies enabled by default

[Secure Cookies](https://en.wikipedia.org/wiki/Secure_cookie) ensure that Cookies added over HTTPS are only resent in subsequent secure connections.

They're **enabled by default** for **Cookies added over SSL**, they can be disabled with:

```csharp
Plugins.Add(new HostConfig {
    UseSecureCookies = false
});
```

## Sharing ServiceStack's Typed Sessions in MVC and ASP.NET

ASP.NET's Session Provider model still maintains its old legacy .NET 1.0 roots with it's heavy XML-encumbered config model, it's coupled and un-testable API, and its [degrading performance limitations by design](http://stackoverflow.com/questions/3629709/i-just-discovered-why-all-asp-net-websites-are-slow-and-i-am-trying-to-work-out) makes it difficult for any web service framework to share the same User Sessions with the base ASP.NET Web Forms or MVC web host. 

ServiceStack gets around these limitations by providing its own de-coupled, testable and dependency-free [ICacheClient](https://github.com/ServiceStack/ServiceStack/blob/master/src/ServiceStack.Interfaces/Caching/ICacheClient.cs) and [ISession](https://github.com/ServiceStack/ServiceStack/blob/master/src/ServiceStack.Interfaces/Caching/ISession.cs) APIs - which all work simply together as they're just plain Guid Session Keys stored in Caches pointing to POCOs.

The method SessionFeature.GetSessionKey allows you to get a Session Key for a current request if you are trying to access it in ASP.NET Web Forms or MVC web host. Using a Session Key you can have a full control over Session object:

```csharp
// CacheClient is instance of ICacheClient

var sessionKey = SessionFeature.GetSessionKey();

// getting an existing User Session or create a new one 
var userSession = SessionFeature.GetOrCreateSession<AuthUserSession>(CacheClient); 
// or SessionFeature.GetOrCreateSession<CustomUserSession>(CacheClient); 
```

## Saving in Service

As a typed session is just a disconnected POCO, it needs to explicitly saved to be persisted - which you can do with the [base.SaveSession()](https://github.com/ServiceStack/ServiceStack/blob/6ac4bd1842c170f1569bb5aa1020a37c7bb4017d/src/ServiceStack/ServiceExtensions.cs#L73) Extension method.

```csharp
public async Task<object> Any(Request request)
{
    var session = await base.SessionAsAsync<AuthUserSession>();

    // modify session

    await base.Request.SaveSessionAsync(session);
}
```

## Saving outside a Service

If your logic is outside a ServiceStack service you can save your typed session by getting access to the ServiceStack `IRequest` which you can create from ASP.NET Request objects:

```csharp
IHttpRequest httpReq = aspCtx.ToRequest(); //HttpContext
IHttpRequest httpReq = aspReq.ToRequest(); //MVC HttpRequestBase
IHttpRequest httpReq = netCoreCtx.ToRequest(); //.NET Core HttpContext
IHttpRequest httpReq = listenerCtx.ToRequest(); //HttpListenerContext

//In ASP.NET hosts via the singleton
IHttpRequest httpReq = HostContext.AppHost.TryGetCurrentRequest(); 
```

Once you have access to the current `IRequest` you can save your typed session using the `SaveSessionAsync()` extension method:

```csharp
await httpReq.SaveSessionAsync(session);
```

This API is also available in MVC Controllers that inherit `ServiceStackController` or ASP.NET Pages that inherit `ServiceStackPage`:

```csharp
await base.SaveSessionAsync(session);
```

## Intercept Saving Sessions

Each time the Session is saved it's saved again with the default Session Expiry which can be specified on the top-level `AuthFeature.SessionExpiry` for temp Sessions or `AuthFeature.PermanentSessionExpiry` for permanent "Remember Me" Sessions.

For fine-grained control you can intercept each time a Session is saved and change what Session Expiry it's saved with by overriding `OnSaveSessionAsync` in your AppHost:

```csharp
public override Task OnSaveSessionAsync(
    IRequest httpReq, IAuthSession session, TimeSpan? expiresIn = null, CancellationToken token=default)
{
    var customExpiry = ...
    base.OnSaveSessionAsync(httpReq, session, customExpiry, token);
}
```

## Sliding Sessions

You can extend existing User Sessions in ServiceStack by just re-saving the Users Session.
This can be done anywhere in [ServiceStack's Request Pipeline](/order-of-operations), E.g.
in a [Request or Response Filter Attribute](/filter-attributes) or 
[Global Request or Response Filter](/request-and-response-filters):

E.g. here's a Sliding Sessions example using a custom `[SlideExpiration]` Response Filter Attribute:

```csharp
public class SlidingSessionAttribute : ResponseFilterAsyncAttribute
{
    public TimeSpan? Expiry { get; set; }

	public SlidingSessionAttribute(int expirySecs=0)
	{
		this.Expiry = expirySecs <= 0
            ? (TimeSpan?)null 
            : TimeSpan.FromSeconds(expirySecs);
	}

    public override async Task ExecuteAsync(IRequest req, IResponse res, object response)
    {
        var session = await req.GetSessionAsync();
        if (session != null) 
            await req.SaveSessionAsync(session, this.Expiry);
    }
}
```

Which can be applied to any protected User Services, e.g:

```csharp
[Authenticate]
[SlidingSession(10 * 60)] //= 10 minutes
public class UserServices : Service
{
    public object Any(MyUserRequest request) => ...;
}
```

Which just re-saves the Session in order to extend it with a new Session Expiry, this can 
instead be done in a Global Response Filter with:

```csharp
GlobalResponseFiltersAsync.Add(async (req, res, dto) => {
    var session = await req.GetSessionAsync();
    if (session != null)
        await req.SaveSessionAsync(session, TimeSpan.FromMinutes(10));
});
```

### Find the remaining time left before a Session expires

For [Cache Clients](/) that implement you can retrieve the 
`ICacheClientExtended.GetTimeToLive()` returns a `TimeSpan?` which will return:

 - `null` if no key exists
 - `TimeSpan.MaxValue` if there is no expiry set on the key
 - or a `TimeSpan` value with the time remaining before the key is set to expire

 So you can determine the remaining time on a Session by querying the **Time To Live** 
 remaining on the Session Key in the Cache which you could use to extend the Users Session
 by **10 minutes** if they have **less than 10 minutes** remaining:

```csharp
var sessionId = req.GetSessionId(); 
var sessionKey = SessionFeature.GetSessionKey(sessionId);
var ttl = req.GetCacheClient().GetTimeToLive(sessionKey);

if (ttl != null && ttl <= TimeSpan.FromMinutes(10)) 
{
    var session = await req.GetSessionAsync();
    await req.SaveSessionAsync(session, TimeSpan.FromMinutes(10));
}
```

## Typed Sessions in MVC

To make use of it in MVC, you effectively do the same thing, although this time you can simply inherit the existing [ServiceStackController](https://github.com/ServiceStack/ServiceStack/blob/master/src/ServiceStack.Mvc/ServiceStackController.cs) which has the above templated code in a generic MVC Controller Template:

```csharp
public class ControllerBase : ServiceStackController<CustomUserSession> {}
```

From there it's just a basic property which you can use in your Controller or assign to your views [like this](https://github.com/ServiceStack/SocialBootstrapApi/blob/master/src/SocialBootstrapApi/Controllers/HomeController.cs#L12):

```csharp
public partial class HomeController : ControllerBase 
{
    public virtual ActionResult Index() 
    {
        ViewBag.Message = "MVC + ServiceStack PowerPack!";
        ViewBag.UserSession = base.UserSession;
        return View();
    }   
}
```

## Typed Sessions in ASP.NET Web Forms

It's the same thing in ASP.NET Web Forms although this comes in the form of a [base ASP.NET Web Page](https://github.com/ServiceStack/ServiceStack/blob/master/NuGet/ServiceStack.Host.AspNet/content/App_Start/PageBase.cs.pp) which you get for free when you install ServiceStack via the [ServiceStack.Host.AspNet](http://nuget.org/packages/ServiceStack.Host.AspNet) NuGet package.

## Using Dynamic / Untyped Sessions in Session Bag

You can access the dynamic UserSession Bag in ServiceStack services via the `base.SessionBag` property already built-in ServiceStack's [Service](https://github.com/ServiceStack/ServiceStack/blob/master/src/ServiceStack/Service.cs) base class, e.g:

```csharp
await base.SessionBagAsync.SetAsync("cart", new Cart { ... });
var cart = await base.SessionBagAsync.GetAsync<Cart>("cart");
```

## Use HTTP Headers to Send Session Cookies

You can now make a Session-enabled request with HTTP Headers instead of Cookies. The Session HTTP Headers have a `X-` prefix before the Session Id, i.e: `X-ss-id`, `X-ss-pid` and `X-ss-opts`.

## Inspecting persisted User Sessions

ServiceStack Sessions are just serialized POCO's stored in the Registered `ICacheClient` at the following key:

```
urn:iauthsession:{SessionId}
```

Where `{SessionId}` is either the users `ss-id` or `ss-pid` cookie depending on whether the user was authenticated with `RememberMe=true` which instructs ServiceStack to save the session against the `ss-pid` permanent cookie - this preference is stored in the `ss-opt=perm` cookie.

Since they're just plain POCO's stored at a predictable key format, we can easily iterate through all user sessions by using the `ICacheClient` API's directly, e.g:

```csharp
var sessionPattern = IdUtils.CreateUrn<IAuthSession>(""); //= urn:iauthsession:
var sessionKeys = Cache.GetKeysStartingWith(sessionPattern).ToList();

var allSessions = Cache.GetAll<IAuthSession>(sessionKeys);
```

## Community Resources

  - [Sliding session expirations in ServiceStack](http://teadriven.me.uk/2013/02/14/sliding-sessions-in-service-stack/) by [@teadriven](https://twitter.com/teadriven)
  - [Accessing ASP.NET Session from ServiceStack](http://www.richardfawcett.net/2012/02/29/accessing-asp-net-session-from-servicestack/) by [@yeurch](https://twitter.com/yeurch)
  - [REST Web Services with ServiceStack](https://web.archive.org/web/20121124003901/http://openlandscape.net/2011/03/21/rest-web-services-with-servicestack) by Jacques du Preez


# JWT Auth Provider
Source: https://docs.servicestack.net/auth/jwt-authprovider

::: info
When using [ASP.NET Core Identity Auth](/auth/identity-auth) refer to [JWT Identity Auth](/auth/jwt-identity-auth) instead
:::

<lite-youtube class="w-full mx-4 my-4" width="560" height="315" videoid="NTCUT7atoLo" style="background-image: url('https://img.youtube.com/vi/NTCUT7atoLo/maxresdefault.jpg')"></lite-youtube>

The `JwtAuthProvider` is our integrated Auth solution for the popular [JSON Web Tokens](https://jwt.io/) (JWT) industry standard which is easily enabled by registering the `JwtAuthProvider` with the `AuthFeature` plugin:

```csharp
Plugins.Add(new AuthFeature(...,
    new IAuthProvider[] {
        new JwtAuthProvider(AppSettings) { AuthKey = AesUtils.CreateKey() },
        new CredentialsAuthProvider(AppSettings),
        //...
    }));
```

At a minimum you'll need to specify the `AuthKey` that will be used to Sign and Verify JWT tokens.
Whilst creating a new one in memory as above will work, a new Auth Key will be created every time the 
AppDomain recycles which will invalidate all existing JWT Tokens created with the previous key. 

## Generate new Auth Key

You can create a new **Base64 Auth Key** by running the code snippet below locally:

```csharp
var base64Key = System.Convert.ToBase64String(ServiceStack.AesUtils.CreateKey());
```

You'll typically want to generate the AuthKey out-of-band and configure it with the `JwtAuthProvider` at
registration which you can do in code using any of the [AppSettings providers](/appsettings):

```csharp
new JwtAuthProvider(AppSettings) { 
    AuthKeyBase64 = AppSettings.GetString("AuthKeyBase64") 
}
```

Or alternatively you can configure most `JwtAuthProvider` properties in your **appsettings.json** or **Web.config** `<appSettings/>` 
following the `jwt.{PropertyName}` format:

#### appsettings.json

```json
{
    "jwt.AuthKeyBase64": "{Base64AuthKey}"
}
```

#### Web.config

```xml
<add key="jwt.AuthKeyBase64" value="{Base64AuthKey}" />
```

As with all crypto keys you'll want to keep them confidential as if anyone gets a hold of your AuthKey 
they'll be able to forge and sign their own JWT tokens letting them be able to impersonate any user, 
roles or permissions!

### Upgrade to v5.9.2

If you're using JWT Auth please upgrade to v5.9.2 when possible to resolve a JWT signature verification issue comparing different lengthed signatures. 

If you're not able to upgrade, older versions should ensure a minimum length signature with a custom `ValidateToken`, e.g:

```csharp
new JwtAuthProvider(...) {
    ValidateToken = (js,req) => req.GetJwtToken().LastRightPart('.').FromBase64UrlSafe().Length >= 32,
}
```

## JWT Token Cookies

From **v6+** the default configuration of the [JWT Auth Provider](/auth/jwt-authprovider) uses **HTTP Token Cookies by default** which is both recommended [for Web Apps](https://stormpath.com/blog/where-to-store-your-jwts-cookies-vs-html5-web-storage#where-to-store-your-jwts) that's also better able to support effortless JWT Token management features.

It allows for a more interoperable and seamless solution as it already works with the normal client logic for authenticating using normal [Server Session Cookies](/auth/sessions), e.g:

```csharp
let api = client.api(new Authenticate({ provider:'credentials', userName, password, rememberMe }))
```

Which also works transparently after a configuring to use JWT on the server to switch to using stateless JWT Tokens, as in both cases the HTTP Clients utilize Cookies to enable authenticated requests.

### Transparent Server Auto Refresh of JWT Tokens

JWTs enable stateless authentication of clients without servers needing to maintain any Auth state in server infrastructure or perform any I/O to validate a token. As such, [JWTs are a popular choice for Microservices](/auth/jwt-authprovider#stateless-auth-microservices) as they only need to configured with confidential keys to validate access.

But to be able to terminate a users access, they need to revalidate their eligibility to verify they're still allowed access (e.g. deny Locked out users). This JWT revalidation pattern is implemented using [Refresh Tokens](/auth/jwt-authprovider#refresh-tokens) which are used to request revalidation of their access with a new JWT Access Token which they'll be able to use to make authenticated requests until it expires.

Previously the management of **auto refreshing expired JWT Access Tokens** was done with logic built into each of our smart generic Service Clients. But switching to use Token Cookies allows us to implement the revalidation logic on the server where it's now able to do this **transparently for all HTTP Clients**, i.e. it's no longer just limited to our typed Service Clients. 

### Revert to Bearer Token Responses

If you prefer not to use HTTP Token Cookies and want to manually handle JWT Auth Tokens, you can revert to returning JWT Tokens in `AuthenticateResponse` API responses with:

```csharp
new JwtAuthProvider(AppSettings) {
    UseTokenCookie = false
}
```

JWT Token Cookies are supported for most built-in Auth Providers including `Authenticate` Requests as well as **OAuth Web Flow** Sign Ins.

The alternative to configuring on the server is for clients to request it with [UseTokenCookie on the Authenticate Request](#request-jwt-cookie-is-set-on-authentication) or in a [hidden FORM Input](#switching-existing-sites-to-jwt). 

### RequireSecureConnection

The JWT Auth Provider defaults to `RequireSecureConnection=true` which mandates for Authentication via either Provider to happen over a secure (HTTPS) connection as both bearer tokens should be kept highly confidential. You can specify `RequireSecureConnection=false` to disable this requirement for testing or within controlled internal environments.

## Sending JWT with Service Clients

JWT Tokens can be sent using the Bearer Token support in all HTTP and Service Clients:

```csharp
var client = new JsonApiClient(baseUrl) {
    BearerToken = jwtToken
};

var response = await "https://example.org/secured".GetJsonFromUrlAsync(
    requestFilter: req => req.AddBearerToken(jwtToken));
```

The Service Clients offer additional high-level functionality where it's able to transparently request 
a new JWT Token after it expires by handling when the configured JWT Token becomes invalidated in the 
`OnAuthenticationRequired` callback. Here we can retrieve a new JWT Token that we can fetch using a 
different Service Client accessing a centralized and independent Auth Microservice that's configured with 
both API Key and JWT Token Auth Providers. We can fetch a new JWT Token by calling ServiceStack's 
built-in `Authenticate` Service with our **secret** API Key (that by default never invalidates unless revoked).

If authenticated, sending an empty `Authenticate()` DTO will return the currently Authenticated User Info 
that also generates a new JWT Token from the User's Authenticated Session and returns it in the `BearerToken` 
Response DTO property which we can use to update our invalidated JWT Token.

All together we can configure our Service Client to transparently refresh expired JWT Tokens with just:

```csharp
var authClient = JsonServiceClient(centralAuthBaseUrl) {
    Credentials = new NetworkCredential(apiKey, "")
};

var client = new JsonServiceClient(baseUrl);
client.OnAuthenticationRequired = () => {
    client.BearerToken = authClient.Send(new Authenticate()).BearerToken;
};
```

### Sending JWT using Cookies

To [improve accessibility with Ajax clients](https://stormpath.com/blog/where-to-store-your-jwts-cookies-vs-html5-web-storage) JWT Tokens can also be sent using the `ss-tok` Cookie, e.g:

```csharp
var client = new JsonServiceClient(baseUrl);
client.SetCookie("ss-tok", jwtToken);

//Equivalent to: 
client.SetTokenCookie(jwtToken);
```

We'll walk through an example of how you can access JWT Tokens as well as how you can convert Authenticated
Sessions into JWT Tokens and assign it to use a **Secure** and **HttpOnly** Cookie later on.

### Sending JWT in Request DTOs

Similar to the `IHasSessionId` interface Request DTOs can also implement `IHasBearerToken` to send Bearer Tokens as an alternative for sending them in HTTP Headers or Cookies, e.g:

```csharp
public class Secure : IHasBearerToken
{
    public string BearerToken { get; set; }
    public string Name { get; set; }
}

var response = client.Get(new Secure { BearerToken = jwtToken, Name = "World" });
```

Alternatively you can set the `BearerToken` property on the Service Client once where it will automatically populate all Request DTOs 
that implement `IHasBearerToken`, e.g:

```csharp
client.BearerToken = jwtToken;

var response = client.Get(new Secure { Name = "World" });
```

## JWT Overview

A nice property of JWT tokens is that they allow for truly stateless authentication where API Keys and user 
credentials can be maintained in a decentralized Auth Service that's kept isolated from the rest of your 
System, making them optimal for use in Microservice architectures.

Being self-contained lends JWT tokens to more scalable, performant and flexible architectures as they don't 
require any I/O or any state to be accessed from App Servers to validate the JWT Tokens, this is unlike all 
other Auth Providers which requires at least a DB, Cache or Network hit to authenticate the user.

A good introduction into JWT is available from the JWT website: [jwt.io/introduction/](https://jwt.io/introduction/) whilst [JWT vs Sessions](https://float-middle.com/json-web-tokens-jwt-vs-sessions/) is a good article on advantages of using JWT instead of Sessions.

## JWT Format

Essentially JWT's consist of 3 parts separated by `.` with each part encoded in 
[Base64url Encoding](https://tools.ietf.org/html/rfc4648#section-5) making it safe to encode both text and
binary using only URL-safe (i.e. non-escaping required) chars in the following format:

    Base64UrlHeader.Base64UrlPayload.Base64UrlSignature 

Where just like the API Key, JWT's can be sent as a Bearer Token in the `Authorization` HTTP Request Header.

### JWT Header

The header typically consists of two parts: the type of the token and the hashing algorithm being used 
which is typically just:

```json
{
  "alg": "HS256",
  "typ": "JWT"
}
```

We also send the "kid" [Key Id](http://self-issued.info/docs/draft-jones-json-web-token-01.html#rfc.section.5.1)
used to identify which key should be used to validate the signature to help with seamless key rotations in 
future. If not specified the KeyId defaults to the **first 3 chars** of the Base64 HMAC or RSA Public Key Modulus.

### JWT Payload

The Payload contains the essential information of a JWT Token which is made up of "claims", i.e. 
statements and metadata about a user which are categorized into 3 groups: 

 - [Registered Claim Names](https://tools.ietf.org/html/rfc7519#section-4.1) - containing a known set of 
reserved names predefined in the JWT Standard
 - [Public Claim Names](https://tools.ietf.org/html/rfc7519#section-4.2) - additional common names that are
 registered in the [IANA "JSON Web Token Claims" registry](http://www.iana.org/assignments/jwt/jwt.xhtml) or
 otherwise adopt a Collision-Resistant name, e.g. prefixed by a namespace
 - [Private Claim Names](https://tools.ietf.org/html/rfc7519#section-4.3) - any other metadata you wish to
 include about an entity

We use the Payload to store essential information about the user which we use to validate the token and 
populate the session. Which typically contains:

 - **iss** ([Issuer](https://tools.ietf.org/html/rfc7519#section-4.1.1)) - the principal that issued the
 JWT. Can be set with `JwtAuthProvider.Issuer`, defaults to **ssjwt**
 - **sub** ([Subject](https://tools.ietf.org/html/rfc7519#section-4.1.2)) - identifies the subject of 
 the JWT, used to store the User's **UserAuthId**
 - **iat** ([Issued At](https://tools.ietf.org/html/rfc7519#section-4.1.6)) - when JWT Token was issued.
 Can use `InvalidateTokensIssuedBefore` to invalidate tokens issued before a specific date
 - **exp** ([Expiration Time](https://tools.ietf.org/html/rfc7519#section-4.1.4)) - when the JWT expires. 
 Initialized with `JwtAuthProvider.ExpireTokensIn` from date of issue (default **14 days**)
 - **aud** ([Audience](https://tools.ietf.org/html/rfc7519#section-4.1.3)) - identifies the recipient of
 the JWT. Can be set with `JwtAuthProvider.Audience`, defaults to `null` (Optional)

The remaining information in the JWT Payload is used to populate the Users Session, to maximize interoperability
we've used the most appropriate [Public Claim Names](http://www.iana.org/assignments/jwt/jwt.xhtml) 
where possible:

 - **email** <- `session.Email`
 - **given_name** <- `session.FirstName`
 - **family_name** <- `session.LastName`
 - **name** <- `session.DisplayName`
 - **preferred_username** <- `session.UserName`
 - **picture** <- `session.ProfileUrl`

We also need to capture Users Roles and Permissions but as there's no Public Claim Name for this yet we're using 
[Azure's Active Directory Conventions](https://azure.microsoft.com/en-us/documentation/articles/active-directory-token-and-claims/) where User Roles are stored in **roles** as a JSON Array and similarly, Permissions are stored in **perms**.

To keep the JWT Token small we're only storing the essential User Info above in the Token, which means when
the Token is restored it will only be partially populated. You can detect when a Session was partially 
populated from a JWT Token with the new `FromToken` boolean property.

### Limit to Essential Info

Only the above partial information is included in JWT payloads as JWTs are typically resent with every request that
adds overhead to each HTTP Request so special consideration should be given to limit its payload to only 
include essential information identifying the User, any authorization info or other info that needs to accessed by most requests, 
e.g. TenantId for usage in partitioned queries or Display Info shown on each server generated page, etc.

Any other info is recommended to not be included in JWT's, instead they should be sourced from the App's data sources 
using the identifying user info stored in JWTs when needed. 

You can add any additional properties you want included in JWTs and authenticated User Infos by using the 
`CreatePayloadFilter` and `PopulateSessionFilter` filters below, be mindful to include only minimal essential
info and keep the properties names small to reduce the size (and request overhead) of JWTs.

### Modifying the Payload

Whilst only limited info is embedded in the payload by default, all matching 
[AuthUserSession](https://github.com/ServiceStack/ServiceStack/blob/master/src/ServiceStack/AuthUserSession.cs)
properties embedded in the token will also be populated on the Session, which you can add to the payload 
using the `CreatePayloadFilter` delegate. So if you also want to have access to when the user was registered 
you can add it to the payload with:

```csharp
new JwtAuthProvider(AppSettings) 
{
    CreatePayloadFilter = (payload,session) => 
        payload["CreatedAt"] = session.CreatedAt.ToUnixTime().ToString()
}
```

You can also use the filter to modify any existing property which you can use to change the behavior of the
JWT Token, e.g. we can add a special exception extending the JWT Expiration to all Users from Acme Inc with:

```csharp
new JwtAuthProvider(AppSettings) 
{
    CreatePayloadFilter = (payload,session) => {
        if (session.Email.EndsWith("@acme.com")) 
            payload["exp"] = DateTime.UtcNow.AddYears(1).ToUnixTime().ToString();
    }
}
```

Likewise you can modify how the Users Session is populated from the custom JWT with the `PopulateSessionFilter`, e.g:

```csharp
new JwtAuthProvider(AppSettings) 
{
    PopulateSessionFilter = (session,payload,req) => 
        session.CreatedAt = long.Parse(payload["CreatedAt"]).FromUnixTime();
}
```

If needed you can also modify JWT Headers with the `CreateHeaderFilter` delegate.

### JWT Signature

JWT Tokens are possible courtesy of the cryptographic signature added to the end of the message that's used 
to Authenticate and Verify that a Message hasn't been tampered with. As long as the message signature 
validates with our `AuthKey` we can be certain the contents of the message haven't changed from when it was 
created by either ourselves or someone else with access to our AuthKey.

JWT standard allows for a number of different Hashing Algorithms although requires at least the **HM256** 
HMAC SHA-256 to be supported which is the default. The full list of Symmetric HMAC and Asymmetric RSA
Algorithms `JwtAuthProvider` supports include:

 - **HS256** - Symmetric HMAC SHA-256 algorithm
 - **HS384** - Symmetric HMAC SHA-384 algorithm
 - **HS512** - Symmetric HMAC SHA-512 algorithm
 - **RS256** - Asymmetric RSA with PKCS#1 padding with SHA-256
 - **RS384** - Asymmetric RSA with PKCS#1 padding with SHA-384
 - **RS512** - Asymmetric RSA with PKCS#1 padding with SHA-512

HMAC is the simplest to use as it lets you use the same AuthKey to Sign and Verify the message. 

But if preferred you can use an RSA Key to sign and verify tokens by changing the `HashAlgorithm` and 
specifying a RSA Private Key:

```csharp
new JwtAuthProvider(AppSettings) { 
    HashAlgorithm = "RS256",
    PrivateKeyXml = AppSettings.GetString("PrivateKeyXml") 
}
```

If you don't have a RSA Private Key, one can be created with:

```csharp
var privateKey = RsaUtils.CreatePrivateKeyParams(RsaKeyLengths.Bit2048);
```

And its public key can be extracted using `ToPublicRsaParameters()` extension method, e.g:

```csharp
var publicKey = privateKey.ToPublicRsaParameters();
```

Then to serialize RSA Keys, you can then export them to XML with:

```csharp
var privateKeyXml = privateKey.ToPrivateKeyXml()
var publicKeyXml = privateKey.ToPublicKeyXml();
```

The behavior of using RSA to sign the JWT Tokens is mostly transparent but instead of using the AuthKey to 
both Sign and Verify the JWT Payload, it's signed with the Private Key and verified using the Public Key.
New tokens will also have the **alg** JWT Header set to **RS256** to reflect the new HashAlgorithm used.

## Encrypted JWE Tokens

Something that's not immediately obvious is that while JWT Tokens are signed to prevent tampering and 
verify authenticity, they're not encrypted and can easily be read by decoding the URL-safe Base64 string.
This is a feature of JWT where it allows Client Apps to inspect the User's claims and hide functionality
they don't have access to, it also means that JWT Tokens are debuggable and can be inspected for whenever 
you need to track down unexpected behavior.

But there may be times when you want to embed sensitive information in your JWT Tokens in which case you'll
want to enable Encryption, which can be done with:

```csharp
new JwtAuthProvider(AppSettings) { 
    PrivateKeyXml = AppSettings.GetString("PrivateKeyXml"),
    EncryptPayload = true
}
```

When turning on encryption, tokens are instead created following the
[JSON Web Encryption (JWE)](https://tools.ietf.org/html/rfc7516#section-3) standard where they'll be
encoded in the 5-part [JWE Compact Serialization](https://tools.ietf.org/html/rfc7516#section-3.1) format:

```
BASE64URL(UTF8(JWE Protected Header)) || '.' ||
BASE64URL(JWE Encrypted Key)          || '.' ||
BASE64URL(JWE Initialization Vector)  || '.' ||
BASE64URL(JWE Ciphertext)             || '.' ||
BASE64URL(JWE Authentication Tag)
```

JwtAuthProvider's JWE implementation uses RSAES OAEP for Key Encryption and AES/128/CBC HMAC SHA256 for
Content Encryption, closely following 
[JWE's AES_128_CBC_HMAC_SHA_256 Example](https://tools.ietf.org/html/rfc7516#appendix-A.2)
where a new MAC Auth and AES Crypt Key and IV are created for each Token. The Content Encryption Key (CEK) 
used to Encrypt and Authenticate the payload is encrypted using the Public Key and decrypted with the 
Private Key so only Systems with access to the Private Key will be able to Decrypt, Validate and Read 
the Token's payload.

## Stateless Auth Microservices

One of JWT's most appealing features is its ability to decouple the System that provides User Authentication 
Services and issues tokens from all the other Systems but are still able provide protected Services although 
no longer needs access to a User database or Session data store to facilitate it, as sessions can now be 
embedded in Tokens and its state maintained and sent by clients instead of accessed from each App Server. 
This is ideal for Microservice architectures where Auth Services can be isolated into a single 
externalized System.

With this use-case in mind we've decoupled `JwtAuthProvider` in 2 classes:

 - [JwtAuthProviderReader](https://github.com/ServiceStack/ServiceStack/blob/master/src/ServiceStack/Auth/JwtAuthProviderReader.cs) - 
Responsible for validating and creating Authenticated User Sessions from tokens
 - [JwtAuthProvider](https://github.com/ServiceStack/ServiceStack/blob/master/src/ServiceStack/Auth/JwtAuthProvider.cs) -
Inherits `JwtAuthProviderReader` to also be able to Issue, Encrypt and provide access to tokens

### Services only Validating Tokens

This lets us configure our Microservices that we want to enable Authentication via JWT Tokens down to just:

```csharp
public override void Configure(Container container)
{
    Plugins.Add(new AuthFeature(() => new AuthUserSession(),
        new IAuthProvider[] {
            new JwtAuthProviderReader(AppSettings) {
                HashAlgorithm = "RS256",
                PublicKeyXml = AppSettings.GetString("PublicKeyXml")
            },
        }));
}
```

Or if you want to just use a single AuthKey for both Issuing and Validating tokens:

```csharp
Plugins.Add(new AuthFeature(() => new AuthUserSession(),
    new [] { new JwtAuthProviderReader(AppSettings) }));
```

Which can be configured in [AppSettings](/appsettings):

```xml
<add key="jwt.AuthKeyBase64" value="{Base64AuthKey}" />
```

Which no longer needs access to a 
[IUserAuthRepository](/auth/authentication-and-authorization#userauth-persistence---the-iuserauthrepository)
or [Sessions](/auth/sessions) since they're populated entirely
from JWT Tokens. Whilst you can use the default **HS256** HashAlgorithm, RSA is ideal for this use-case
as you can limit access to the **PrivateKey** to only the central Auth Service issuing the tokens and then 
only distribute the **PublicKey** to each Service which needs to validate them.

### Service Issuing Tokens

As we can now contain all our Systems Auth Functionality to a single System we can open it up to support 
multiple Auth Providers as it only needs to be maintained in a central location but is still able to 
benefit all our Microservices that are only configured to validate JWT Tokens.

Here's a popular Auth Server configuration example which stores all User Auth information as well as
User Sessions in SQL Server and is configured to support many of ServiceStack's Auth and OAuth providers:

```csharp
public override void Configure(Container container)
{
    //Store UserAuth in SQL Server
    var dbFactory = new OrmLiteConnectionFactory(
        AppSettings.GetString("LiveDb"), SqlServerDialect.Provider);
        
    container.Register<IDbConnectionFactory>(dbFactory);
    container.Register<IAuthRepository>(c =>
        new OrmLiteAuthRepository(dbFactory) { UseDistinctRoleTables = true });

    //Create UserAuth RDBMS Tables
    container.Resolve<IAuthRepository>().InitSchema();

    //Also store User Sessions in SQL Server
    container.RegisterAs<OrmLiteCacheClient, ICacheClient>();
    container.Resolve<ICacheClient>().InitSchema();
    
    //Add Support for 
    Plugins.Add(new AuthFeature(() => new AuthUserSession(),
        new IAuthProvider[] {
            new JwtAuthProvider(AppSettings) {
                HashAlgorithm = "RS256",
                PrivateKeyXml = AppSettings.GetString("PrivateKeyXml")
            },
            new ApiKeyAuthProvider(AppSettings),        //Sign-in with API Key
            new CredentialsAuthProvider(),              //Sign-in with UserName/Password credentials
            new BasicAuthProvider(),                    //Sign-in with HTTP Basic Auth
            new DigestAuthProvider(AppSettings),        //Sign-in with HTTP Digest Auth
            new TwitterAuthProvider(AppSettings),       //Sign-in with Twitter
            new FacebookAuthProvider(AppSettings),      //Sign-in with Facebook
            new YahooOpenIdOAuthProvider(AppSettings),  //Sign-in with Yahoo OpenId
            new OpenIdOAuthProvider(AppSettings),       //Sign-in with Custom OpenId
            new GoogleOAuth2Provider(AppSettings),      //Sign-in with Google OAuth2 Provider
            new LinkedInOAuth2Provider(AppSettings),    //Sign-in with LinkedIn OAuth2 Provider
            new GithubAuthProvider(AppSettings),        //Sign-in with GitHub OAuth Provider
            new YandexAuthProvider(AppSettings),        //Sign-in with Yandex OAuth Provider        
            new VkAuthProvider(AppSettings),            //Sign-in with VK.com OAuth Provider 
        }));
}
```

With this setup we can Authenticate using any of the supported Auth Providers with our central Auth Server, retrieve the generated Token and use it to communicate with any our Microservices configured to validate tokens:

## Retrieve Token from Central Auth Server using Credentials Auth

```csharp
var authClient = new JsonServiceClient(centralAuthBaseUrl);

var authResponse = authClient.Post(new Authenticate {
    provider = "credentials",
    UserName = "user",
    Password = "pass",
    RememberMe = true,
});

var client = new JsonServiceClient(BaseUrl) {
    BearerToken = authResponse.BearerToken //Send JWT in HTTP Authorization Request Header
};
var response = client.Get(new Secured { ... });
```

Once the ServiceClient is configured it can also optionally be converted to send the JWT Token using the `ss-tok` Cookie instead by [calling `ConvertSessionToToken`](/auth/jwt-authprovider#sending-jwt-with-service-clients), e.g:

```csharp

client.Send(new ConvertSessionToToken());

client.BearerToken = null; // No longer needed as JWT is automatically sent in ss-tok Cookie

var response = client.Get(new Secured { ... });
```

### Retrieve Token from Central Auth Server using API Key

You can also choose to Authenticate with any AuthProvider and the `Authenticate` Service will return the JWT Token if Authentication was successful. 

The example below uses the JWT Token authenticates with the central Auth Server via its configured [API Key Auth Provider](/auth/api-key-authprovider). If successful the generated JWT can be populated in any of your Service Clients as normal, e.g:

```csharp
var authClient = new JsonServiceClient(centralAuthBaseUrl) {
    Credentials = new NetworkCredential(apiKey, "")
};

var jwtToken = authClient.Send(new Authenticate()).BearerToken;

var client = new JsonServiceClient(service1BaseUrl) { BearerToken = jwtToken };
var response = client.Get(new Secured { ... });
```

### Retrieve Token with HTTP Basic Auth

```csharp
var authClient = new JsonServiceClient(centralAuthBaseUrl) {
    Credentials = new NetworkCredential(username, password)
};

var jwtToken = authClient.Send(new Authenticate()).BearerToken;
```

### Retrieve Token with Credentials Auth

```csharp
var authClient = new JsonServiceClient(centralAuthBaseUrl);

var jwtToken = authClient.Send(new Authenticate {
    provider = "credentials",
    UserName = username,
    Password = password
}).BearerToken;
```

## Refresh Tokens

Just like JWT Tokens, Refresh Tokens are populated on the `AuthenticateResponse` DTO after successfully 
authenticating via any registered Auth Provider, e.g:

```csharp
var response = client.Post(new Authenticate {
    provider = "credentials",
    UserName = userName,
    Password = password,
});

var jwtToken = response.BearerToken;
var refreshToken = response.RefreshToken;
```

### Automatically refreshing Access Tokens

The `RefreshToken` property in all Service Clients can be used to instruct the client to automatically 
retrieve a new JWT Token behind-the-scenes when the original JWT token has expired, e.g:

```csharp
var client = new JsonServiceClient(baseUrl) {
    BearerToken = jwtToken,
    RefreshToken = refreshToken,
};

var response = client.Send(new Secured());
```

You don't even need to configure the client with a JWT Token as it will also fetch a new one on first use:

```csharp
var client = new JsonServiceClient(baseUrl) {
    RefreshToken = refreshToken,
};

var response = client.Send(new Secured());
```

## Using an alternative JWT Server

By default Service Clients will assume they should call the same ServiceStack Instance at the BaseUrl it's 
configured with to fetch new JWT Tokens. If instead refresh tokens need to be sent to a different server, 
it can be specified using the `RefreshTokenUri` property, e.g:

```csharp
var client = new JsonServiceClient(baseUrl) {
    RefreshToken = refreshToken,
    RefreshTokenUri = authBaseUrl + "/access-token"
};
```

## Handling Refresh Tokens Expiring

For the case when Refresh Tokens themselves expire the `WebServiceException` is wrapped in a typed 
`RefreshTokenException` to make it easier to handle initiating the flow to re-authenticate the User, e.g:

```csharp
try
{
    var response = client.Send(new Secured());
} 
catch (RefreshTokenException ex) 
{
    // re-authenticate to get new RefreshToken
}
```

## Lifetimes of tokens

The default expiry time of JWT and Refresh Tokens below can be overridden when registering the `JwtAuthProvider`:

```csharp
new JwtAuthProvider {
    ExpireTokensIn        = TimeSpan.FromDays(14),  // JWT Token Expiry
    ExpireRefreshTokensIn = TimeSpan.FromDays(365), // Refresh Token Expiry
}
```

These expiry times are use-case specific so you'll want to check what values are appropriate for your System.
The `ExpireTokensIn` property controls how long a client is allowed to make Authenticated Requests with the same JWT Token, whilst the `ExpireRefreshTokensIn` property controls how long the client can keep requesting new JWT Tokens using the same Refresh Token before needing to re-authenticate and generate a new one.

### Requires User Auth Repository or IUserSessionSourceAsync

One limitation for Refresh Tokens support is that it must be configured to use a 
[User Auth Repository](/auth/authentication-and-authorization#user-auth-repository)
which is the persisted data source used to rehydrate the User Session that's embedded in the JWT Token.

Users who are not using an `IAuthRepository` can instead implement the `IUserSessionSourceAsync` interface:

```csharp
public interface IUserSessionSourceAsync
{
    Task<IAuthSession> GetUserSessionAsync(string userAuthId, CancellationToken token=default);
}
```

On either their **Custom AuthProvider**, or if preferred register it as a **dependency in the IOC** as an alternative source for populating Sessions in new JWT Tokens created using RefreshToken's. The implementation should only return a populated `IAuthSession` if the User is allowed to sign-in, e.g. if their account is locked or suspended it should throw an Exception:

```csharp
throw HttpError.Forbidden("User is suspended");
```

## Convert Sessions to Tokens

Another useful Service that `JwtAuthProvider` provides is being able to Convert your current Authenticated
Session into a Token. Authenticating via Credentials Auth establishes an **Authenticated Session** with the
server which is captured in the 
[Session Cookies](/auth/sessions#cookie-session-ids)
that gets populated on the HTTP Client. This lets us access protected Services immediately after we've
successfully Authenticated, e.g:

```csharp
var authResponse = client.Send(new Authenticate {
    provider = "credentials",
    UserName = username,
    Password = password
});

var response = client.Get(new Secured { ... });
```

## Request JWT Cookie is set on Authentication

However this only establishes an **Authenticated Session** to a single Server that only lasts until the
session stored on the Server is valid. The easiest way to tell ServiceStack to convert the Session into a
stateless JWT Cookie instead is to set the `UseTokenCookie` option when authenticating, e.g:

```csharp
var authResponse = client.Send(new Authenticate {
    provider = "credentials",
    UserName = username,
    Password = password,
    UseTokenCookie = true
});

//Uses stateless ss-tok Cookie with our Session encapsulated in JWT Token
var response = client.Get(new Secured { ... }); 
var jwtToken = client.GetTokenCookie(); //From ss-tok Cookie
```

This also removes the our Session from the App Servers Cache as now the Users **Authenticated Session** is
contained solely in the JWT Cookie and is valid until the JWT Cookies Expiration, instead of determined
by Server Session State.

## Server Token Cookies

In most cases the easiest way to utilize JWT with your other Auth Providers is to configure `JwtAuthProvider` to use `UseTokenCookie` to
automatically return a JWT Token Cookie for all Auth Providers authenticating via `Authenticate` requests or after a successful OAuth Web Flow
from an [OAuth Provider](/auth/authentication-and-authorization#oauth-providers).

This is what [techstacks.io](https://techstacks.io) uses to maintain Authentication via a JWT Token after Signing in with Twitter or GitHub:

```csharp
Plugins.Add(new AuthFeature(() => new CustomUserSession(), 
    new IAuthProvider[] {
        new TwitterAuthProvider(AppSettings),
        new GithubAuthProvider(AppSettings),    
        new JwtAuthProvider(AppSettings) {
            UseTokenCookie = true,
        }
    }));
```

Clients can then detect whether a user is authenticated by sending an empty `Authenticate` request which either returns a `AuthenticateResponse` DTO
containing basic Session Info for authenticated requests otherwise throws a **401 Unauthorized** response.

So clients will be able to detect whether a user is authenticated with something like:

```ts
const client = new JsonServiceClient(BaseUrl);

async function getSession() {
    try {
        return await client.get(new Authenticate());
    } catch (e) {
        return null;
    }
}

const isAuthenticated = async () => await getSession() != null;

//...

if (await isAuthenticated()) {
    // User is authenticated
}
```

## Converting an existing Authenticated Session into A JWT Token

Another way we can access our Token is to call the `ConvertSessionToToken` Service which also converts our 
currently Authenticated Session into a JWT Token which we can use instead to communicate with all our 
independent Services, e.g:

```csharp
var tokenResponse = client.Send(new ConvertSessionToToken());
var jwtToken = client.GetTokenCookie(); //From ss-tok Cookie

var client2 = new JsonServiceClient(service2BaseUrl) { BearerToken = jwtToken };
var response = client2.Get(new Secured2 { ... });

var client3 = new JsonServiceClient(service3BaseUrl) { BearerToken = jwtToken };
var response = client3.Get(new Secured3 { ... });
```

Tokens are returned in the Secure HttpOnly **ss-tok** Cookie, accessible from the `GetTokenCookie()` 
extension method as seen above.

The default behavior of `ConvertSessionToToken` is to remove the Current Session from the Auth Server 
which will prevent access to protected Services using our previously Authenticated Session. 
If you still want to preserve your existing Session you can indicate this with:

```csharp
var tokenResponse = client.Send(new ConvertSessionToToken { PreserveSession = true });
```

For cases where you don't have access to HTTP Client Cookies you can use the new opt-in `IncludeJwtInConvertSessionToTokenResponse` option on `JwtAuthProvider` to also include the JWT in `AccessToken` property of `ConvertSessionToTokenResponse` Responses which are otherwise only available in the `ss-tok` Cookie.

## Ajax Clients

Using Cookies is the 
[recommended way for using JWT Tokens in Web Applications](https://stormpath.com/blog/where-to-store-your-jwts-cookies-vs-html5-web-storage)
since the `HttpOnly` Cookie flag will prevent it from being accessible from JavaScript making them immune
to XSS attacks whilst the `Secure` flag will ensure that the JWT Token is only ever transmitted over HTTPS.

You can convert your Session into a Token and set the **ss-tok** Cookie in your web page by sending an Ajax 
request to `/session-to-token`, e.g:

```javascript
$.post("/session-to-token");
```

Likewise this API lets you convert Sessions created by any of the OAuth providers into a stateless JWT Token.

## Switching existing Sites to JWT

Existing sites that already have an [Authenticated Session](/auth/sessions) can convert their current server Session into a JWT Token by sending a `ConvertSessionToToken` Request DTO or an empty **POST** request to its `/session-to-token` user-defined route:

```ts
const authResponse = await client.post(new ConvertSessionToToken());
```

E.g. Single Page App can call this when their Web App is first loaded, which is ignored if the User isn't authenticated but if the Web App is loaded after 
[Signing In via an OAuth Provider](/auth/authentication-and-authorization#oauth-providers) it will convert their OAuth Authenticated Session into a 
stateless client JWT Token Cookie.

This approach is also used by the old [Angular TechStacks](https://github.com/ServiceStackApps/TechStacks) after signing in via Twitter and Github OAuth to [use JWT with a single jQuery Ajax call](https://github.com/ServiceStackApps/TechStacks/blob/78ecd5e390e585c14f616bb27b24e0072b756040/src/TechStacks/TechStacks/js/user/services.js#L30):

```javascript
$.post("/session-to-token");
```

Whilst [Gistlyn uses the Fetch API](https://github.com/ServiceStack/Gistlyn/blob/770768e7f7f6a7258ea948dbe1cee7f09b47ea8d/src/Gistlyn/src/app.tsx#L69) to convert an existing Github OAuth into a JWT Token Cookie:

```ts
fetch("/session-to-token", { method:"POST", credentials:"include" });
```

We've also upgraded [servicestack.net](https://servicestack.net) which as it uses normal Username/Password Credentials Authentication 
(i.e. instead of redirects in OAuth), it doesn't need any additional network calls as we can add the `UseTokenCookie`
option as a hidden variable in our FORM request:

```html
<form id="form-login" action="/auth/login">
    <input type="hidden" name="UseTokenCookie" value="true" />
    ...
</form>
```

Which just like `ConvertSessionToToken` returns a populated session in the **ss-tok** Cookie so now 
both [techstacks.io](https://techstacks.io) and [servicestack.net](https://servicestack.net) can maintain 
uninterrupted Sessions across multiple redeployments without a persistent Sessions cache.

## Fallback Auth and RSA Keys

You can specify multiple fallback AES Auth Keys and RSA Public Keys to allow for smooth key rotations to newer Auth Keys whilst simultaneously being able to verify JWT Tokens signed with a previous key. 

The fallback keys can be configured in code when registering the `JwtAuthProvider`:

```csharp
new JwtAuthProvider {
    AuthKey = authKey2016,
    FallbackAuthKeys = {
        authKey2015,
        authKey2014,
    },
    PrivateKey = privateKey2016,
    FallbackPublicKeys = {
        publicKey2015,
        publicKey2014,
    },
}
```

Or in [AppSettings](/appsettings):

```xml
<appSettings>
    <add key="jwt.AuthKeyBase64" value="{AuthKey2016Base64}" />
    <add key="jwt.AuthKeyBase64.1" value="{AuthKey2015Base64}" />
    <add key="jwt.AuthKeyBase64.2" value="{AuthKey2014Base64}" />

    <add key="jwt.PrivateKeyXml" value="{PrivateKey2016Xml}" />
    <add key="jwt.PublicKeyXml.1" value="{PublicKeyXml2015Xml}" />
    <add key="jwt.PublicKeyXml.2" value="{PublicKeyXml2014Xml}" />
</appSettings>
```

## Send JWTs in HTTP Params

The JWT Auth Provider can **opt-in** to accept JWT's via the Query String or HTML POST FormData with:

```csharp
new JwtAuthProvider {
    AllowInQueryString = true,
    AllowInFormData = true
}
```

This is useful for situations where it's not possible to attach the JWT in the HTTP Request Headers or `ss-tok` Cookie. 

For example if you wanted to authenticate via JWT to a real-time [Server Events stream](/server-events) from a token retrieved from a remote auth server (i.e. so the JWT Cookie isn't already configured with the SSE server) you can [call the /session-to-token API](/auth/jwt-authprovider#ajax-clients) to convert the JWT Bearer Token into a JWT Cookie which will configure it with that domain so the subsequent HTTP Requests to the SSE event stream contains the JWT cookie and establishes an authenticated session:

```ts
var client = new JsonServiceClient(BaseUrl);
client.setBearerToken(JWT);
await client.post(new ConvertSessionToToken());

var sseClient = new ServerEventsClient(BaseUrl, ["*"], {
    handlers: {
        onConnect: e => { 
            console.log(e.isAuthenticated /*true*/, e.userId, e.displayName);
        }
    }
}).start();
```

Unfortunately this wont work in `node.exe` Server Apps (or in integration tests) which doesn't support a central location for configuring domain cookies. One solution that works everywhere is to add the JWT to the `?ss-tok` query string that's used to connect to the `/event-stream` URL, e.g:

```csharp
var sseClient = new ServerEventsClient(BaseUrl, ["*"], {
    resolveStreamUrl: url => appendQueryString(url, { "ss-tok": JWT }),
    handlers: {
        onConnect: e => { 
            console.log(e.isAuthenticated /*true*/, e.userId, e.displayName);
        }
    }
}).start();
```

### Setting the JWT Token Cookie

As the TypeScript `ServerEventsClient` needs to use the browsers native EventSource class to establish the SSE connection it's not able to customize 
the HTTP Request Headers in other clients but as the client shares the same cookies with the browser you can use a JWT Token Cookie either
by Requesting to use a [JWT Token Cookie at Authentication](/auth/jwt-authprovider#request-jwt-cookie-is-set-on-authentication) or by setting the Token
Cookie on the client, [CORS permitting](/corsfeature), e.g:

```js
document.cookie = "ss-tok={Token}";
```

### JWT FormData POST

The stateless nature of JWTs makes it highly versatile to be able to use in a number of difference scenarios, e.g. it could be used to make stateless authenticated requests across different domains without JavaScript (HTTP Headers or Cookies), by embedding it in a HTML Form POST:

```html
<form action="https://remote.org/secure" method="post">
    <input type="hidden" name="ss-tok" value="{JWT}" />
    ...
</form>
```

Although as this enables cross-domain posts it should be enabled with great care.

### Runtime JWT Configuration

To allow for dynamic per request configuration as needed in Multi Tenant applications we've added a new [IRuntimeAppSettings](https://github.com/ServiceStack/ServiceStack/blob/master/src/ServiceStack.Interfaces/Configuration/IAppSettings.cs) API which can be registered in your `AppHost` to return custom per request configuration. 

E.g. this can be used to return a custom `AuthKey` that should be used to sign JWT Tokens for that request:

```csharp
container.Register<IRuntimeAppSettings>(c => new RuntimeAppSettings { 
    Settings = {
        { nameof(JwtAuthProvider.AuthKey), req => (byte[]) GetAuthKey(GetTenantId(req)) }
    }
});
```

The following `JwtAuthProvider` properties can be overridden by `IRuntimeAppSettings`:

 - `byte[]` AuthKey
 - `RSAParameters` PrivateKey
 - `RSAParameters` PublicKey
 - `List<byte[]>` FallbackAuthKeys
 - `List<RSAParameters>` FallbackPublicKeys

## Multiple Audiences

With the JWT support for issuing and validating JWT's with multiple audiences, you could for example configure the JWT Auth Provider to issue tokens allowing users to access **search** and **analytics** system functions by configuring its `Audiences` property: 

```csharp
new JwtAuthProvider {
    Audiences = { "search", "analytics" }
}
```

This will include both audiences in new JWT's as a JSON Array (if only 1 audience was configured it will continue to be embedded as a string).

When validating a JWT with multiple audiences it only needs to match a single Audience configured with the `JwtAuthProvider`, e.g given the above configuration users that authenticate with a JWT containing:

```
JWT[aud] = null           //= Valid: No Audience specified
JWT[aud] = admin          //= NOT Valid: Wrong Audience specified
JWT[aud] = [search,admin] //= Valid: Partial Audience match
```

## Adhoc JWT APIs

You can retrieve the JWT Token string from the current `IRequest` with:
 
```csharp
string jwt = req.GetJwtToken();
```
 
You can manually convert JWT Tokens into User Sessions with:
 
```csharp
var userSession = JwtAuthProviderReader.CreateSessionFromJwt(base.Request);
```
 
Which is essentially a shorthand for:
 
```csharp
var jwtProvider = AuthenticateService.GetJwtAuthProvider();
var userSession = jwtProvider.ConvertJwtToSession(base.Request, req.GetJwtToken());
```

### Creating JWT Tokens Manually

You can create a custom JWT Token that encapsulates an Authenticated User Session by using JwtAuthProvider's static APIs
to create the JWT Header, JWT Payload then sign and authenticate the token using the configured signing keys in order to 
make authenticated Requests to any remote AppHost configured with the same JwtAuthProvider configuration, e.g:

```csharp
var jwtProvider = new JwtAuthProvider { ... };

var header = JwtAuthProvider.CreateJwtHeader(jwtProvider.HashAlgorithm);
var body = JwtAuthProvider.CreateJwtPayload(new AuthUserSession
    {
        UserAuthId = "1",
        DisplayName = "Test",
        Email = "as@if.com",
        IsAuthenticated = true,
    },
    issuer: jwtProvider.Issuer,
    expireIn: jwtProvider.ExpireTokensIn,
    audience: new[]{ jwtProvider.Audience },
    roles: new[] {"TheRole"},
    permissions: new[] {"ThePermission"});

var jwtToken = JwtAuthProvider.CreateJwt(header, body, jwtProvider.GetHashAlgorithm());
```

The generated JWT Token can then be [used to make Authenticated Requests](#sending-jwt-with-service-clients) 
to any Server configured with the same JwtAuthProvider configuration that the JWT Token was created with, e.g:

```csharp
var client = new JsonServiceClient(baseUrl);
client.SetTokenCookie(jwtToken);

var response = client.Get(new Secured { ... });
```

### Validating JWT Manually

The `IsValidJwt()` and `GetValidJwtPayload()` APIs lets you validate and inspect the contents of a JWT stand-alone, i.e. outside the context of a Request. Given an invalid `expiredJwt` and a `validJwt` you can test the validity and inspect the contents of each with:

```csharp
var jwtProvider = AuthenticateService.GetJwtAuthProvider();

jwtProvider.IsValidJwt(expiredJwt);          //= false
jwtProvider.GetValidJwtPayload(expiredJwt);  //= null


jwtProvider.IsValidJwt(validJwt);            //= true
JsonObject payload = jwtProvider.GetValidJwtPayload(validJwt);

var userId = payload["sub"];
```

## Large Profile Image Handling

As [high res profile images in Microsoft Graph Auth](/releases/v6.html#microsoft-graph-auth) doesn't return CDN URIs to the users profile image that can be referenced within Apps directly, it pushes the burden of profile image management down to every authenticating App server, which to maintain their **statelessness**, means converting into a [Data URI](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/Data_URIs), except as it typically returns the high-res image JPEG which far exceeds the maximum **4kb** limit of cookies, it requires resizing in order to make fit (otherwise the JWT Cookie is ignored and Authentication will fail). 

Unfortunately as [Image Resizing is unreliable in Linux](/releases/v6.html#state-of-imaging-on-linux) we've had to adopt an alternative solution that's able to display a users high-res photo whilst still keeping our App server stateless by creating a new [ImagesHandler](https://github.com/ServiceStack/ServiceStack/blob/main/ServiceStack/src/ServiceStack/ImagesHandler.cs) that the JWT AuthProvider calls `RewriteImageUri()` on to replace any large profile URLs with a link to its `/auth-profiles/{MD5}.jpg` - a URL it also handles serving the original high-res image back to.

This is the solution `AuthFeature` uses by default, pre-configured with:

```csharp
new AuthFeature {
    ProfileImages = new ImagesHandler("/auth-profiles", fallback: Svg.GetStaticContent(Svg.Icons.DefaultProfile))
}
```

Where if using a custom [SavePhotoSize](https://github.com/NetCoreTemplates/blazor-wasm/blob/main/MyApp/appsettings.Development.json#L30) will be resized using Microsoft Graph APIs, if the resized image size still exceeds the max allowable size in JWT Cookies it's swapped out for a URL reference to the image which ImageHandler stores in memory. The trade-off of this default is when your Docker App is re-deployed, whilst their stateless authentication keeps them authenticated, the original high-res photo saved in ImageHandler's memory will be lost, which will be replaced with the fallback `Svg.Icons.DefaultProfile` image.

Using an MD5 hash does allow us to maintain URLs that's both predictable in that it will result in the same hash after every sign in, while also preventing information leakage that using a predictable User Id would do. A client-only solution that could retain their avatar across deployments is saving it to localStorage however that pushes the burden down to every client App using your APIs, which could be manageable if you control all of them.

#### Persistent Large Profile Image Handling

For a persistent solution that retains profile images across deployments you can use `PersistentImagesHandler` with the VFS Provider and path for profile images to be written to, e.g:

```csharp
new AuthFeature {
    ProfileImages = new PersistentImagesHandler("/auth-profiles", Svg.GetStaticContent(Svg.Icons.DefaultProfile),
        appHost.VirtualFiles, "/App_Data/auth-profiles")
}
```

When using the default `FileSystemVirtualFiles` VFS provider this would require configuring your Docker App with a persistent `/App_Data` Volume, otherwise using one of the other [Virtual Files Providers](/virtual-file-system) like `S3VirtualFiles` or `AzureBlobVirtualFiles` may be the more preferable solution to keep your Docker Apps stateless.

## Refresh Token Cookies supported in all Service Clients

::include jwt-service-clients.md::

## JWT Configuration
~~~~
The JWT Auth Provider provides the following options to customize its behavior: 

```csharp
class JwtAuthProviderReader
{
    // The RSA Bit Key Length to use
    static RsaKeyLengths UseRsaKeyLength = RsaKeyLengths.Bit2048

    // Different HMAC Algorithms supported
    Dictionary<string, Func<byte[], byte[], byte[]>> HmacAlgorithms

    // Different RSA Signing Algorithms supported
    Dictionary<string, Func<RSAParameters, byte[], byte[]>> RsaSignAlgorithms
    Dictionary<string, Func<RSAParameters, byte[], byte[], bool>> RsaVerifyAlgorithms

    // Whether to only allow access via API Key from a secure connection. (default true)
    bool RequireSecureConnection

    // Run custom filter after JWT Header is created
    Action<JsonObject, IAuthSession> CreateHeaderFilter

    // Run custom filter after JWT Payload is created
    Action<JsonObject, IAuthSession> CreatePayloadFilter

    // Run custom filter after session is restored from a JWT Token
    Action<IAuthSession, JsonObject, IRequest> PopulateSessionFilter

    // Whether to encrypt JWE Payload (default false). 
    // Uses RSA-OAEP for Key Encryption and AES/128/CBC HMAC SHA256 for Content Encryption
    bool EncryptPayload

    // Which Hash Algorithm should be used to sign the JWT Token. (default HS256)
    string HashAlgorithm

    // Whether to only allow processing of JWT Tokens using the configured HashAlgorithm.
    bool RequireHashAlgorithm

    // The Issuer to embed in the token. (default ssjwt)
    string Issuer

    // The Audience to embed in the token. (default null)
    string Audience

    // What Id to use to identify the Key used to sign the token. (3 chars of Base64 Key)
    string KeyId

    // The AuthKey used to sign the JWT Token
    byte[] AuthKey
    // Convenient overload to initialize AuthKey with Base64 string
    string AuthKeyBase64

    // The RSA Private Key used to Sign the JWT Token when RSA is used
    RSAParameters? PrivateKey
    // Convenient overload to initialize the Private Key via exported XML
    string PrivateKeyXml

    // The RSA Public Key used to Verify the JWT Token when RSA is used
    RSAParameters? PublicKey

    // Convenient overload to initialize the Public Key via exported XML
    string PublicKeyXml

    // How long should JWT Tokens be valid for. (default 14 days)
    TimeSpan ExpireTokensIn

    // Convenient overload to initialize ExpireTokensIn with an Integer
    int ExpireTokensInDays

    // How long should JWT Refresh Tokens be valid for. (default 365 days)
    TimeSpan ExpireRefreshTokensIn 

    // Allow custom logic to invalidate JWT Tokens
    Func<JsonObject, IRequest, bool> ValidateToken

    // Allow custom logic to invalidate Refresh Tokens
    Func<JsonObject, IRequest, bool> ValidateRefreshToken

    // Whether to invalidate all JWT Tokens issued before a specified date.
    DateTime? InvalidateTokensIssuedBefore

    // Whether to populate the Bearer Token in the AuthenticateResponse
    bool SetBearerTokenOnAuthenticateResponse

    // Modify the registration of ConvertSessionToToken Service
    Dictionary<Type, string[]> ServiceRoutes
}
```

## Further Examples

More examples of both the new API Key and JWT Auth Providers are available in 
[StatelessAuthTests](https://github.com/ServiceStack/ServiceStack/blob/master/tests/ServiceStack.Server.Tests/Auth/StatelessAuthTests.cs)
and [JWT Token Cookie Example](https://github.com/ServiceStack/ServiceStack/blob/master/tests/ServiceStack.WebHost.Endpoints.Tests/UseCases/JwtAuthProviderTests.cs#L235).


# API Key Auth Provider
Source: https://docs.servicestack.net/auth/api-key-authprovider

The API Key Auth Provider provides an alternative method for allowing external 3rd Parties access to 
your protected Services without needing to specify a password. API Keys is the preferred approach for 
many well-known public API providers used in system-to-system scenarios for several reasons:

 - **Simple** - It integrates easily with existing HTTP Auth functionality
 - **Independent from Password** - Limits exposure to the much more sensitive master user passwords that 
 should ideally never be stored in plain-text. Resetting User's Password or password reset strategies 
 wont invalidate existing systems configured to use API Keys
 - **Entropy** - API Keys are typically much more secure than most normal User Passwords. The configurable 
default has **24 bytes** of entropy (Guids have 16 bytes) generated from a secure random number generator 
that encodes to **32 chars** using URL-safe Base64 (Same as Stripe)
 - **Performance** - Thanks to their much greater entropy and independence from user-chosen passwords,
 API Keys are validated as fast as possible using a datastore Index. This is contrast to validating hashed 
 user passwords which as a goal require usage of slower and more computationally expensive algorithms to 
 try make brute force attacks infeasible

Like most ServiceStack providers the new API Key Auth Provider is simple to use, integrates seamlessly with
ServiceStack existing Auth model and includes Typed end-to-end client/server support. 

<lite-youtube class="w-full mx-4 my-4" width="560" height="315" videoid="NTCUT7atoLo" style="background-image: url('https://img.youtube.com/vi/NTCUT7atoLo/maxresdefault.jpg')"></lite-youtube>

For familiarity and utility we've modeled our implementation around Stripe's API Key functionality whilst
sharing many of the benefits of ServiceStack's Auth Providers:

## Simple and Integrated

To register `ApiKeyAuthProvider` add it to the `AuthFeature` list of Auth Providers:

```csharp
Plugins.Add(new AuthFeature(...,
    new IAuthProvider[] {
        new ApiKeyAuthProvider(AppSettings),
        new CredentialsAuthProvider(AppSettings),
        //...
    }
));
```

Or for Apps utilizing encapsulated [Modular Startup](/modular-startup) configuration blocks:

```csharp
[assembly: HostingStartup(typeof(MyApp.ConfigureAuth))]

public class ConfigureAuth : IHostingStartup
{
    public void Configure(IWebHostBuilder builder) => builder
        .ConfigureAppHost(appHost => {
            appHost.Plugins.Add(new AuthFeature(() => new AuthUserSession(),
                new IAuthProvider[] {
                    new ApiKeyAuthProvider(appHost.AppSettings),
                    new CredentialsAuthProvider(appHost.AppSettings),
                    //...
                }));
        });
}
```

The `ApiKeyAuthProvider` works similarly to the other ServiceStack `IAuthWithRequest` providers where a 
successful API Key initializes the current `IRequest` with the user's Authenticated Session. It also adds the 
[ApiKey](https://github.com/ServiceStack/ServiceStack/blob/c4a8f9741e496793d949c09cecb84e84fca86686/src/ServiceStack/Auth/ApiKeyAuthProvider.cs#L31) POCO Model to the request which can be accessed with:

```csharp
ApiKey apiKey = req.GetApiKey();
```

The `ApiKey` can be later inspected throughout the [request pipeline](/order-of-operations) to determine which API Key, Type and Environment was used.

## Interoperable

Using existing HTTP Functionality makes it simple and interoperable to use with any HTTP Client even command-line clients like curl where API Keys can be specified in the **Username** of HTTP Basic Auth:

:::sh
curl https://api.stripe.com/v1/charges -u yDOr26HsxyhpuRB3qbG07qfCmDhqutnA:
:::

Or as a HTTP Bearer Token in the **Authorization** HTTP Request Header:

:::sh
curl https://api.stripe.com/v1/charges -H "Authorization: Bearer yDOr26HsxyhpuRB3qbG07qfCmDhqutnA"
:::
 
Both of these methods are built into most HTTP Clients. Here are a few different ways which you can send them using ServiceStack's [.NET Service Clients](/csharp-client):

```csharp
var client = new JsonApiClient(baseUrl) {
    Credentials = new NetworkCredential(apiKey, "")
};

var client = new JsonHttpClient(baseUrl) {
    BearerToken = apiKey
};
```

Or using the [HTTP Utils](/http-utils) extension methods:

```csharp
var response = baseUrl.CombineWith("/secured").GetStringFromUrl(
    requestFilter: req => req.AddBasicAuth(apiKey, ""));
    
var response = await "https://example.org/secured".GetJsonFromUrlAsync(
    requestFilter: req => req.AddBearerToken(apiKey));
```

## Sending API Key in Request DTOs

Similar to the `IHasSessionId` interface Request DTOs can also implement `IHasBearerToken` to send Bearer Tokens, e.g:

```csharp
public class Secure : IHasBearerToken
{
    public string BearerToken { get; set; }
    public string Name { get; set; }
}

var response = client.Get(new Secure { BearerToken = apiKey, Name = "World" });
```

Alternatively you can set the `BearerToken` property on the Service Client once where it will automatically populate all Request DTOs 
that implement `IHasBearerToken`, e.g:

```csharp
client.BearerToken = jwtToken;

var response = client.Get(new Secure { Name = "World" });
```

## Supported Auth Repositories

The necessary functionality to support API Keys has been implemented in the following supported Auth Repositories:

 - `OrmLiteAuthRepository` - Supporting [most major RDBMS](/ormlite/#ormlite-rdbms-providers)
 - `RedisAuthRepository` - Uses Redis back-end data store
 - `DynamoDbAuthRepository` - Uses AWS DynamoDB data store
 - `MongoDbAuthRepository` - Uses MongoDB data store
 - `InMemoryAuthRepository` - Uses InMemory Auth Repository

And requires no additional configuration as it just utilizes the existing registered `IAuthRepository`.

## Multiple API Key Types and Environments

You can specify any number of different Key Types for use in multiple environments for each user. Keys are 
generated upon User Registration where it generates both a **live** and **test** key for the **secret** 
Key Type by default. To also create both a "secret" and "publishable" API Key, configure it with:

```csharp
Plugins.Add(new AuthFeature(...,
    new IAuthProvider[] {
        new ApiKeyAuthProvider(AppSettings) {
            KeyTypes = new[] { "secret", "publishable" },
        }
    }
));
```

If preferred, any of the API Key Provider options can instead be specified in 
[App Settings](/appsettings) following the `apikey.{PropertyName}` format, e.g:

```xml
<add key="apikey.KeyTypes" value="secret,publishable" />
```

## Cached API Key Sessions

You can reduce the number of I/O Requests and improve the performance of API Key Auth Provider Requests by 
specifying a `SessionCacheDuration` to temporarily store the Authenticated UserSession against the API Key
which will reduce subsequent API Key requests down to 1 DB call to fetch and validate the API Key + 1 Cache Hit 
to restore the User's Session which if you're using the default in-memory Cache will mean it only requires 1 I/O 
call for the DB request.

This can be enabled with:

```csharp
Plugins.Add(new AuthFeature(...,
    new IAuthProvider[] {
        new ApiKeyAuthProvider(AppSettings) {
            SessionCacheDuration = TimeSpan.FromMinutes(10),
        }
    }));
```

## Multitenancy

Thanks to the ServiceStack's trivial support for enabling 
[Multitenancy](/multitenancy), the minimal configuration required to register and API Key Auth Provider that persists to a **LiveDb** SQL Server database and also allows Services called with an Test API Key to query the alternative **TestDb** database instead, is just:

```csharp
class AppHost : AppSelfHostBase
{
    public AppHost() : base("API Key Multitenancy Example", typeof(AppHost).Assembly) { }

    public override void Configure(Container container)
    {
        //Create and register an OrmLite DB Factory configured to use Live DB by default 
        var dbFactory = new OrmLiteConnectionFactory(
            AppSettings.GetString("LiveDb"), SqlServerDialect.Provider);

        container.Register<IDbConnectionFactory>(dbFactory);

        // Register a "TestDb" Named Connection 
        dbFactory.RegisterConnection("TestDb", 
            AppSettings.GetString("TestDb"), SqlServerDialect.Provider);

        //Tell ServiceStack you want to persist User Auth Info in SQL Server
        container.Register<IAuthRepository>(c => new OrmLiteAuthRepository(dbFactory));
        
        //Register the AuthFeature with the API Key Auth Provider 
        Plugins.Add(new AuthFeature(() => new AuthUserSession(),
            new IAuthProvider[] {
                new ApiKeyAuthProvider(AppSettings)
            });
    }
    
    public override IDbConnection GetDbConnection(IRequest req = null)
    {
        //If an API Test Key was used return DB connection to TestDb instead: 
        return req.GetApiKey()?.Environment == "test"
            ? TryResolve<IDbConnectionFactory>().OpenDbConnection("TestDb")
            : base.GetDbConnection(req);
    }
}
```

Now whenever a Test API Key was used to call an Authenticated Service, all `base.Db` Queries or AutoQuery Services will query **TestDb** instead.

## API Key Defaults

The API Key Auth Provider has several options to customize its behavior with all but delegate Filters being able to be specified in AppSettings as well:

```csharp
new ApiKeyAuthProvider 
{
    // Whether to only permit access via API Key from a secure connection. (default true)
    public bool RequireSecureConnection { get; set; }

    // Generate different keys for different environments. (default live,test)
    public string[] Environments { get; set; }

    // Different types of Keys each user can have. (default secret)
    public string[] KeyTypes { get; set; }

    // How much entropy should the generated keys have. (default 24)
    public int KeySizeBytes { get; set; }

    /// Whether to automatically expire keys. (default no expiry)
    public TimeSpan? ExpireKeysAfter { get; set; }

    // Automatically create ApiKey Table for Auth Repositories which need it. (true)
    public bool InitSchema { get; set; }

    // Change how API Key is generated
    public CreateApiKeyDelegate GenerateApiKey { get; set; }

    // Run custom filter after API Key is created
    public Action<ApiKey> CreateApiKeyFilter { get; set; }

    // Cache the User Session so it can be reused between subsequent API Key Requests
    public TimeSpan? SessionCacheDuration { get; set; }

    // Whether to allow API Keys in 'apikey' QueryString or FormData (e.g. `?apikey={APIKEY}`) 
    public bool AllowInHttpParams { get; set; }
}
```

## IManageApiKeys API

Should you need to, you can access API Keys from the Auth Repository directly through the following interface:

```csharp
public interface IManageApiKeys
{
    void InitApiKeySchema();

    bool ApiKeyExists(string apiKey);

    ApiKey GetApiKey(string apiKey);

    List<ApiKey> GetUserApiKeys(string userId);

    void StoreAll(IEnumerable<ApiKey> apiKeys);
}
```

::: info
This interface also defines what's required in order to implement API Keys support on a Custom AuthRepository
:::

For Auth Repositories which implement it, you can access the interface by resolving `IAuthRepository` from the IOC and casting it to the above interface, e.g:

```csharp
var apiRepo = (IManageApiKeys)HostContext.TryResolve<IAuthRepository>();
var apiKeys = apiRepo.GetUserApiKeys(session.UserAuthId);
```

## Built-in API Key Services

To give end-users access to their keys the API Key Auth Provider enables 2 Services: the `GetApiKeys` Service to return all valid User API Keys for the specified environment:

```csharp
//GET /apikeys/live
var response = client.Get(new GetApiKeys { Environment = "live" }); 
response.Results.PrintDump(); //User's "live" API Keys 
```

And the `RegenerateApiKeys` Service to invalidate all current API Keys and generate new ones for the specified environment:

```csharp
//POST /apikeys/regenerate/live
var response = client.Post(new RegenerateApiKeys { Environment = "live" }); 
response.Results.PrintDump(); //User's new "live" API Keys 
```

You can modify which built-in Services you want registered, or modify the custom routes to where you want them to be available by modifying the `ServiceRoutes` collection. E.g. you can prevent it from registering any Services by setting `ServiceRoutes` to an empty collection:

```csharp
new ApiKeyAuthProvider { ServiceRoutes = new Dictionary<Type, string[]>() }
```

## Generating API Keys for Existing Users

Whilst the API Key Auth Provider will automatically generate API Keys for new users, if you also want to add API Keys for existing users you'll need to use the `ApiKeyAuthProvider` to generate new keys for all users that don't have keys. 

Here's a script you can use when using an `OrmLiteAuthRepository` to generate API Keys for all users with missing API Keys on startup:

```csharp
public class ConfigureAuth : IHostingStartup
{
    public void Configure(IWebHostBuilder builder) => builder
        .ConfigureAppHost(appHost =>
        {
            appHost.Plugins.Add(new AuthFeature(() => new AuthUserSession(),
                new IAuthProvider[] {
                    new ApiKeyAuthProvider(appHost.AppSettings)
                }));
        }, afterAppHostInit: appHost => {
            var authProvider = (ApiKeyAuthProvider)
                AuthenticateService.GetAuthProvider(ApiKeyAuthProvider.Name);
            
            using var db = appHost.TryResolve<IDbConnectionFactory>().Open();
            var userWithKeysIds = db.Column<string>(db.From<ApiKey>()
                .SelectDistinct(x => x.UserAuthId)).Map(int.Parse);

            var userIdsMissingKeys = db.Column<string>(db.From<UserAuth>() // Use custom UserAuth if configured
                .Where(x => userWithKeysIds.Count == 0 || !userWithKeysIds.Contains(x.Id))
                .Select(x => x.Id));

            foreach (var userId in userIdsMissingKeys)
            {
                var apiKeys = authProvider.GenerateNewApiKeys(userId);
                authRepo.StoreAll(apiKeys);
            }
        });
}
```

:::info
If using another Auth Repository backend this script will need to be modified to fetch the userIds for all users missing API Keys
:::

## .NET Framework Example

Older platforms can register Startup initialization logic using the `HostContext.ConfigureAppHost()` singleton: 

```csharp
HostContext.ConfigureAppHost(afterAppHostInit:appHost => ...);
```

Or adding to `AfterInitCallbacks` in their `AppHost.Configure()`, e.g:

```csharp
public override void Configure(Container container)
{
    AfterInitCallbacks.Add(appHost => ...);
}
```


# Sign in with Apple Auth Provider
Source: https://docs.servicestack.net/auth/signin-with-apple

ServiceStack Sign In with Apple Auth Provider docs & Integration docs from [github.com/NetCoreApps/AppleSignIn](https://github.com/NetCoreApps/AppleSignIn).

![](/img/pages/dev/web-signin-with-apple-login.png)

## Sign In with Apple Requirements

 - Membership **Team ID** from [developer.apple.com/account/#/membership/](https://developer.apple.com/account/#/membership/)
 - Create & configure **App ID** from [developer.apple.com/account/resources/identifiers/list](https://developer.apple.com/account/resources/identifiers/list)
 - Use **App ID** to create & configure **Service ID** from [developer.apple.com/account/resources/identifiers/list/serviceId](https://developer.apple.com/account/resources/identifiers/list/serviceId)
 - Use **App ID** to create & configure **Private Key** from [developer.apple.com/account/resources/authkeys/list](https://developer.apple.com/account/resources/authkeys/list)

### App Requirements Walkthrough

Okta has a [good walkthrough explaining Sign In with Apple](https://developer.okta.com/blog/2019/06/04/what-the-heck-is-sign-in-with-apple) and steps required to create the above resources.

Note: Service ID must be configured with non-localhost trusted domain and HTTPS callback URL, for development you can use:
 - Domain: `dev.servicestack.com`
 - Callback URL: `https://dev.servicestack.com:5001/auth/apple` 

See docs on [Configure localhost development dev certificate](/netcore-localhost-cert) for instructions & info for being able to use a single `local.servicestack.com` or `dev.servicestack.com` local DNS names to support local development of all platforms.

### Apple Services ID configuration

If you also need to support Android you'll also need to register the `https://dev.servicestack.com:5001/auth/apple?ReturnUrl=android:com.servicestack.auth` URL will as a valid Callback URL in your Apple **Services ID** configuration.

## Getting Started

As the elliptic curve algorithms required to integrate with Sign In with Apple requires .NET Core 3 APIs the `AppleAuthProvider` is implemented in the **ServiceStack.Extensions** NuGet Package.

### Create project with preferred Auth Configuration

A quick way to can create a working project from scratch with your preferred configuration using the [mix tool](/mix-tool), e.g: 

```bash
mkdir web && cd web
x mix init auth-ext auth-db sqlite
```

This creates an empty project, with Auth Enabled, adds the **ServiceStack.Extensions** NuGet package, registers OrmLite, SQLite and the `OrmLiteAuthRepository`.

Copy your Apple **Private Key** to your Apps **Content Folder** then configure your OAuth providers in **appsettings.json**:

```json
{
  "oauth.apple.RedirectUrl": "https://dev.servicestack.com:5001/",
  "oauth.apple.CallbackUrl": "https://dev.servicestack.com:5001/auth/apple",
  "oauth.apple.TeamId": "{Team ID}",
  "oauth.apple.ClientId": "{Service ID}",
  "oauth.apple.BundleId": "{Bundle ID}",
  "oauth.apple.KeyId": "{Private KeyId}",
  "oauth.apple.KeyPath": "AuthKey_{Private KeyId}.p8",
  "jwt.AuthKeyBase64": "{Base64 JWT Auth Key}"
}
```

::: info
See JWT docs for how to [Generate a new Auth Key](/auth/jwt-authprovider#generate-new-auth-key)
:::

When needing to support Mobile or Desktop Apps using OAuth Providers like Sign In with Apple, we recommend using it in combination with the [JWT Auth Provider](/auth/jwt-authprovider) with `UseTokenCookie` enabled so the Authorization is returned in a stateless JWT Token that can be persisted for optimal Authentication across App restarts, e.g:

```csharp
Plugins.Add(new AuthFeature(() => new CustomUserSession(),
    new IAuthProvider[] {
        new JwtAuthProvider(AppSettings) {
            UseTokenCookie = true,
        },
        new AppleAuthProvider(AppSettings)
            .Use(AppleAuthFeature.FlutterSignInWithApple), 
    }));
```

### Clone working Client & Server Project 

For a working example you can **clone** or **fork** the [/NetCoreApps/AppleSignIn](https://github.com/NetCoreApps/AppleSignIn) repo or alternatively download the latest master `.zip` with:

:::sh
x download NetCoreApps/AppleSignIn
:::

Then after updating **appsettings.json** with your iOS App's configuration, copying your Private Key into the `web` Content Folder you're all set to run your App:

:::sh
dotnet run
:::

### Android Support

To support Android we recommend using `dev.servicestack.com` which resolves to the `10.0.2.2` special IP in the Android Emulator that maps to `127.0.0.1` on your Host OS. To also be able to use it during development you'll need to add an entry in your OS's `hosts` file
(e.g. `%SystemRoot%\System32\drivers\etc\hosts` for Windows or `/system/etc/hosts` on macOS/Linux):

```
127.0.0.1       dev.servicestack.com
```

If you don't need to support android you can use `local.servicestack.com` instead which resolves to `127.0.0.1`, please see [configuring localhost development dev certificate](/netcore-localhost-cert) for more info.

Then you can view your App using the non-localhost domain name:

 - https://dev.servicestack.com:5001/

You can then use the [Embedded Login Page](/auth/authentication-and-authorization#embedded-login-page-fallback) which renders the Sign In button for each of the registered OAuth providers in your `AuthFeature`:

 - https://dev.servicestack.com:5001/login

Clicking on **Sign in with Apple** button should let you Sign In with Apple. After successfully signing in you can view the `AllUsersInfo` Service to view a dump of all User Sessions & User Auth Info stored in the registered RDBMS:

 - https://dev.servicestack.com:5001/users

## Flutter iOS & Android App

A reference client Flutter iOS & Android App showcasing integration with Sign In with Apple is available at [/flutter/auth](https://github.com/NetCoreApps/AppleSignIn/tree/master/flutter/auth).

![](/img/pages/dev/android-flutter-auth.png)

The first task the App does is to create an instance of the `IServiceClient` it should use using the recommended `ClientFactory` API which in combination with the conditional import below returns the appropriate configured Service Client implementation for the platform it's running on, for iOS & Android it uses the native `JsonServiceClient`:

```dart
import 'package:servicestack/web_client.dart' if (dart.library.io) 'package:servicestack/client.dart';
//...

AppState(client: kDebugMode
  ? ClientFactory.createWith(ClientOptions(baseUrl:'https://dev.servicestack.com:5001', ignoreCert:true))
  : ClientFactory.create("https://prod.app"))
```

Using a constant like `kDebugMode` ensures that create Service Clients that ignore SSL Certificate errors are stripped from production builds. 

### sign_in_with_apple package

To support both iOS and Android we're utilizing the [sign_in_with_apple](https://pub.dev/packages/sign_in_with_apple) `SignInWithAppleButton` which takes care of invoking iOS's native Sign In with Apple behavior as well as enabling support for Android by wrapping an OAuth Web Flow in a WebView. Both approaches, if successful will result in an Authenticated IdentityToken which you can use to Authenticate with your ServiceStack instance to establish an Authenticated session.

The `SignInWithAppleButton` functions as a normal button which is placed in your Widgets `build()` method where you want the UI Button to appear, in this case it'll render the **Sign in with Apple** button if the user is not Authenticated otherwise it renders a **Sign Out** `FlatButton`:

```dart
state.isAuthenticated
  ? FlatButton(onPressed: state.signOut, child: Text('Sign Out'))
  : SignInWithAppleButton(onPressed: () async { await handleSignIn(state); })
```

When either is pressed it invokes its `onPressed` event where the Apple Sign in functionality is initiated,
within the `handleSignIn` implementation which reflects the behavior of the different platforms with Android 
using the OAuth Web Flow to authenticate with its ReturnUrl needing the Android's App Id that it should redirect to.

The native integration in iOS is more streamlined with iOS handling the Auth flow with Apple's servers:

```dart
var clientID = "net.servicestack.myappid";
var redirect = "https://dev.servicestack.com:5001/auth/apple?ReturnUrl=android:com.servicestack.auth";
var scopes = [ AppleIDAuthorizationScopes.email, AppleIDAuthorizationScopes.fullName ];
final credentials = Platform.isAndroid
  ? await SignInWithApple.getAppleIDCredential(scopes:scopes,
      webAuthenticationOptions:WebAuthenticationOptions(clientId:clientID,redirectUri:Uri.parse(redirect)))
  : await SignInWithApple.getAppleIDCredential(scopes:scopes);
```

### New User Registration

When a user signs into your App the first time they'll be presented with the option on what name they want to use and whether or not they want to provide their own email or use Apple's hidden email forwarding service:

![](/img/pages/dev/ios-flutter-sign-in-with-apple-new-user.png)

Subsequent re-authentication attempts in iOS are more seamless & effortless for users whilst Android users will still need to go through the OAuth web flow:

![](/img/pages/dev/android-flutter-auth-request.png)

If Sign in is successful it will return the identity token which we can use to Authenticate against our remote ServiceStack instance. Importantly Apple only returns the Users name on its initial sign in which we'll
need to include in our `Authenticate` request in order for it to be used when creating the new user account.
The same code can also be used to re-authenticate existing users:

```dart
// Sign in with Apple success!
var idToken = credentials.identityToken;

// Authenticate with server using idToken & convert into stateless JWT Cookie + persistent auth token
var response = await state.client.post(Authenticate()
    ..provider = 'apple'
    ..accessToken = idToken, args: {
        'authorizationCode': credentials.authorizationCode,
        'givenName': credentials.givenName,
        'familyName': credentials.familyName,
    }); // JwtAuthProvider.UseTokenCookie returns session as JWT

state.saveAuth(response);
```

### Persistent Authenticated Sessions

We recommend using JWT to store authenticated sessions as it allows using a single approach to support multiple OAuth providers, inc. Username/Password Credentials Auth if you want your App to support it, it's also the fastest & most resilient Auth Provider which requires no I/O to validate & no server state as it's all encapsulated within the stateless client JWT token.

As all DTOs are JSON Serializable, the easiest way to persist Authentication is to save the `AuthenticateResponse` 
(which contains both JWT Bearer & Refresh Tokens) in Flutter's `SharedPreferences` abstraction which has implementations 
available in all its supported platforms. 

Populating a Service Client with `bearerToken` and `refreshToken` enables it to make authenticated requests which is 
done on successful Sign in requests and when the App is initialized which is also what allows for persistent authentication across App restarts. 

```dart
class AppState extends ChangeNotifier {
  SharedPreferences prefs;
  IServiceClient client;
  AuthenticateResponse auth;
  bool hasInit = false;

  bool get isAuthenticated => auth != null;

  AppState({this.client});

  Future<AppState> init() async {
    prefs = await SharedPreferences.getInstance();
    var json = prefs.getString('auth');
    auth = json != null ? AuthenticateResponse.fromJson(jsonDecode(json)) : null;

    initClientAuth(client, auth);

    if (auth != null && !await checkIsAuthenticated(client)) {
      auth = client.bearerToken = client.refreshToken = null;
      prefs.remove('auth');
    }
    hasInit = true;
    return this;
  }

  void signOut() => saveAuth(null);

  void saveAuth(AuthenticateResponse response) {
    auth = response;
    if (auth != null) {
      var json = jsonEncode(auth.toJson());
      prefs.setString('auth', json);
    } else {
      prefs.remove('auth');
    }
    initClientAuth(client, auth);
    notifyListeners();
  }
}

void initClientAuth(IServiceClient client, AuthenticateResponse auth) {
  client.bearerToken = auth?.bearerToken;
  client.refreshToken = auth?.refreshToken;
  if (auth == null) {
    client.clearCookies();
  }
}

Future<bool> checkIsAuthenticated(IServiceClient client) async {
  try {
    await client.post(Authenticate());
    return true;
  } catch (e) {
    return false;
  }
}
```

When signing out we also want to remove its cookies to clear its `ss-tok` authenticated JWT Cookie inc. any other user identifying cookies.

The call to `notifyListeners()` is part of Flutter's `ChangeNotifier` 
[Simple app state management](https://flutter.dev/docs/development/data-and-backend/state-mgmt/simple) solution which notifies widgets using it of state changes, triggering re-rendering of its UI.

### Authenticated API Requests

To test Authentication the App makes a call to `HelloSecure` Secured C# ServiceStack Service that validates Auth only
access using the `[ValidateIsAuthenticated]` [declarative validation attribute](/declarative-validation):

```csharp
[ValidateIsAuthenticated]
[Route("/hello/secure")]
[Route("/hello/secure/{Name}")]
public class HelloSecure : IReturn<HelloResponse>
{
    public string Name { get; set; }
}

public class HelloResponse
{
    public string Result { get; set; }
}

public class MyServices : Service
{
    public object Any(HelloSecure request) => 
        new HelloResponse { Result = $"Secure {request.Name}!" };
}
```

Which uses the Dart client DTOs generated using the [Dart ServiceStack Reference](/dart-add-servicestack-reference) feature to perform its Typed API Request:

```dart
  floatingActionButton: FloatingActionButton(
    onPressed: _callService,
    tooltip: 'HTTP API Example',
    child: Icon(Icons.play_arrow),
  ), // This trailing comma makes auto-formatting nicer for build methods.

//...

  Future<void> _callService() async {
    try {
      var client = Provider.of<AppState>(context, listen: false).client;
      var response = await client.get(HelloSecure()..name = "Flutter");
      setState(() {
        result = response.result;
      });
    } on WebServiceException catch (e) {
      setState(() {
        result = "${e.statusCode}: ${e.message}";
      });
    }
  }
```

Which if authenticated will update the UI with API Response for both iOS:

![](/img/pages/dev/ios-flutter-auth-request.jpeg)

and Android:

![](/img/pages/dev/android-flutter-secure.png)


Or fail with an `Unauthorized: Not Authenticated` error if the user is not Signed in.

### Resetting App Sign in

As the Sign in behavior is different for new & existing users you may need to find yourself needing to retest the new user workflow which you can do by removing your existing relationship to your App by signing into your Apple Id:

  - [appleid.apple.com](https://appleid.apple.com)

Then under **Security** click on **Manage apps & websites...**

![](/img/pages/dev/appleid-manage-signin.png)

Which will let you delete your existing user id and relationship with existing Apps you've signed into:

![](/img/pages/dev/appleid-reset-signin.png)

Now next time you Sign in to your App it will behave as an initial new User request complete with a new unique user id.

### Flutter Android sign_in_with_apple requirements

It's already configured in this project, but to be able to use [sign_in_with_apple](https://pub.dev/packages/sign_in_with_apple) in your own Flutter Android Apps you'll need to register this Android intent in your **AndroidManifest.xml**:

```xml
<application ...>

    <!-- Set up the Sign in with Apple activity, such that it's callable from the browser-redirect -->
    <activity
        android:name="com.aboutyou.dart_packages.sign_in_with_apple.SignInWithAppleCallback"
        android:exported="true"
        >
        <intent-filter>
            <action android:name="android.intent.action.VIEW" />
            <category android:name="android.intent.category.DEFAULT" />
            <category android:name="android.intent.category.BROWSABLE" />

            <data android:scheme="signinwithapple" />
            <data android:path="callback" />
        </intent-filter>
    </activity>
    
    <!-- Don't delete the meta-data below.
            This is used by the Flutter tool to generate GeneratedPluginRegistrant.java -->
    <meta-data
        android:name="flutterEmbedding"
        android:value="2" />

</application>
```

#### ServiceStack AppleAuthProvider configuration

This client App configuration works in combination with the Server's `AppleAuthProvider` to redirect to your Android's App intent which needs to be configured with:

```csharp
new AppleAuthProvider(AppSettings)
    .Use(AppleAuthFeature.FlutterSignInWithApple), 
```

Where it adds support for `?ReturnUrl=android:<android-package-id>` Callback URLs that your Flutter Android App needs to use.

## SwiftUI App

The [/NetCoreApps/AppleSignIn](https://github.com/NetCoreApps/AppleSignIn) repo also includes a SwiftUI iOS Example App available at [/swift/MyApp](https://github.com/NetCoreApps/AppleSignIn/tree/master/swift/MyApp) as it'll likely end up being another popular platform that will utilize **Sign in with Apple**. 

It's a good idea to checkout Apple's official docs for their recommended approach for 
[Implementing User Authentication with Sign in with Apple](https://developer.apple.com/documentation/authenticationservices/implementing_user_authentication_with_sign_in_with_apple) in Swift Apps which includes a 
sample iOS Storyboard Swift App which enlists the built-in [Authentication Services Framework](https://developer.apple.com/documentation/authenticationservices) for iOS's native Sign in feature.

For simplicity & comparison purposes we've developed an App similar to the Flutter example using
Apple's new declarative state-of-the-art [SwiftUI Framework](https://developer.apple.com/xcode/swiftui/), which like 
Flutter is a declarative Reactive UI Framework allowing you to construct your App's UI & logic in code - most of which is 
contained within [ContentView.swift](https://github.com/NetCoreApps/AppleSignIn/blob/master/swift/MyApp/MyApp/ContentView.swift).

#### Real device needed to test Sign in with Apple

Whilst the iOS Simulator can run the rest of the App, a real device was needed to test the actual Sign in functionality
which otherwise hangs in the simulator which has been reported is due to 2FA which is required to use Sign in with Apple.

### Enabling Sign In With Apple Capability

To enable Sign In functionality in your iOS App you'll need to add the **Sign in with Apple** capability in your App's **Target** > **Signing & Capabilities** window:

![](/img/pages/dev/ios-swiftui-xcode-capability.png)

### SwiftUI Layout

SwiftUI's declarative API is able to expressively capture our UI in its different states within this code fragment 
below:

```swift
struct ContentView: View {
    @ObservedObject var vm = ViewModel()
    
    var body: some View {
         VStack {
            if !vm.hasInit {
                Text("Loading...")
            } else {
                Text(vm.result)
                Button("Go!") {
                    vm.doSecureRequest()
                }
                if let auth = vm.auth {
                    VStack {
                        Text("Hi \(auth.displayName ?? "")")
                        if vm.authState != "" {
                            Text("authState: \(vm.authState)")
                                .foregroundColor(vm.authState == "authorized" ? .green : .primary)
                        }
                        Button("Sign Out") { vm.signOut() }
                    }
                } else {
                    AppleSignInButton()
                        .frame(width: 200, height: 50)
                        .onTapGesture {
                            self.vm.getRequest()
                        }
                }
            }
        }
    }
}

struct AppleSignInButton: UIViewRepresentable {
 func makeUIView(context: Context) -> ASAuthorizationAppleIDButton {
  return ASAuthorizationAppleIDButton(
    authorizationButtonType: .signUp,
    authorizationButtonStyle: .white)
 }
 func updateUIView(_ uiView: ASAuthorizationAppleIDButton, context:Context) {}
}
```

Which for an initialized unauthenticated user will render the **Go!** button with a Sign in button:

![](/img/pages/dev/ios-swiftui-home.png)

The Sign in buttons UI is defined by `AppleSignInButton()` which is our wrapper around Apple's `ASAuthorizationAppleIDButton()` that allows for several customizations to change its appearance. 
When the button is pressed it calls our ViewModel `getRequest()` method to initiate the Sign in request.

`@ObservedObject` is one of SwiftUI's constructs for managing state, effectively it's the mechanism by which your App modifies to re-render its UI. A good article explaining the features and differences of each construct can be found in
[SwiftUI: @State vs @StateObject vs @ObservedObject vs @EnvironmentObject](https://purple.telstra.com/blog/swiftui---state-vs--stateobject-vs--observedobject-vs--environme).

Inside `getRequest()` we can see it's just calling `signInWithApple.getAppleRequest()` which is our custom controller
used to manage the Sign in request.

```swift
class ViewModel: ObservableObject {
    private lazy var signInWithApple = SignInWithAppleCoordinator(vm:self)
    private lazy var client = createClient()
    
    func createClient() -> JsonServiceClient {
        let client = JsonServiceClient(baseUrl: "https://dev.servicestack.com:5001")
        client.ignoreCert = true
        return client
    }
    
    @Published var auth: AuthenticateResponse?
    var isAuthenticated:Bool { auth != nil }
    @Published var hasInit:Bool = false
    @Published var result:String = ""
    @Published var authState:String = ""
    
    func getRequest() {
        signInWithApple.getAppleRequest()
    }
    //....
}
```

The `SignInWithAppleCoordinator` uses the `ASAuthorizationController` to initiate the request and assigns itself as the `ASAuthorizationControllerDelegate` used to handle its success & error callbacks:

```swift
final class SignInWithAppleCoordinator : NSObject {
    let vm: ViewModel
    init(vm:ViewModel) {
        self.vm = vm
    }
    
    func getAppleRequest() {
        let appleIdProvider = ASAuthorizationAppleIDProvider()
        let request = appleIdProvider.createRequest()
        request.requestedScopes = [.fullName, .email]
        let authController = ASAuthorizationController(authorizationRequests: [request])
        authController.delegate = self
        authController.performRequests()
    }
    
    private func setUserInfo(for credential: ASAuthorizationAppleIDCredential) {
        ASAuthorizationAppleIDProvider().getCredentialState(forUserID: credential.user, completion: { 
          credentialState, error in
            var authState: String?
            switch credentialState {
            case .authorized: authState = "authorized"
            case .notFound: authState = "notFound"
            case .revoked: authState = "revoked"
            case .transferred: authState = "transferred"
            @unknown default: fatalError()
            }
            self.vm.setUser(credential:credential, authState:authState!)
        })
    }
}

extension SignInWithAppleCoordinator : ASAuthorizationControllerDelegate 
{    
    func authorizationController(controller: ASAuthorizationController, 
      didCompleteWithAuthorization authorization: ASAuthorization) {
        if let credential = authorization.credential as? ASAuthorizationAppleIDCredential {
            setUserInfo(for: credential)
        }
    }
    
    func authorizationController(controller: ASAuthorizationController, didCompleteWithError error: Error) {
        print("Sign In with Apple Error: \(error.localizedDescription)")
    }
}
```

The Sign in request is initiated with `authController.performRequests()` which on first usage launches a splash screen
explaining the benefits of **Sign in with Apple**:

![](/img/pages/dev/ios-swiftui-signin-with-apple-splash.png)

Then new users will be able to customize the name & email they'll share with your App:

![](/img/pages/dev/ios-swiftui-signin-with-apple-new-user.png)

Upon successful authentication the `authorizationController` callback gets invoked with the users credentials captured
in the `ASAuthorizationAppleIDCredential` struct that eventually calls `setUser()` with both the authenticated `credential` and its `authState`.

`setUser()` then uses the authorized `credential` to authenticate with our remote ServiceStack instance, passing
through the `givenName` and `familyName` that are only populated on a new Users initial Sign in request with the App.

```swift
func setUser(credential: ASAuthorizationAppleIDCredential, authState: String) {
    
    DispatchQueue.main.async {
        self.authState = authState

        if authState == "authorized" {
            let request = Authenticate()
            request.provider = "apple"
            request.accessToken = String(decoding:credential.identityToken!, as: UTF8.self)
            request.meta = [
                "authorizationCode": String(decoding:credential.authorizationCode!, as: UTF8.self),
                "givenName": credential.fullName?.givenName ?? "",
                "familyName": credential.fullName?.familyName ?? "",
            ]
            _ = self.client.postAsync(request)
                .done { r in
                    self.auth = r
                    UserDefaults.standard.set(r.toJson(), forKey: "auth")
                    self.client.bearerToken = r.bearerToken
                    self.client.refreshToken = r.refreshToken
                }
                .catch { error in
                    let status:ResponseStatus = error.convertUserInfo()!
                    self.result = "\(status.errorCode ?? ""): \(status.message ?? "")"
                }
        }
    }
}
```

Like the Flutter example, we save the JSON serialized `AuthenticateResponse` DTO to enable persistent Authentication
across App restarts and populate the `JsonServiceClient` with the JWT `bearerToken` and `refreshToken` to configure
the authenticated Service Client. 

To Sign out the user we can use a new fresh client instance and remove any shared cookies that were created by 
the previous client.

```swift
func signOut() {
    DispatchQueue.main.async {
        self.auth = nil
        HTTPCookieStorage.shared.cookies?.forEach(HTTPCookieStorage.shared.deleteCookie)
        self.client = self.createClient()
    }
    UserDefaults.standard.removeObject(forKey: "auth")
}
```

### Loading persistent JWT Auth Tokens

Which is restored on App start and verified the JWT Token is still valid by calling the `Authenticate` Service
with an empty DTO which returns if Authenticated otherwise throws a **401 Unauthorized** Error if they're not.

```swift
class ViewModel: ObservableObject {
  init() { load() }
  //...

  func load() {
      if let authJson = UserDefaults.standard.string(forKey: "auth"),
          let auth = AuthenticateResponse.fromJson(authJson) {
          client.bearerToken = auth.bearerToken
          client.refreshToken = auth.refreshToken
          client.postAsync(Authenticate())
              .done { r in
                  self.auth = auth
              }
              .catch { error in
                  self.client.bearerToken = nil
                  self.client.refreshToken = nil
                  UserDefaults.standard.removeObject(forKey: "auth")
              }
              .finally {
                  self.hasInit = true
              }
      } else {
          self.hasInit = true
      }
  }
}
```

#### Apple recommends maintaining Auth tokens in Keychain

Whilst this example uses `UserDefaults`, Apple's recommendation is to instead [save auth tokens in the User's Keychain](https://developer.apple.com/documentation/authenticationservices/implementing_user_authentication_with_sign_in_with_apple#3546459).

### Authenticated Requests

With our Service Client configured with our JWT Auth Tokens it can now be used to perform authenticated requests using 
the generic `JsonServiceClient` to send typed Swift DTOs generated from the 
[Swift ServiceStack Reference](/swift-add-servicestack-reference) feature:

```swift
func doSecureRequest() {
    self.result = ""
    DispatchQueue.main.async {
        let request = HelloSecure()
        request.name = "SwiftUI"
        _ = self.client.getAsync(request)
            .done { r in
                self.result = r.result ?? ""
            }
            .catch { error in
                let status:ResponseStatus = error.convertUserInfo()!
                self.result = "\(status.errorCode ?? ""): \(status.message ?? "")"
            }
    }
}
```

Which when sent from an authenticated Service Client will result in the expected:

![](/img/pages/dev/ios-swiftui-auth-request.jpeg)

### Advanced Configuration

As with ServiceStack's other [OAuth Providers](/auth/authentication-and-authorization#oauth-providers), the behavior of the `AppleAuthProvider` can be further customized with the below configuration, when registering the `AppleAuthProvider` or in your App's configured 
[App Settings](/appsettings):

```csharp
public class AppleAuthProvider
{
    // Apple Developer Membership Team ID
    // appsettings: oauth.apple.TeamId
    public string TeamId
    
    // Service ID
    // appsettings: oauth.apple.ClientId
    public string ClientId
        
    // Bundle ID
    // appsettings: oauth.apple.BundleId
    public string BundleId

    // The Private Key ID
    // appsettings: oauth.apple.KeyId
    public string KeyId
    
    // Path to .p8 Private Key 
    // appsettings: oauth.apple.KeyPath
    public string KeyPath

    // Base64 of .p8 Private Key bytes 
    // appsettings: oauth.apple.KeyBase64
    public string KeyBase64
    
    // .p8 Private Key bytes 
    public byte[] KeyBytes
    
    // Customize ClientSecret JWT
    public Func<AppleAuthProvider, string> ClientSecretFactory
    
    // When JWT Client Secret expires, defaults to Apple Max 6 Month Expiry 
    // default: 6 months in secs 
    // appsettings: oauth.apple.ClientSecretExpiry
    public TimeSpan ClientSecretExpiry
    
    // JSON list of Apple's public keys, defaults to fetching from https://appleid.apple.com/auth/keys
    // appsettings: oauth.apple.IssuerSigningKeysJson
    public string IssuerSigningKeysJson

    // Whether to cache private Key if loading from KeyPath, 
    // default: true
    // appsettings: oauth.apple.CacheKey
    public bool CacheKey

    // Whether to cache Apple's public keys
    // default: true
    // appsettings: oauth.apple.CacheKey
    public bool CacheIssuerSigningKeys

    // How long before re-validating Sign in RefreshToken, default: 1 day.
    // Set to null to disable RefreshToken validation.
    public TimeSpan? ValidateRefreshTokenExpiry

    // Custom DisplayName resolver function when not sent by Apple
    public Func<IAuthSession,IAuthTokens, string> ResolveUnknownDisplayName
}
```


# Anti Forgery
Source: https://docs.servicestack.net/auth/anti-forgery

You can leverage ASP.NET MVC's AntiForgery token support your Razor pages by embedding the token in your HTML Forms with:

## Example

```html
<form action="/antiforgery/test" method="POST">
    @Html.AntiForgeryToken()
    <input name="Field" value="Test"/>        
    <input type="submit"/>
</form>
```

Which you can then validate in your Service with:

```csharp
[Route("/antiforgery/test")]
public class AntiForgeryTest
{
    public string Field { get; set; }
}

public class AntiForgeryService : Service
{
    public object Any(AntiForgeryTest request)
    {
        AntiForgery.Validate();
        ...
    }
}
```

::: info
ASP.NET MVC's AntiForgery API is only available in the .NET Framework
:::


# AutoQuery RDBMS
Source: https://docs.servicestack.net/autoquery/rdbms

AutoQuery RDBMS enables the rapid development of high-performance, fully-queryable typed RDBMS data-driven services with just a POCO Request DTO class definition and [supports most major RDBMS](/ormlite/#ormlite-rdbms-providers) courtesy of building on [OrmLite's high-performance RDBMS-agnostic API's](https://github.com/ServiceStack/ServiceStack.OrmLite).

### AutoQuery Services are ServiceStack Services

An important point to highlight is that AutoQuery Services are just normal ServiceStack Services, utilizing the same [Request Pipeline](/order-of-operations), which can be mapped to any [user-defined route](/routing), is available in all [registered formats](/formats) and can be [consumed from existing typed Service Clients](/clients-overview). 

In addition to leveraging ServiceStack's existing functionality, maximizing re-use in this way reduces the cognitive overhead required for developers who can re-use their existing knowledge in implementing, customizing, introspecting and consuming ServiceStack services. 

### Getting Started

Like ServiceStack's [other composable features](/plugins), the AutoQuery Feature is enabled by registering a Plugin, e.g:

```csharp
Plugins.Add(new AutoQueryFeature { MaxLimit = 100 });
```

Which is all that's needed to enable the AutoQuery feature. The AutoQueryFeature is inside [ServiceStack.Server](https://servicestack.net/download#get-started) NuGet package which contains value-added features that utilize either OrmLite and Redis which can be added to your project with:

:::copy
`<PackageReference Include="ServiceStack.Server" Version="8.*" />`
:::

If you don't have OrmLite configured it can be registered with a 1-liner by specifying your preferred DialectProvider and Connection String:

```csharp
container.Register<IDbConnectionFactory>(
    new OrmLiteConnectionFactory(":memory:", SqliteDialect.Provider));
```

The above config registers an In Memory Sqlite database although as the AutoQuery test suite works in all [supported RDBMS providers](https://github.com/ServiceStack/ServiceStack.OrmLite/#download) you're free to use your registered DB of choice.

The `MaxLimit` option ensures each query returns a maximum limit of **100** rows.

::: tip
It's recommended `MaxLimit` is set based on your own requirements as not setting a `MaxLimit` will return **all rows** for a query
:::

Now that everything's configured we can create our first service. To implement the ideal API for [OData's movie ratings query](/autoquery/why-not-odata) we just need to define the Request DTO for our service, i.e:

```csharp
[Route("/movies")]
public class FindMovies : QueryDb<Movie>
{
    public string[] Ratings { get; set; }
}
```

That's all the code needed! Which we can now call using the ideal route:

```
/movies?ratings=G,PG-13
```

### Clients continue to benefit from a typed API

and because it's a just regular Request DTO, we also get an end-to-end typed API for free with:

```csharp
var movies = client.Get(new FindMovies { Ratings = new[]{"G","PG-13"} })
```

Whilst that gives us the ideal API we want, the minimum code required is to just declare a new Request DTO with the table you wish to query:

```csharp
public class FindMovies : QueryDb<Movie> {}
```

Which just like other Request DTO's in ServiceStack falls back to using ServiceStack's [pre-defined routes](/routing#pre-defined-routes)

### IQuery

`QueryDb<T>` is just an abstract class that implements `IQuery<T>` and returns a typed `QueryResponse<T>`:

```csharp
public abstract class QueryDb<T> : QueryDb, 
    IQuery<T>, IReturn<QueryResponse<T>> { }

public interface IQuery
{
    int? Skip { get; set; }           // How many results to skip
    int? Take { get; set; }           // How many results to return
    string OrderBy { get; set; }      // List of fields to sort by
    string OrderByDesc { get; set; }  // List of fields to sort by descending
    string Include { get; set; }      // Aggregate queries to include
    string Fields { get; set; }       // The fields to return
}
```

The `IQuery` interface includes shared features that all Queries support and acts as a interface marker telling ServiceStack to create query services for each Request DTO. 

### Custom AutoQuery Implementations

The behavior of queries can be completely customized by simply providing your own Service implementation instead, e.g:

```csharp
// Override with custom implementation
public class MyQueryServices(IAutoQueryDb autoQuery) : Service
{
    // Sync
    public object Any(FindMovies query)
    {
        using var db = autoQuery.GetDb(query, base.Request);
        var q = autoQuery.CreateQuery(query, base.Request, db);
        return autoQuery.Execute(query, q, base.Request, db);
    }

    // Async
    public async Task<object> Any(QueryRockstars query)
    {
        using var db = autoQuery.GetDb(query, base.Request);
        var q = autoQuery.CreateQuery(query, base.Request, db);
        return await autoQuery.ExecuteAsync(query, q, base.Request, db);
    }
}
```

This is essentially what the AutoQuery feature generates for each `IQuery` Request DTO unless a Service for the Request DTO already exists, in which case it uses the existing implementation. 

We can inspect each line to understand how AutoQuery works:

Resolve the DB Connection for this AutoQuery request:

```csharp
using var db = AutoQuery.GetDb(query, base.Request);
```

By default this follows the [Multitenancy conventions](/multitenancy) for resolving a DB connection, which you can override with your 
own custom resolution for this service.

Creating a populated type SqlExpression:

```csharp
var q = AutoQuery.CreateQuery(query, base.Request, db);
```

Is an equivalent short-hand version for:

```csharp
Dictionary<string,string> queryArgs = Request.GetRequestParams();
var q = AutoQuery.CreateQuery(dto, queryArgs, Request, db);
```

Which constructs an [OrmLite SqlExpression](https://github.com/ServiceStack/ServiceStack.OrmLite/#examples) 
from typed properties on the Request DTO as well as any untyped key/value pairs on the HTTP Requests 
**QueryString** or **FormData**.

At this point you can inspect the SqlExpression that AutoQuery has constructed or append any additional custom criteria to limit the scope of the request like limiting results to the authenticated user.

After constructing the query from the Request all that's left is executing it:

```csharp
return AutoQuery.Execute(dto, q, Request);
```

As the implementation is trivial we can show the implementation inline:

```csharp
public QueryResponse<Into> Execute<Into>(
    IDbConnection db, ISqlExpression query)
{
    var q = (SqlExpression<From>)query;
    return new QueryResponse<Into>
    {
        Offset = q.Offset.GetValueOrDefault(0),
        Total = (int)db.Count(q),
        Results = db.LoadSelect<Into, From>(q),
    };
}
```

Basically just returns the results in an `QueryResponse<Into>` Response DTO. We also see that each query makes 2 requests, 1 for retrieving the total count for the query and another for the actual results, either limited by the request's `Skip` or `Take` or the configured `AutoQueryFeature.MaxLimit`.  

## Returning Custom Results

To specify returning results in a custom Response DTO you can inherit from the `QueryDb<From, Into>` convenience base class:

```csharp
public abstract class QueryDb<From, Into> 
    : QueryDb, IQuery<From, Into>, IReturn<QueryResponse<Into>> { }
```

As we can tell from the class definition this tells AutoQuery you want to query against `From` but return results into the specified `Into` type. This allows being able to return a curated set of columns, e.g:

```csharp
public class QueryCustomRockstars : QueryDb<Rockstar, CustomRockstar> {}

public class CustomRockstar
{
    public string FirstName { get; set; }
    public string LastName { get; set; }
    public int? Age { get; set; }
    public string RockstarAlbumName { get; set; }
}
```

In the example above we're returning only a subset of results. Unmatched properties like `RockstarAlbumName` are ignored enabling the re-use of custom DTO's for different queries.

## Returning Nested Related Results

AutoQuery also takes advantage of [OrmLite's References Support](https://github.com/ServiceStack/ServiceStack.OrmLite/#reference-support-poco-style) which lets you return related child records that are annotated with `[Reference]` attribute, e.g:

```csharp
public class QueryRockstars : QueryDb<Rockstar> {}

public class Rockstar
{
    public int Id { get; set; }
    public string FirstName { get; set; }
    public string LastName { get; set; }
    public int? Age { get; set; }

    [Reference]
    public List<RockstarAlbum> Albums { get; set; } 
}
```

## Joining Tables

AutoQuery lets us take advantage of OrmLite's recent [support for JOINs in typed SqlExpressions](https://github.com/ServiceStack/ServiceStack.OrmLite/#typed-sqlexpression-support-for-joins) 

We can tell AutoQuery to join on multiple tables using the `IJoin<T1,T2>` interface marker:

```csharp
public class QueryRockstarAlbums 
  : QueryDb<Rockstar,CustomRockstar>, IJoin<Rockstar,RockstarAlbum>
{
    public int? Age { get; set; }
    public string RockstarAlbumName { get; set; }
}
```

The above example tells AutoQuery to query against an **INNER JOIN** of the `Rockstar` and `RockstarAlbum` tables using [OrmLite's reference conventions](https://github.com/ServiceStack/ServiceStack.OrmLite/#reference-conventionst) that's implicit between both tables.

The Request DTO lets us query against fields across the joined tables where each field is matched with the [first table containing the field](https://github.com/ServiceStack/ServiceStack.OrmLite/#selecting-multiple-columns-across-joined-tables). You can match against fields using the fully qualified `{Table}{Field}` convention, e.g. `RockstarAlbumName` queries against the `RockstarAlbum`.`Name` column.

This mapping of fields also applies to the Response DTO where now `RockstarAlbumName` from the above `CustomRockstar` type will be populated:

```csharp
public class CustomRockstar
{
    ...
    public string RockstarAlbumName { get; set; }
}
```

### Joining multiple tables

Use the appropriate `Join<,>` generic interface to specify JOINs across multiple tables. AutoQuery supports joining up to 5 tables with 1 `Join<>` interface, e.g:

```csharp
IJoin<T1, T2, T3, T4, T5>
```

Or alternatively any number of tables can be joined together by annotating the Request DTO with multiple `IJoin<>` interfaces, e.g:

```csharp
IJoin<T1,T2>,
IJoin<T2,T3>,
IJoin<T3,T4>,
//...
```

### Support for LEFT JOINS

You can tell AutoQuery to use a **LEFT JOIN** by using the `ILeftJoin<,>` marker interface instead, e.g:

```csharp
public class QueryRockstarAlbumsLeftJoin : QueryDb<Rockstar, CustomRockstar>, 
    ILeftJoin<Rockstar, RockstarAlbum>
{
    public int? Age { get; set; }
    public string AlbumName { get; set; }
}
```

## Customizable Adhoc Queries

The queries up to this point showcase the default behavior of Request DTO fields performing an **Exact Match** using the `=` operand to match fields on queried tables. Advanced queries are available via configurable attributes illustrated in the example below which uses explicit templates to enable custom querying, e.g:

```csharp
public class QueryRockstars : QueryDb<Rockstar>
{
    //Defaults to 'AND FirstName = {Value}'
    public string FirstName { get; set; }  

    //Collections defaults to 'FirstName IN ({Values})'
    public string[] FirstNames { get; set; } 

    [QueryDbField(Operand = ">=")]
    public int? Age { get; set; }

    [QueryDbField(Template = "UPPER({Field}) LIKE UPPER({Value})", 
                Field = "FirstName")]
    public string FirstNameCaseInsensitive { get; set; }

    [QueryDbField(Template="{Field} LIKE {Value}", 
                Field="FirstName", ValueFormat="{0}%")]
    public string FirstNameStartsWith { get; set; }

    [QueryDbField(Template="{Field} LIKE {Value}", 
                Field="LastName", ValueFormat="%{0}")]
    public string LastNameEndsWith { get; set; }

    [QueryDbField(Template = "{Field} BETWEEN {Value1} AND {Value2}", 
                Field="FirstName")]
    public string[] FirstNameBetween { get; set; }

    [QueryDbField(Term = QueryTerm.Or)]
    public string LastName { get; set; }
}
```

We'll go through each of the examples to give a better idea of the customizations available.

### Queries on Collections

ServiceStack properties are case-insensitive and allows populating a collection with comma-delimited syntax, so this query:

```
/rockstars?firstNames=A,B,C
```

Will populate the string array:

```csharp
public string[] FirstNames { get; set; } 
```

That by default `IEnumerable` properties are queried using an SQL `{Field} IN ({Values})` template which will convert the string array into a quoted and escaped comma-delimited list of values suitable for use in SQL that looks like:

```sql
"FirstName" IN ('A','B','C')
```

The `{Field}` property is substituted according to the OrmLite FieldDefinition it matches, which for a Joined table with an `[Alias("FName")]` attribute would substitute to a fully-qualified name, e.g: `"Table"."FName"`

AutoQuerying also supports pluralized versions by trimming the `s` off Field names as a fall-back which is how `FirstNames` was able to match the `FirstName` table property.

### Customizable Operands

One of the easiest customization's available is changing the operand used in the query, e.g:

```csharp 
[QueryDbField(Operand = ">=")]
public int? Age { get; set; }
```

Will change how the Age is compared to:

```sql
"Age" >= {Value}
```

### Customizable Templates

By providing a customized template  even greater customization achieved and by sticking with TSQL compatible fragments will ensure it's supported by every RDBMS provider, e.g: 

```csharp
[QueryDbField(Template = "UPPER({Field}) LIKE UPPER({Value})",
            Field="FirstName")]
public string FirstNameCaseInsensitive { get; set; }
```

As noted above `{Field}` variable place holder is substituted with the qualified Table field whilst `{Value}` gets quoted and escaped to prevent SQL Injections.

The `Field="FirstName"` tells AutoQuery to ignore the property name and use the specified field name.

### Formatting Values

You can use the `ValueFormat` modifier to insert custom characters within the quoted `{Value}` placeholder which we use to insert the `%` wildcard in with the quoted value enabling StartsWith and EndsWith queries, e.g:

```csharp
[QueryDbField(Template="{Field} LIKE {Value}", 
            Field="FirstName", ValueFormat="{0}%")]
public string FirstNameStartsWith { get; set; }

[QueryDbField(Template="{Field} LIKE {Value}", 
            Field="LastName", ValueFormat="%{0}")]
public string LastNameEndsWith { get; set; }
```

### Specifying Multi Airity Queries

An alternate way to format multiple values is to use `Value{N}` variable placeholders which allows supporting statements with multiple values like SQL's **BETWEEN** statement:

```csharp
[QueryDbField(Template = "{Field} BETWEEN {Value1} AND {Value2}", 
            Field = "FirstName")]
public string[] FirstNameBetween { get; set; }
```

### Changing Querying Behavior

By default queries act like a filter and every condition is combined with **AND** boolean term to further filter the result-set. This can be changed to use an **OR** at the field-level by specifying `Term=QueryTerm.Or` modifier, e.g:

```csharp
[QueryDbField(Term=QueryTerm.Or)]
public string LastName { get; set; }
```

However as your API's should strive to [retain the same behavior and call-semantics](http://stackoverflow.com/questions/15927475/servicestack-request-dto-design/15941229#15941229) the recommendation is to instead change the behavior at the API-level so that each property maintains consistent behavior, e.g:

```csharp
[QueryDb(QueryTerm.Or)]
public class QueryRockstars : QueryDb<Rockstar>
{
    public int[] Ids { get; set; }
    public List<int> Ages { get; set; }
    public List<string> FirstNames { get; set; }
}
```

In this example each property is inclusive where every value specified is added to the returned result-set. 

### Dynamic Attributes

Whilst .NET attributes are normally defined with the property they attribute, ServiceStack also allows attributes to be added dynamically allowing them to be defined elsewhere, detached from the DTO's, e.g:

```csharp
typeof(QueryRockstars)
    .GetProperty("Age")
    .AddAttributes(new QueryDbFieldAttribute { Operand = ">=" });
```

## Implicit Conventions

The examples above show how we can define adhoc **explicit** queries on concrete properties using explicit attributes. Whilst this was necessary to understand how to create customized queries, the concrete properties and explicit attributes can be avoided entirely by utilizing the built-in conventions, configurable on the `AutoQueryFeature` plugin.

With implicit conventions we can get back to defining Request DTO's with an empty body:

```csharp
public class QueryRockstars : QueryDb<Rockstar> {}
```

The built-in conventions allow using convention-based naming to query fields with expected behavior using self-describing properties. To explore this in more detail lets look at what built-in conventions are defined:

```csharp
const string GreaterThanOrEqualFormat = "{Field} >= {Value}";
const string GreaterThanFormat =        "{Field} >  {Value}";
const string LessThanFormat =           "{Field} <  {Value}";
const string LessThanOrEqualFormat =    "{Field} <= {Value}";
const string NotEqualFormat =           "{Field} <> {Value}";
const string IsNull =                   "{Field} IS NULL";
const string IsNotNull =                "{Field} IS NOT NULL";

ImplicitConventions = new Dictionary<string, string> 
{
    {"%Above%",         GreaterThanFormat},
    {"Begin%",          GreaterThanFormat},
    {"%Beyond%",        GreaterThanFormat},
    {"%Over%",          GreaterThanFormat},
    {"%OlderThan",      GreaterThanFormat},
    {"%After%",         GreaterThanFormat},
    {"OnOrAfter%",      GreaterThanOrEqualFormat},
    {"%From%",          GreaterThanOrEqualFormat},
    {"Since%",          GreaterThanOrEqualFormat},
    {"Start%",          GreaterThanOrEqualFormat},
    {"%Higher%",        GreaterThanOrEqualFormat},
    {">%",              GreaterThanOrEqualFormat},
    {"%>",              GreaterThanFormat},
    {"%!",              NotEqualFormat},
    {"<>%",             NotEqualFormat},

    {"%GreaterThanOrEqualTo%", GreaterThanOrEqualFormat},
    {"%GreaterThan%",          GreaterThanFormat},
    {"%LessThan%",             LessThanFormat},
    {"%LessThanOrEqualTo%",    LessThanOrEqualFormat},
    {"%NotEqualTo",            NotEqualFormat},

    {"Behind%",         LessThanFormat},
    {"%Below%",         LessThanFormat},
    {"%Under%",         LessThanFormat},
    {"%Lower%",         LessThanFormat},
    {"%Before%",        LessThanFormat},
    {"%YoungerThan",    LessThanFormat},
    {"OnOrBefore%",     LessThanOrEqualFormat},
    {"End%",            LessThanOrEqualFormat},
    {"Stop%",           LessThanOrEqualFormat},
    {"To%",             LessThanOrEqualFormat},
    {"Until%",          LessThanOrEqualFormat},
    {"%<",              LessThanOrEqualFormat},
    {"<%",              LessThanFormat},

    {"Like%",           "UPPER({Field}) LIKE UPPER({Value})"},
    {"%In",             "{Field} IN ({Values})"},
    {"%Ids",            "{Field} IN ({Values})"},
    {"%Between%",       "{Field} BETWEEN {Value1} AND {Value2}"},

    {"%HasAll",         "{Value} & {Field} = {Value}"},
    {"%HasAny",         "{Value} & {Field} > 0"},
            
    {"%IsNull",         IsNull},
    {"%IsNotNull",      IsNotNull},
};

EndsWithConventions = new Dictionary<string, QueryDbFieldAttribute>
{
    { "StartsWith", new QueryDbFieldAttribute { 
          Template= "UPPER({Field}) LIKE UPPER({Value})", 
          ValueFormat= "{0}%" }},
    { "Contains", new QueryDbFieldAttribute { 
          Template= "UPPER({Field}) LIKE UPPER({Value})", 
          ValueFormat= "%{0}%" }},
    { "EndsWith", new QueryDbFieldAttribute { 
          Template= "UPPER({Field}) LIKE UPPER({Value})", 
          ValueFormat= "%{0}" }},
};
```

The string key in the above dictionaries describe what property each rule maps to. We'll run through a few examples to see how we can make use of them:

The request below works as you would expect in returning all Rockstars older than 42 years of age.

```
/rockstars?AgeOlderThan=42
```

It works by matching on the rule since `AgeOlderThan` does indeed ends with `OlderThan`:

```csharp
{"%OlderThan", "{Field} > {Value}"},
```

The `%` wildcard is a placeholder for the field name which resolves to `Age`. Now that it has a match it creates a query with the defined `{Field} > {Value}` template to achieve the desired behavior.

If you instead wanted to use the inclusive `>=` operand, we can just use a rule with the `>=` template:

```
/rockstars?AgeGreaterThanOrEqualTo=42
```

Which matches the rule:

```csharp
{"%GreaterThanOrEqualTo%", "{Field} >= {Value}"},
```

And when the wildcard is on both ends of the pattern:

```csharp
{"%GreaterThan%", "{Field} > {Value}"},
```

So to can the field name, which matches both these rules:

```
/rockstars?AgeGreaterThan=42
/rockstars?GreaterThanAge=42
```

An alternative to using wordy suffixes are the built-in short-hand syntax:

| Param | Behavior |
|-|-|
|**>Age**|`Age >= {Value}`|
|**Age>**|`Age  > {Value}`|
|**<Age**|`Age  < {Value}`|
|**Age<**|`Age <= {Value}`|

Which uses the appropriate operand based on whether the `<` `>` operators come before or after the field name:

```
/rockstars?>Age=42
/rockstars?Age>=42
/rockstars?<Age=42
/rockstars?Age<=42
```

The use of `{Values}` or the `Value{N}` formats specifies the query should be treated as a collection, e.g:

```csharp
{"%Ids",       "{Field} IN ({Values})"},
{"%In",        "{Field} IN ({Values})"},
{"%Between%",  "{Field} BETWEEN {Value1} AND {Value2}"},
```

Which allows multiple values to be specified on the QueryString:

```
/rockstars?Ids=1,2,3
/rockstars?FirstNamesIn=Jim,Kurt
/rockstars?FirstNameBetween=A,F
```

### Advanced Conventions

More advanced conventions can be specified directly on the `StartsWithConventions` and `EndsWithConventions` dictionaries which allow customizations using the full `[QueryDbField]` attribute, e.g:

```csharp
EndsWithConventions = new Dictionary<string, QueryDbFieldAttribute>
{
    { "StartsWith", new QueryDbFieldAttribute { 
          Template = "UPPER({Field}) LIKE UPPER({Value})", 
          ValueFormat = "{0}%" }},
    { "Contains", new QueryDbFieldAttribute { 
          Template = "UPPER({Field}) LIKE UPPER({Value})", 
          ValueFormat = "%{0}%" }},
    { "EndsWith", new QueryDbFieldAttribute { 
          Template = "UPPER({Field}) LIKE UPPER({Value})", 
          ValueFormat = "%{0}" }},
};
```

that can be called as normal:

```
/rockstars?FirstNameStartsWith=Jim
/rockstars?LastNameEndsWith=son
/rockstars?RockstarAlbumNameContains=e
```

This also shows that Implicit Conventions can also apply to joined table fields like `RockstarAlbumNameContains` using the fully qualified `{Table}{Field}` reference convention.

## Explicit Conventions

Whilst Implicit conventions can be called on an empty "contract-less" DTO, you're also able to specify the concrete properties for the conventions you end up using: 

```csharp
public class QueryRockstars : QueryDb<Rockstar>
{
    public int? AgeOlderThan { get; set; }
    public int? AgeGreaterThanOrEqualTo { get; set; }
    public int? AgeGreaterThan { get; set; }
    public int? GreaterThanAge { get; set; }
    public string FirstNameStartsWith { get; set; }
    public string LastNameEndsWith { get; set; }
    public string LastNameContains { get; set; }
    public string RockstarAlbumNameContains { get; set; }
    public int? RockstarIdAfter { get; set; }
    public int? RockstarIdOnOrAfter { get; set; }
}
```

### Preemptive client requests

A hidden gem in AutoQuery's approach that's not immediately obvious is how everything will still work when concrete properties are only added to client Request DTO's that the server doesn't even know about yet! This is possible as the service client generates the same HTTP Request that matches the implicit conventions, making it possible to perform new preemptive typed queries on the client without having to redeploy the server. Although unlikely to be a popular use-case given that in most cases the client and server shares the same DTOs, it's a nice surprise feature when needed.

### Advantages of well-defined Service Contracts

The advantages of formalizing the conventions you end up using is that they can be consumed with ServiceStack's [Typed Service Clients](/csharp-client):

```csharp
var response = client.Get(new QueryRockstars { AgeOlderThan = 42 });
```

As well as making your API self-describing and gives you access to all of ServiceStack's metadata services including:

 - [Metadata pages](/metadata-page)
 - [Open API](/openapi)
 - [Postman Support](/postman)

Which is why we recommend formalizing your conventions you want to allow before deploying your API to production. 

When publishing your API, you can also assert that only explicit conventions are ever used by disabling untyped implicit conventions support with:

```csharp
Plugins.Add(new AutoQueryFeature { EnableUntypedQueries = false });
```

## Raw SQL Filters

It's also possible to specify Raw SQL Filters. Whilst offering greater flexibility they also suffer from many of the problems that OData's expressions have. 

Raw SQL Filters also don't benefit from limiting matching to declared fields and auto-escaping and quoting of values although they're still validated against OrmLite's [IllegalSqlFragmentTokens](https://github.com/ServiceStack/ServiceStack.OrmLite/blob/master/src/ServiceStack.OrmLite/OrmLiteUtilExtensions.cs#L172) to protect against SQL Injection attacks. But as they still allow calling SQL Functions, Raw SqlFilters shouldn't be enabled when accessible by untrusted parties unless they've been configured to use a [Named OrmLite DB Connection](https://github.com/ServiceStack/ServiceStack.OrmLite/#multi-nested-database-connections) which is read-only and locked-down so that it only has access to what it's allowed to.

If safe to do so, RawSqlFilters can be enabled with:

```csharp
Plugins.Add(new AutoQueryFeature { 
    EnableRawSqlFilters = true,
    UseNamedConnection = "readonly",
    IllegalSqlFragmentTokens = { "ProtectedSqlFunction" },
});
```

Once enabled you can use the `_select`, `_from`, `_where` modifiers to append custom SQL Fragments, e.g:

```
/rockstars?_select=FirstName,LastName

/rockstars?_where=Age > 42
/rockstars?_where=FirstName LIKE 'Jim%'

/rockstars?_select=FirstName&_where=LastName = 'Cobain'

/rockstars?_from=Rockstar r INNER JOIN RockstarAlbum a ON r.Id = a.RockstarId
```

::: info
url encoding in the above examples are omitted for readability
:::

Whilst Raw SqlFilters affect the query executed, they don't change what Response DTO is returned.

## Custom Fields

You can also customize which fields you want returned using the `Fields` property available on all AutoQuery Services, e.g:

```
?Fields=Id,Name,Description,JoinTableId
```

The Fields still need to be defined on the Response DTO as this feature doesn't change the Response
DTO Schema, only which fields are populated. This does change the underlying RDBMS SELECT that's executed, 
also benefiting from reduced bandwidth between your RDBMS and App Server.

A useful [JSON customization](/customize-json-responses) 
that you can add when specifying custom fields is `ExcludeDefaultValues`, e.g:

```
/query?Fields=Id,Name,Description,JoinTableId&jsconfig=ExcludeDefaultValues
```

### Wildcards

You can use **wildcards** to quickly reference all fields on a table using the `table.*` format, e.g:

```
?fields=id,departmentid,department,employee.*
```

Which is a shorthand that expands to manually listing each field in the `Employee` table, useful for queries 
which joins multiple tables, e.g:

```csharp
[Route("/employees", "GET")]
public class QueryEmployees : QueryDb<Employee>,
    IJoin<Employee, EmployeeType>,
    IJoin<Employee, Department>,
    IJoin<Employee, Title> 
{
    //...
}
```

### DISTINCT Custom Fields

To query only results with distinct fields you can prefix the custom fields list with `DISTINCT `, e.g

Using QueryString:

```
?Fields=DISTINCT City,Country
```

Using C# Client:

```csharp
var response = client.Get(new QueryCustomers { 
    Fields = "DISTINCT City,Country"
})
```

We can use this feature with Northwind's existing [AutoQuery Request DTOs](https://github.com/NetCoreApps/Northwind/blob/master/src/Northwind.ServiceModel/AutoQuery.cs):

```csharp
[Route("/query/customers")]
public class QueryCustomers : QueryDb<Customer> { }
```

To return all unique City and Countries of Northwind Customers with:

 - [northwind.netcore.io/query/customers?Fields=DISTINCT City,Country](https://northwind.netcore.io/query/customers?Fields=DISTINCT%20City,Country)

Or to just return their unique Countries they're in:

 - [northwind.netcore.io/query/customers?Fields=DISTINCT Country](https://northwind.netcore.io/query/customers?Fields=DISTINCT%20Country)

## Paging and Ordering

Some functionality defined on the core `IQuery` interface and available to all queries is the ability to page and order results:

```csharp
public interface IQuery
{
    int? Skip { get; set; }
    int? Take { get; set; }
    string OrderBy { get; set; }
    string OrderByDesc { get; set; }
}
```

This works as you would expect where you can modify the returned result set with:

```
/rockstars?skip=10&take=20&orderBy=Id
```

Or when accessing via a ServiceClient:

```csharp
client.Get(new QueryRockstars { Skip=10, Take=20, OrderBy="Id" });
``` 

When results are paged an implicit OrderBy is added using the PrimaryKey of the `IQuery<Table>` to ensure predictable ordering of results are returned. You can change the OrderBy used by specifying your own: 

```csharp
client.Get(new QueryRockstars { Skip=10, Take=20, OrderByDesc="Id" });
``` 

Or remove the default behavior with:

```csharp
Plugins.Add(new AutoQueryFeature { 
    OrderByPrimaryKeyOnPagedQuery = false 
});
```

### Multiple OrderBy's

AutoQuery also supports specifying multiple OrderBy's with a comma-delimited list of field names, e.g:

```
/rockstars?orderBy=Id,Age,FirstName
```

Same request via Service Client:

```csharp
client.Get(new QueryRockstars { OrderBy = "Id,Age,FirstName" });
```

#### Sort specific fields in reverse order

When specifying multiple order by's you can sort specific fields in reverse order by prepending a `-` before the field name, e.g:

```
?orderBy=Id,-Age,FirstName
?orderByDesc=-Id,Age,-FirstName
```

### OrderBy Random

`OrderBy` includes special support for returning results in Random order using `Random`, e.g:

```
/rockstars?OrderBy=Random
```

Using Service Client:

```csharp
client.Get(new QueryRockstars { OrderBy = "Random" });
``` 

## Service Clients Support

One of the major benefits of using Typed DTO's to define your Service Contract is that it allows usage of ServiceStack's [.NET Service Clients](/csharp-client) which enables an end-to-end API without code-gen for [most .NET and PCL client platforms](https://github.com/ServiceStack/Hello). 

With the richer semantics available in queries, we've been able to enhance the Service Clients new `GetLazy()` API that allows lazy streaming of responses to provide transparent paging of large result-sets, e.g:

```csharp
var results = client.GetLazy(new QueryMovies { 
    Ratings = new[]{"G","PG-13"}
}).ToList();
```

Since GetLazy returns a lazy `IEnumerable<T>` sequence it can also be used within LINQ expressions, e.g:

```csharp
var top250 = client.GetLazy(new QueryMovies { 
        Ratings = new[]{ "G", "PG-13" } 
    })
    .Take(250)
    .ConvertTo(x => x.Title);
```

## Mime Types and Content-Negotiation

Another benefit we get from AutoQuery Services being regular ServiceStack services is taking advantage of [ServiceStack's built-in formats](/formats). 

### CSV Format

The [CSV Format](/csv-format) especially shines here given queries return a single tabular resultset making it perfect for CSV. In many ways CSV is one of the most interoperable Data Formats given most data import and manipulation programs including Databases and Spreadsheets have native support for CSV allowing for deep and seamless integration.

ServiceStack provides a number of ways to [request your preferred content-type](/routing#content-negotiation), the easiest of which is to just use the `.{format}` extension at the end of the `/pathinfo` e.g:

```
/rockstars.csv
/movies.csv?ratings=G,PG-13
```

[CSV Format](/csv-format) responses can use the same [scoped custom responses as JSON](/customize-json-responses) to allow
Typed Results to exclude default values columns when returning limited [custom fields with `?fields`](/autoquery/rdbms#custom-fields):

 - Camel Humps Notation: `?jsconfig=edv`
 - Full configuration: `?jsconfig=ExcludeDefaultValues`

### JSONL Format

whilst the [JSON Lines Format](/jsonl-format) is useful for returning results in a streamable JSON format:

```
/rockstars.jsonl
/movies.jsonl?ratings=G,PG-13
```

## Named Connection

AutoQuery can also easily be configured to query any number of different databases registered in your AppHost. 

In the example below we configure our main RDBMS to use SQL Server and register a **Named Connection** 
to point to a **Reporting** PostgreSQL RDBMS:

```csharp
var dbFactory = new OrmLiteConnectionFactory(connString, SqlServer2012Dialect.Provider);
container.Register<IDbConnectionFactory>(dbFactory);

dbFactory.RegisterConnection("Reporting", pgConnString, PostgreSqlDialect.Provider);
```

Any normal AutoQuery Services like `QueryOrders` will use the default SQL Server connection whilst 
`QuerySales` will execute its query on the PostgreSQL `Reporting` Database instead:

```csharp
public class QueryOrders : QueryDb<Order> {}

[ConnectionInfo(NamedConnection = "Reporting")]
public class QuerySales : QueryDb<Sales> {}
```

An alternative to specifying the `[ConnectionInfo]` Request Filter Attribute on the AutoQuery Request DTO, is to specify the named connection on the **POCO Table** instead, e.g:

```csharp
[NamedConnection("Reporting")]
public class Sales { ... }

public class QuerySales : QueryDb<Sales> {}
```

## Include Aggregates in AutoQuery

AutoQuery supports running additional Aggregate queries on the queried result-set. To include aggregates in your Query's response specify them in the `Include` property of your AutoQuery Request DTO, e.g:

```cs
var response = client.Get(new QueryRockstars { Include = "COUNT(*)" })
```

Or in the `Include` QueryString param if you're calling AutoQuery Services from a browser, e.g:

```
/rockstars?include=COUNT(*)
```

The result is then published in the `QueryResponse<T>.Meta` String Dictionary and is accessible with:

```
response.Meta["COUNT(*)"] //= 7
```

By default any of the functions in the SQL Aggregate whitelist can be referenced: 

```
AVG, COUNT, FIRST, LAST, MAX, MIN, SUM
```

Which can be added to or removed from by modifying `SqlAggregateFunctions` collection, e.g, you can allow usage of a `CustomAggregate` SQL Function with:

```cs
Plugins.Add(new AutoQueryFeature { 
    SqlAggregateFunctions = { "CustomAggregate" }
})
```

### Aggregate Query Usage

The syntax for aggregate functions is modelled after their usage in SQL so they're instantly familiar. At its most basic usage you can just specify the name of the aggregate function which will use `*` as a default argument so you can also query `COUNT(*)` with: 

```
?include=COUNT
```

It also supports SQL aliases:

```
COUNT(*) Total
COUNT(*) as Total
```

Which is used to change what key the result is saved into:

```cs
response.Meta["Total"]
```

Columns can be referenced by name:

```
COUNT(LivingStatus)
```

If an argument matches a column in the primary table the literal reference is used as-is, if it matches a column in a joined table it's replaced with its fully-qualified reference and when it doesn't match any column, Numbers are passed as-is otherwise its automatically escaped and quoted and passed in as a string literal.

The `DISTINCT` modifier can also be used, so a complex example looks like:

```
COUNT(DISTINCT LivingStatus) as UniqueStatus
```

Which saves the result of the above function in:

```cs
response.Meta["UniqueStatus"]
```

Any number of aggregate functions can be combined in a comma-delimited list:

```
Count(*) Total, Min(Age), AVG(Age) AverageAge
```

Which returns results in:

```cs
response.Meta["Total"]
response.Meta["Min(Age)"]
response.Meta["AverageAge"]
```

### Include Total

The total records available for a query can be included in the Response by adding it on the QueryString, e.g:

```
/query?Include=Total
```

Or on the Request DTO:

```csharp
var response = client.Get(new MyQuery { Include = "Total" });
```

Alternatively you can always have the Total returned in every request with:

```csharp
Plugins.Add(new AutoQueryFeature {
    IncludeTotal = true
})
```

#### Aggregate Query Performance

AutoQuery combines all other aggregate functions like `Total` and executes them in the same a single query for optimal performance.

### Hybrid AutoQuery Services

AutoQuery Services can be easily enhanced by creating a custom Service implementation that modifies the `SqlExpression` Query that AutoQuery auto populates from the incoming request. In addition to using OrmLite's typed API to perform standard DB queries you can also take advantage of advanced RDBMS features with custom SQL fragments. As an example we'll look at the implementation of [techstacks.io](https://github.com/NetCoreApps/TechStacks) fundamental 
[QueryPosts Service](https://github.com/NetCoreApps/TechStacks/blob/master/src/TechStacks.ServiceInterface/PostPublicServices.cs) 
which powers every Post feed in TechStacks where its custom implementation inherits all queryable functionality of its `QueryDb<Post>` AutoQuery Service and adds high-level functionality for `AnyTechnologyIds` and `Is` custom high-level properties that's used to query multiple columns behind-the-scenes.

In addition to inheriting all default Querying functionality in a `QueryDb<Post>` AutoQuery Service, the custom implementation also:

 - Prevents returning any `Deleted` Posts
 - Prevents returning any posts with a `closed` status unless the query specifically targets a closed label or status
 - Avoids any table joins by using PostgreSQL advanced Array data type for querying post `string` **labels** or `int` **technology ids**
 - Uses `AnyTechnologyIds` to return any posts **tagged with** the specified technologies

```csharp
[Route("/posts", "GET")]
public class QueryPosts : QueryDb<Post>
{
    // Handled by AutoQuery
    public int[] Ids { get; set; }
    public int? OrganizationId { get; set; }
    public int[] OrganizationIds { get; set; }
    public string[] Types { get; set; }

    // Handled by Custom Implementation
    public int[] AnyTechnologyIds { get; set; }
    public string[] Is { get; set; }
}

[CacheResponse(Duration = 600)]
public class PostPublicServices(IAutoQueryDb autoQuery) : Service
{
    public object Any(QueryPosts request)
    {
        using var db = autoQuery.GetDb(query, base.Request);
        var q = autoQuery.CreateQuery(query, base.Request, db) //Populated SqlExpression

        q.Where(x => x.Deleted == null);
        
        var states = request.Is ?? TypeConstants.EmptyStringArray;
        if (states.Contains("closed") || states.Contains("completed") || states.Contains("declined"))
            q.And(x => x.Status == "closed");
        else
            q.And(x => x.Hidden == null && (x.Status == null || x.Status != "closed"));

        if (states.Length > 0)
        {
            var labelSlugs = states.Where(x => x != "closed" && x != "open")
                .Map(x => x.GenerateSlug());
            if (labelSlugs.Count > 0)
                q.And($"{PgSql.Array(labelSlugs)} && labels");
        }

        if (!request.AnyTechnologyIds.IsEmpty())
        {
            q.And($"{PgSql.Array(request.AnyTechnologyIds)} && technology_ids");
        }

        return AutoQuery.Execute(request, q, base.Request);
    }
}
```

The above implementation also caches all `QueryPosts` responses as a result of being defined in a Service annotated with [`[CacheResponse]` attribute](/cacheresponse-attribute).

### IAutoQueryDb API

To increase the versatility of using AutoQuery functionality in custom Service implementations, `IAutoQueryDb` supports both parallel Sync and Async APIs 
if needing to enlist AutoQuery functionality in Sync methods that are unable to be refactored to use the async APIs:

```csharp
public interface IAutoQueryDb : IAutoCrudDb
{
    // Generic API to resolve the DB Connection to use for this request
    IDbConnection GetDb<From>(IRequest req = null);

    // Generate a populated and Typed OrmLite SqlExpression using same model as the source and output target
    SqlExpression<From> CreateQuery<From>(IQueryDb<From> dto, Dictionary<string, string> dynamicArgs,
        IRequest req = null, IDbConnection db = null);

    // Execute an OrmLite SqlExpression using the same model as the source and output target
    QueryResponse<From> Execute<From>(IQueryDb<From> model, SqlExpression<From> query, 
        IRequest req = null, IDbConnection db = null);

    // Async Execute an OrmLite SqlExpression using the same model as the source and output target
    Task<QueryResponse<From>> ExecuteAsync<From>(IQueryDb<From> model, SqlExpression<From> query, 
        IRequest req = null, IDbConnection db = null);

    // Generate a populated and Typed OrmLite SqlExpression using different models for source & output target
    SqlExpression<From> CreateQuery<From,Into>(IQueryDb<From,Into> dto, Dictionary<string,string> dynamicArgs,
        IRequest req = null, IDbConnection db = null);

    // Execute an OrmLite SqlExpression using different models for source and output target
    QueryResponse<Into> Execute<From, Into>(IQueryDb<From,Into> model, SqlExpression<From> query, 
        IRequest req = null, IDbConnection db = null);

    // Async Execute an OrmLite SqlExpression using different models for source and output target
    Task<QueryResponse<Into>> ExecuteAsync<From, Into>(IQueryDb<From,Into> model, SqlExpression<From> query, 
        IRequest req = null, IDbConnection db = null);
}
```

The `IAutoQueryDb` inherits `IAutoCrudDb` APIs below and can access both AutoQuery and CRUD functionality.

Likewise the new AutoQuery Crud APIs also have sync & async implementations:

```csharp
public interface IAutoCrudDb
{
    // Inserts new entry into Table
    object Create<Table>(ICreateDb<Table> dto, IRequest req);
    
    // Inserts new entry into Table Async
    Task<object> CreateAsync<Table>(ICreateDb<Table> dto, IRequest req);
    
    // Updates entry into Table
    object Update<Table>(IUpdateDb<Table> dto, IRequest req);
    
    // Updates entry into Table Async
    Task<object> UpdateAsync<Table>(IUpdateDb<Table> dto, IRequest req);
    
    // Partially Updates entry into Table (Uses OrmLite UpdateNonDefaults behavior)
    object Patch<Table>(IPatchDb<Table> dto, IRequest req);
    
    // Partially Updates entry into Table Async (Uses OrmLite UpdateNonDefaults behavior)
    Task<object> PatchAsync<Table>(IPatchDb<Table> dto, IRequest req);
    
    // Deletes entry from Table
    object Delete<Table>(IDeleteDb<Table> dto, IRequest req);
    
    // Deletes entry from Table Async
    Task<object> DeleteAsync<Table>(IDeleteDb<Table> dto, IRequest req);

    // Inserts or Updates entry into Table
    object Save<Table>(ISaveDb<Table> dto, IRequest req);

    // Inserts or Updates entry into Table Async
    Task<object> SaveAsync<Table>(ISaveDb<Table> dto, IRequest req);
}
```

Due to its internal pre-defined behavior, AutoQuery CRUD custom Service implementations have limited customizability over its implementation but still allows you to apply custom logic like apply Custom Filter Attributes, include additional validation, augment the Response DTO, etc.

E.g. This implementation applies the `[ConnectionInfo]` behavior to all its Services which will instead execute queries on the registered Reporting named connection:

```csharp
[ConnectionInfo(NamedConnection = "Reporting")]
public class MyReportingServices(IAutoQueryDb autoQuery) : Service
{
    public Task<object> Any(CreateReport request) => autoQuery.CreateAsync(request,base.Request);
}
```

### AutoQuery Response Filters

The Aggregate functions feature is built on the new `ResponseFilters` support in AutoQuery which provides a new extensibility option enabling customization and additional metadata to be attached to AutoQuery Responses. As the Aggregate Functions support is itself a Response Filter in can disabled by clearing them:

```csharp
Plugins.Add(new AutoQueryFeature {
    ResponseFilters = new List<Action<QueryFilterContext>>()
})
```

The Response Filters are executed after each AutoQuery and gets passed the full context of the executed query, i.e:

```csharp
class QueryFilterContext
{
    IDbConnection Db             // The ADO.NET DB Connection
    List<Command> Commands       // Tokenized list of commands
    IQuery Request               // The AutoQuery Request DTO
    ISqlExpression SqlExpression // The AutoQuery SqlExpression
    IQueryResponse Response      // The AutoQuery Response DTO
}
```

Where the `Commands` property contains the parsed list of commands from the `Include` property, tokenized into the structure below:

```csharp
class Command 
{
    string Name
    List<string> Args
    string Suffix
}
```

With this we could add basic calculator functionality to AutoQuery with the custom Response Filter below:

```csharp
Plugins.Add(new AutoQueryFeature {
    ResponseFilters = {
        ctx => {
            var supportedFns = new Dictionary<string, Func<int, int, int>>(StringComparer.OrdinalIgnoreCase)
            {
                {"ADD",      (a,b) => a + b },
                {"MULTIPLY", (a,b) => a * b },
                {"DIVIDE",   (a,b) => a / b },
                {"SUBTRACT", (a,b) => a - b },
            };
            var executedCmds = new List<Command>();
            foreach (var cmd in ctx.Commands)
            {
                Func<int, int, int> fn;
                if (!supportedFns.TryGetValue(cmd.Name, out fn)) continue;
                var label = !string.IsNullOrWhiteSpace(cmd.Suffix) ? cmd.Suffix.Trim() : cmd.ToString();
                ctx.Response.Meta[label] = fn(int.Parse(cmd.Args[0]), int.Parse(cmd.Args[1])).ToString();
                executedCmds.Add(cmd);
            }
            ctx.Commands.RemoveAll(executedCmds.Contains);
        }        
    }
})
```

Which now lets users perform multiple basic arithmetic operations with any AutoQuery request!

```csharp
var response = client.Get(new QueryRockstars {
    Include = "ADD(6,2), Multiply(6,2) SixTimesTwo, Subtract(6,2), divide(6,2) TheDivide"
});

response.Meta["ADD(6,2)"]      //= 8
response.Meta["SixTimesTwo"]   //= 12
response.Meta["Subtract(6,2)"] //= 4
response.Meta["TheDivide"]     //= 3
```

### Untyped SqlExpression

If you need to introspect or modify the executed `ISqlExpression`, it’s useful to access it as a `IUntypedSqlExpression` so its non-generic API's are still accessible without having to convert it back into its concrete generic `SqlExpression<T>` Type, e.g:

```csharp
IUntypedSqlExpression q = ctx.SqlExpression.GetUntypedSqlExpression()
    .Clone();
```

::: info
Cloning the SqlExpression allows you to modify a copy that won't affect any other Response Filter.
:::

### AutoQuery Property Mapping

AutoQuery can map `[DataMember]` property aliases on Request DTO's to the queried table, e.g:

```csharp
public class QueryPerson : QueryDb<Person>
{
    [DataMember(Name = "first_name")]
    public string FirstName { get; set; }
}

public class Person
{
    public int Id { get; set; }
    public string FirstName { get; set; }
    public string LastName { get; set; }
}
```

Which can be queried with:

```
?first_name=Jimi
```

or by setting the global `JsConfig.Init(Config { TextCase = TextCase.SnakeCase })` convention:

```csharp
public class QueryPerson : QueryDb<Person>
{
    public string LastName { get; set; }
}
```

Where it's also queryable with:

```
?last_name=Hendrix
```

## Extensibility with QueryFilters

We've already covered some of extensibility options with Customizable **QueryDbFields** and **Implicit Conventions**, the most customizable would be to override the default implementation with a custom one, e.g:

```csharp
public class MyQueryServices(IAutoQueryDb autoQuery) : Service
{
    //Override with custom implementation
    public object Any(FindMovies dto)
    {
        var q = autoQuery.CreateQuery(dto, Request.GetRequestParams(), base.Request);
        return autoQuery.Execute(dto, q, base.Request);
    }
}
```

There's also a lighter weight option by registering a typed Query Filter, e.g:

```csharp
var autoQuery = new AutoQueryFeature()
  .RegisterQueryFilter<QueryRockstarsFilter, Rockstar>((q, dto, req) =>
      q.And(x => x.LastName.EndsWith("son"))
  )
  .RegisterQueryFilter<IFilterRockstars, Rockstar>((q, dto, req) =>
      q.And(x => x.LastName.EndsWith("son"))
  );

Plugins.Add(autoQuery);
```

Registering an interface like `IFilterRockstars` is especially useful as it enables applying custom logic to a number of different Query Services sharing the same interface. 

## Intercept and Introspect Every Query

As mentioned earlier AutoQuery works by auto-generating ServiceStack Services for each Request DTO marked with `IQueryDb` unless a custom implementation has been defined for that Query. It's also possible to change the base class for the generated services so that all queries execute your custom implementation instead.

To do this, create a custom Service that inherits from `AutoQueryServiceBase` and overrides both `Exec` methods with your own implementation, e.g:

```csharp
public abstract class MyAutoQueryServiceBase : AutoQueryServiceBase
{
    public override object Exec<From>(IQueryDb<From> dto)
    {
        var q = AutoQuery.CreateQuery(dto, Request.GetRequestParams(), base.Request);
        return AutoQuery.Execute(dto, q, base.Request);
    }

    public override object Exec<From, Into>(IQueryDb<From, Into> dto)
    {
        var q = AutoQuery.CreateQuery(dto, Request.GetRequestParams(), base.Request);
        return AutoQuery.Execute(dto, q, base.Request);
    }
}
```

Then tell AutoQuery to use your base class instead, e.g:

```csharp
Plugins.Add(new AutoQueryFeature { 
    AutoQueryServiceBaseType = typeof(MyAutoQueryServiceBase)
});
```

Which will now get AutoQuery to execute your implementations instead.

## Exclude AutoQuery Collections from being initialized

The default configuration for all languages supported in
[Add ServiceStack Reference](/add-servicestack-reference) 
is to 
[InitializeCollections](/csharp-add-servicestack-reference#initializecollections)
which allows for a nicer client API in which clients can assume Request DTO's have their collections 
initialized allowing them to use the shorthand collection initializer syntax, e.g:

```csharp
var response = client.Get(new SearchQuestions { 
    Tags = { "redis", "ormlite" }
});
```

## AutoQuery CRUD Batch Requests

All AutoQuery CRUD operations support auto batch implementations which will by default execute all AutoQuery CRUD Requests within a DB transaction.

By default it will generate AutoBatch implementations for all CRUD operations and can be changed to only generate implementations for specific CRUD operations by changing:

```csharp
Plugins.Add(new AutoQueryFeature {
    GenerateAutoBatchImplementationsFor = new() { AutoCrudOperation.Create }
});
```

It also wont generate implementations for custom AutoBatch implementations, e.g. you can add a custom implementation that does what the generated implementation would've done and execute using the same DB Connection and Transaction with:

```csharp
public class CustomAutoQueryServices(IAutoQueryDb autoQuery) : Service
{
    public object Any(CreateItem[] requests)
    {
        using var db = autoQuery.GetDb<Item>(Request);
        using var dbTrans = db.OpenTransaction();

        var results = new List<object>();
        foreach (var request in requests)
        {
            var response = await autoQuery.CreateAsync(request, Request, db);
            results.Add(response);
        }

        dbTrans.Commit();
        return results;            
    }
}
```

As AutoQuery Services are normal ServiceStack Services they can re-use the existing Service Client support for [Auto Batched Requests](/auto-batched-requests), e.g:

```csharp
var client = new JsonApiClient(BaseUrl);
var response = client.SendAll(new CreateItem[] { ... });
```

<auto-query-examples class="not-prose"></auto-query-examples>


# AutoQuery Data
Source: https://docs.servicestack.net/autoquery/data

AutoQuery Data is a new implementation that closely follows the dev model you're used to with [AutoQuery RDBMS](/autoquery/rdbms)
where any experience gained in creating RDBMS AutoQuery Services previously are now also applicable to 
Querying alternative data sources as well.

### Getting Started

The AutoQuery Data Feature is enabled by registering:

```csharp
Plugins.Add(new AutoQueryDataFeature { MaxLimit = 100 });
```

### Learn Once, Query Everywhere 

All features from [AutoQuery RDBMS](/autoquery/rdbms) except for the RDBMS-specific 
[Joining Tables](/autoquery#joining-tables) and
[Raw SQL Filters](/autoquery#raw-sql-filters) features
also have an equivalent in AutoQuery Data as well. 

Like AutoQuery you can declaratively create AutoQuery Data Services using just Request DTO's but instead of 
inheriting from `QueryDb<T>` you'd instead inherit from `QueryData<T>`, e.g:

```csharp
//AutoQuery RDBMS
public class QueryCustomers : QueryDb<Customer> {}

//AutoQuery Data - Multiple / Open Data Sources 
public class QueryCustomers : QueryData<Customer> {}
```

The API to call and consume both RDBMS AutoQuery and AutoQuery Data Services are indistinguishable to 
external clients where both are queried using the same 
[implicit](/autoquery#implicit-conventions) and
[explicit conventions](/autoquery#explicit-conventions)
and both return the same `QueryResponse<T>` Response DTO. 

### Use AutoQuery Viewer

A direct result of this means you can reuse [AutoQuery Viewer](https://github.com/ServiceStack/Admin) 
to access a rich auto UI for querying all AutoQuery implementations together in the same UI, whether queries are served from an RDBMS or an alternative data source.

[![](https://raw.githubusercontent.com/ServiceStack/Admin/master/img/query-default-values.png)](https://github.com/ServiceStack/Admin)


## AutoQuery Data Sources

AutoQuery Data supports an Open Data provider model requiring an extra piece of configuration Services 
need to function - the Data Source that it will query. Data Sources are registered with the 
`AutoQueryDataFeature` plugin by calling using its fluent `AddDataSource()` API to register all Data Sources 
you want available to query. 

At launch there are 3 different data sources that are available - all of which are accessible as 
extension methods on the `QueryDataContext` parameter for easy discoverability:

```csharp
Plugins.Add(new AutoQueryDataFeature()
    .AddDataSource(ctx => ctx.MemorySource(...))
    .AddDataSource(ctx => ctx.ServiceSource(...))
    .AddDataSource(ctx => ctx.DynamoDBSource(...))
);
```

AutoQuery Data Open Provider model supports querying of multiple data source back-ends. The 3 data source providers available include:

 - [AutoQuery Memory](/autoquery/memory) - for querying static or dynamic in-memory .NET collections, some example uses include showing querying a flat-file **.csv** file and querying a throttled 3rd Party API with it's built-in configurable caching.
 - [AutoQuery Service](/autoquery/service) - a step higher than `MemorySource` where you can decorate the response of existing Services with AutoQuery's rich querying capabilities.
 - [AutoQuery DynamoDB](/autoquery/dynamodb) - adds rich querying capabilities over an AWS DynamoDB Table, offering a leap of greater productivity than constructing DynamoDB queries manually.


# AutoQuery Memory Data Source
Source: https://docs.servicestack.net/autoquery/memory

The simplest data source we can query is an in-memory .NET collection registered with `ctx.MemorySource()`. 
But how the collection is populated remains up to you. The example below shows registering collections from 
multiple sources inc. **in-line code**, populated **from a CSV file** (utilizing ServiceStack's 
CSV deserialization support) and populated **from a 3rd Party API** using 
[HTTP Utils](/http-utils):

```csharp
//Declaration in code
var countries = new[] {
    new Country { ... },
    new Country { ... },
};

//From CSV File
List<Currency> currencies = File.ReadAllText("currencies.csv").FromCsv<List<Currency>>();

//From 3rd Party API
List<GithubRepo> repos = "https://api.github.com/orgs/ServiceStack/repos"
    .GetJsonFromUrl(req => req.UserAgent="AutoQuery").FromJson<List<GithubRepo>>();

//AutoQuery Data Plugin
Plugins.Add(new AutoQueryDataFeature { MaxLimit = 100 }
    .AddDataSource(ctx => ctx.MemorySource(countries))
    .AddDataSource(ctx => ctx.MemorySource(currencies))
    .AddDataSource(ctx => ctx.MemorySource(repos))
);
```

After data sources are registered, you can then create AutoQuery Data Services to query them:

```csharp
[Route("/countries")]
public class QueryCountries : QueryData<Country> {}

[Route("/currencies")]
public class QueryCurrencies : QueryData<Currency> {}

[Route("/repos")]
public class QueryGithubRepos : QueryData<GithubRepo> {}
```

With just the empty Request DTO's above they're now queryable like any other AutoQuery Service, e.g:

   - /countries?code=AU
   - /currencies.json?code=AUD
   - /repos.csv?watchers_count>=100&orderBy=-watchers_count,name&fields=name,homepage,language


## Queryable PocoDataSource

**PocoDataSource** is useful for quickly creating an In Memory Queryable Data Source as done in the [TODOs MVC Jamstack Examples](/templates/jamstack#todos-mvc):

```csharp
public class TodosServices : Service
{
    public IAutoQueryData AutoQuery { get; set; }

    static readonly PocoDataSource<Todo> Todos = PocoDataSource.Create(new Todo[]
    {
        new () { Id = 1, Text = "Learn" },
        new () { Id = 2, Text = "Blazor", IsFinished = true },
        new () { Id = 3, Text = "WASM!" },
    }, nextId: x => x.Select(e => e.Id).Max());

    public object Get(QueryTodos query)
    {
        var db = Todos.ToDataSource(query, Request);
        return AutoQuery.Execute(query, AutoQuery.CreateQuery(query, Request, db), db);
    }

    public Todo Post(CreateTodo request)
    {
        var newTodo = new Todo { Id = Todos.NextId(), Text = request.Text };
        Todos.Add(newTodo);
        return newTodo;
    }

    public Todo Put(UpdateTodo request)
    {
        var todo = request.ConvertTo<Todo>();
        Todos.TryUpdateById(todo, todo.Id);
        return todo;
    }

    // Handles Deleting the Todo item
    public void Delete(DeleteTodo request) => Todos.TryDeleteById(request.Id);

    public void Delete(DeleteTodos request) => Todos.TryDeleteByIds(request.Ids);
}
```

Where it provides ThreadSafe CRUD operations to manage a collection of In Memory POCOs. 

### In Memory AutoQuery

The `QueryTodos` implementation utilizes an [AutoQuery Memory Source](/autoquery/memory) with the full capabilities of AutoQuery's [Implicit Conventions](/autoquery/rdbms#implicit-conventions):

 - [/api/QueryTodos?Id>=1](https://vue-vite-api.jamstacks.net/api/QueryTodos?Id>=1)
 - [/api/QueryTodos?TextContains=Blazor](https://vue-vite-api.jamstacks.net/api/QueryTodos?TextContains=Blazor)
 - [/api/QueryTodos?IsFinished=false](https://vue-vite-api.jamstacks.net/api/QueryTodos?IsFinished=false)

Where it can be used to iteratively prototype new data models under a productive **dotnet watch** workflow until it satisfies all your requirements where it could be easily converted to [AutoQuery CRUD](/autoquery/crud) APIs and integrated with your Systems configured RDBMS - which would require even less code.

### Cacheable Data Sources

The examples above provides a nice demonstration of querying static memory collections. But Data Sources 
offers even more flexibility where you're also able to query and cache dynamic .NET collections that 
are customizable per-request.

The registration below shows an example of this where results are dynamically fetched from **GitHub's API** 
and persisted in the **local in-memory cache** for **5 minutes** - throttling the number of requests made 
to the external 3rd Party API:

```csharp
.AddDataSource(ctx => ctx.MemorySource(() => 
 $"https://api.github.com/repos/ServiceStack/{ctx.Request.GetParam("repo")}/contributors"
   .GetJsonFromUrl(req => req.UserAgent="AutoQuery").FromJson<List<GithubContributor>>(),
  HostContext.LocalCache, 
  TimeSpan.FromMinutes(5)
));
```

We can now create an AutoQuery Data Service to query the above cached `GithubContributor` Memory Source:

```csharp
[Route("/contributors")]
public class QueryContributors : QueryData<GithubContributor>
{
    public string Repo { get; set; }
}
```

Thanks to the Typed Request DTO we also get an end-to-end Typed API for free which we can use to query 
the contributors result-set returned from GitHub's API. As an example we can view the 
**Top 20 Contributors** for the **ServiceStack** Project with:

```csharp
var top20Contributors = client.Get(new QueryContributors {
    Repo = "ServiceStack",
    OrderByDesc = "Contributions",
    Take = 20
});

top20Contributors.PrintDump(); // Pretty print results to Console
```


# AutoQuery Service Data Source
Source: https://docs.servicestack.net/autoquery/service

The next step after [MemorySource](/autoquery/memory) in querying for even richer result-sets, whether you want to add custom validation, access multiple dependencies, construct complex queries or other custom business logic, you can use a **Service Source** instead which lets you call a Service and use its Response as the dynamic Data Source that you can apply Auto Querying logic on.

`ServiceSource` is very similar to `MemorySource` however instead of passing in the in-memory collection 
you want to query directly, you'll need to pass a **Request DTO** of the Service you want called instead.
The response of the Service is then further queried just as if its results were passed into a MemorySource 
directly.

We'll illustrate with a few examples how to register and use ServiceSources, explore some of their capabilities 
and provide some examples of when you may want to use them below. 

## Register Data Sources

The `UserLogin` ServiceSource shows you can just pass an empty Request DTO as-is to execute its Service. 
The `RockstarAlbum` and `GithubRepo` Service Sources are however leveraging the built-in
[Auto Mapping](/auto-mapping) to copy any matching 
properties from the AutoQuery Request DTO to the downstream `GetRockstarAlbums` and `GetGithubRepos` 
Request DTO's. Finally the responses for the `GithubRepo` Service is **cached for 5 minutes** so any 
subsequent matching requests end up querying the cached result set instead of re-executing the `GetGithubRepos` 
Service:

```csharp
Plugins.Add(new AutoQueryDataFeature { MaxLimit = 100 }
    .AddDataSource(ctx => ctx.ServiceSource<UserLogin>(new GetTodaysUserActivity())),
    .AddDataSource(ctx => ctx.ServiceSource<RockstarAlbum>(ctx.Dto.ConvertTo<GetRockstarAlbums>())),
    .AddDataSource(ctx => ctx.ServiceSource<GithubRepo>(ctx.Dto.ConvertTo<GetGithubRepos>(), 
        HostContext.Cache, TimeSpan.FromMinutes(5)));
);
```

The implementation of `GetTodaysUserActivity` Service uses an async OrmLite RDBMS call to get all User Logins 
within the last day, fetches the Live Activity data from Redis, then 
[merges the disconnected POCO result sets](/ormlite/reference-support#merge-disconnected-poco-result-sets)
into the `UserLogin` POCO which it returns:

```csharp
[Route("/useractivity/today")]
public class QueryTodaysUserActivity : QueryData<UserLogin> {}

public async Task<List<UserLogin>> Any(GetTodaysUserActivity request)
{
    var logins = await Db.SelectAsync<UserLogin>(x => x.LastLogin >= DateTime.UtcNow.AddDays(-1));
    var activities = Redis.As<Activity>().GetAll();
    logins.Merge(activities);
    return logins;
}
```

## GetRockstarAlbums

The `GetRockstarAlbums` Service shows an example of a calling an existing ad hoc DB Service executing an 
arbitrary custom Query. It uses the Request DTO Auto-Mapping at the `ServiceSource` registration to 
first copy any matching properties from the initial `QueryRockstarAlbums` Request DTO to populate a new 
`GetRockstarAlbums` instance which is what's used to execute the Service with. 

In this way the `QueryRockstarAlbums` AutoQuery Service is essentially decorating the underlying 
`GetRockstarAlbums` Service giving it access to AutoQuery features where clients are able to apply 
further post-querying server logic to an existing Service implementation which now lets them filter, 
sort, select only a partial list of fields, include additional aggregate queries, etc.

```csharp
public class QueryRockstarAlbums : QueryData<RockstarAlbum> 
{
    public string Name { get; set; }
    public int[] IdBetween { get; set; }
}

public object Any(GetRockstarAlbums request)
{
    var q = Db.From<RockstarAlbum>();

    if (request.IdBetween != null)
        q.Where(x => x.Id >= request.IdBetween[0] && x.Id <= request.IdBetween[1]);

    if (request.Name != null)
        q.Where(x => x.Name == request.Name);

    return new GetRockstarAlbumsResponse { Results = Db.Select(q) };
}
```

One thing to notice is that ServiceSource still works whether the results are wrapped in a Response DTO 
instead of a naked `IEnumerable<RockstarAlbum>` collection. This is transparently supported as `ServiceSource` 
will use the first matching `IEnumerable<T>` property for Services that don't return a collection.

It should be noted that decorating an existing OrmLite Service is rarely necessary as in most cases you'll
be able to get by with just a simple AutoQuery RDBMS query as seen in the Service below which replaces 
the above 2 Services:

```csharp
public class QueryRockstarAlbums : QueryDb<RockstarAlbum> {}
```

## GetGithubRepos

The final `GetGithubRepos` ServiceSource example shows an example of a slightly more complex implementation
than a single 3rd Party API call where it adds custom validation logic and call different 3rd Party API 
Endpoints depending on user input:

```csharp
public class QueryGithubRepo : QueryData<GithubRepo> 
{
    public string User { get; set; }
    public string Organization { get; set; }
}

public object Get(GetGithubRepos request)
{
    if (request.User == null && request.Organization == null)
        throw new ArgumentNullException("User");

    var url = request.User != null
        ? $"https://api.github.com/users/{request.User}/repos"
        : $"https://api.github.com/orgs/{request.Organization}/repos";

    return url.GetJsonFromUrl(requestFilter:req => req.UserAgent = GetType().Name)
        .FromJson<List<GithubRepo>>();
}
```

A hidden feature ServiceSources are naturally able to take advantage of due to its behind-the-scenes usage 
of the new [Service Gateway](/service-gateway) is that the exact code above could still function if the
`QueryGithubRepo` AutoQuery Data Service and underlying `GetGithubRepos` Service were moved to different
hosts :)

## Custom AutoQuery Data Implementation

Just like you can 
[Create a Custom implementation](/autoquery#custom-autoquery-implementations)
in AutoQuery, you can do the same in AutoQuery Data by just defining an implementation for your AutoQuery 
Data Request DTO. But instead of `IAutoQueryDb` you'd reference the `IAutoQueryData` dependency to construct 
and execute your custom AutoQuery Data query.

When overriding the default implementation of an AutoQuery Data Service you also no longer need to register 
a Data Source as you can specify the Data Source in-line when calling `AutoQuery.CreateQuery()`.

For our custom AutoQuery Data implementation we'll look at creating a useful Service which reads the
daily CSV Request and Error Logs from the new [CsvRequestLogger](/request-logger#csv-request-logger) and queries it by 
wrapping the POCO `RequestLogEntry` results into a `MemoryDataSource`:

```csharp
[Route("/query/requestlogs")]
[Route("/query/requestlogs/{Date}")]
public class QueryRequestLogs : QueryData<RequestLogEntry>
{
    public DateTime? Date { get; set; }
    public bool ViewErrors { get; set; }
}

public class CustomAutoQueryDataServices : Service
{
    public IAutoQueryData AutoQuery { get; set; }

    public object Any(QueryRequestLogs query)
    {
        var date = query.Date.GetValueOrDefault(DateTime.UtcNow);
        var logSuffix = query.ViewErrors ? "-errors" : "";
        var csvLogsFile = VirtualFileSources.GetFile(
            "requestlogs/{0}-{1}/{0}-{1}-{2}{3}.csv".Fmt(
                date.Year.ToString("0000"),
                date.Month.ToString("00"),
                date.Day.ToString("00"),
                logSuffix));

        if (csvLogsFile == null)
            throw HttpError.NotFound("No logs found on " + date.ToShortDateString());

        var logs = csvLogsFile.ReadAllText().FromCsv<List<RequestLogEntry>>();

        var db = new MemoryDataSource<RequestLogEntry>(logs, query, Request);
        var q = AutoQuery.CreateQuery(query, Request, db);
        return AutoQuery.Execute(query, q, db);
    }
}
```

This Service now lets you query the Request Logs of any given day, letting you filter, page and sort 
through the Request Logs of the day. While we're at it, let's also create multiple Custom AutoQuery 
Data implementations to act as canonical smart links for the above Service:

```csharp
[Route("/logs/today")]
public class TodayLogs : QueryData<RequestLogEntry> { }
[Route("/logs/today/errors")]
public class TodayErrorLogs : QueryData<RequestLogEntry> { }

[Route("/logs/yesterday")]
public class YesterdayLogs : QueryData<RequestLogEntry> { }
[Route("/logs/yesterday/errors")]
public class YesterdayErrorLogs : QueryData<RequestLogEntry> { }
```

The implementations of which just delegates to `QueryRequestLogs` with the selected Date and whether or 
not to show just the error logs:

```csharp
public object Any(TodayLogs request) =>
    Any(new QueryRequestLogs { Date = DateTime.UtcNow });

public object Any(TodayErrorLogs request) =>
    Any(new QueryRequestLogs { Date = DateTime.UtcNow, ViewErrors = true });

public object Any(YesterdayLogs request) =>
    Any(new QueryRequestLogs { Date = DateTime.UtcNow.AddDays(-1) });

public object Any(YesterdayErrorLogs request) =>
    Any(new QueryRequestLogs { Date = DateTime.UtcNow.AddDays(-1), ViewErrors = true });
```

## View Request Logs in [AutoQuery Viewer](https://github.com/ServiceStack/Admin)

And with no more effort we can jump back to `/ss_admin/` and use [AutoQuery Viewer's](https://github.com/ServiceStack/Admin) nice UI to quickly 
inspect Todays and Yesterdays Request and Error Logs :)

![](https://raw.githubusercontent.com/ServiceStack/Assets/master/img/release-notes/autoqueryviewer-csv-logs.png)


# AutoQuery DynamoDB Data Source
Source: https://docs.servicestack.net/autoquery/dynamodb

AutoQuery Data's `DynamoDbSource` provides the most productive development experience for effortlessly creating rich, queryable and optimized Services for [DynamoDB data stores](https://aws.amazon.com/dynamodb/).

[![](https://raw.githubusercontent.com/ServiceStack/Assets/master/img/release-notes/dynamodb-banner.png)](/aws-pocodynamo)

DynamoDB is the near perfect solution if you're on AWS and in need of a managed NoSQL data storage solution 
that can achieve near-infinite scale whilst maintaining constant single-digit millisecond performance. 
The primary issue with DynamoDB however is working with it's unstructured schema and API's which is reflected 
in the official .NET DynamoDB client providing a flexible but low-level and cumbersome development experience 
to work with directly. Most of these shortcomings are resolved with our POCO-friendly 
[PocoDynamo](/aws-pocodynamo) client which provides an intuitive and idiomatic 
Typed .NET API that lets you reuse your DTO's and OrmLite POCO Data Models for persistence in DynamoDB.

Querying in DynamoDB is even more cumbersome, unlike an RDBMS which can process ad hoc queries on non-indexed 
fields with decent performance, every query in DynamoDB needs to be performed on an index defined ahead-of-time. 
Any queries not on an index needs to be sent as a Filter Expression and even more limiting is that queries 
can only be executed against rows containing the same hash id. If you need to query data spanning across 
multiple hash ids you either need to create a separate 
[Global Index](http://docs.aws.amazon.com/amazondynamodb/latest/developerguide/GSI.html) 
or perform a full 
[SCAN operation](http://docs.aws.amazon.com/amazondynamodb/latest/developerguide/QueryAndScan.html#QueryAndScan.Scan) 
which is even slower than full table scans on an RDBMS as they need to be performed on all underlying sharded 
nodes which can quickly eat up your reserved provisioned throughput allotted to your DynamoDB table.

## Optimal DynamoDB Queries

With AutoQuery's `DynamoDbSource` a lot of these nuances are transparently handled where it will automatically 
create the most optimal DynamoDB Query based on the fields populated on the incoming AutoQuery Request DTO. 
E.g. it will perform a 
[DynamoDB Query](http://docs.aws.amazon.com/amazondynamodb/latest/developerguide/QueryAndScan.html#QueryAndScan.Query)
when the **Hash** field is populated otherwise transparently falls back into a 
[Scan Operation](http://docs.aws.amazon.com/amazondynamodb/latest/developerguide/QueryAndScan.html#QueryAndScan.Scan). 
Any conditions that query an Index field are added to the 
[Key Condition](http://docs.aws.amazon.com/amazondynamodb/latest/developerguide/QueryAndScan.html#QueryAndScan.Query), 
starting first with the **Range Key** (if specified), otherwise uses any populated **Local Indexes** it can 
find before any of the remaining conditions are added to the 
[Filter Expression](http://docs.aws.amazon.com/amazondynamodb/latest/developerguide/QueryAndScan.html#FilteringResults).

Transparently adopting the most optimal queries dramatically reduces development time as it lets you quickly
create, change and delete DynamoDB Services without regard for Indexes where it will often fallback to 
**SCAN** operations (performance of which is unnoticeable during development). Then once you're project is 
ready to deploy to production, go back and analyze all remaining queries your System relies on at the end 
then re-create tables with the appropriate indexes so that all App queries are efficiently querying an index.

::: info
When needed you can specify `.DynamoDbSource<T>(allowScans:false)` to disable anyone from executing SCAN 
requests when deployed to production
:::

## Download

To Get Started Install [ServiceStack's AWS Support package](https://github.com/ServiceStack/ServiceStack/tree/main/ServiceStack.Aws) from NuGet:

:::copy
`<PackageReference Include="ServiceStack.Aws" Version="8.*" />`
:::

## Simple AutoQuery Data Example

To illustrate how to use AutoQuery with DynamoDB we'll walk through a simple example of querying Rockstars Albums. 
For this example we'll specify
[explicit conventions](/autoquery#explicit-conventions)
so we can use ServiceStack's 
[typed .NET Service Clients](/csharp-client) 
to show which fields we're going to query and also lets us call the Service with a convenient typed API:

```csharp
[Route("/rockstar-albums")]
public class QueryRockstarAlbums : QueryData<RockstarAlbum>
{
    public int? Id { get; set; }         // Primary Key | Range Key
    public int? RockstarId { get; set; } // Foreign key | Hash Key
    public string Name { get; set; }
    public string Genre { get; set; }
    public int[] IdBetween { get; set; }
}
```

Here we see that creating DynamoDB Queries is no different to any other AutoQuery Data Service, where the 
same definition is used irrespective if the data source was populated from a `MemorySource`, `ServiceSource` 
or `DynamoDbSource` and the only thing that would need to change to have it query an RDBMS instead is the 
`QueryDb<T>` base class.

The text in comments highlight that when the `RockstarAlbum` POCO is stored in an RDBMS 
[OrmLite](https://github.com/ServiceStack/ServiceStack.OrmLite) 
creates the table with the `Id` as the Primary Key and `RockstarId` as a Foreign Key to the `Rockstar` table. 
This is different in DynamoDB where 
[PocoDynamo](/aws-pocodynamo) behavior is to keep related records together so
they can be efficiently queried and will instead Create the `RockstarAlbum` DynamoDB Table with the 
`RockstarId` as the Hash Key and its unique `Id` as the Range Key.

### Register DynamoDbSource

To use DynamoDB AutoQuery's you need to first configure 
[PocoDynamo](/aws-pocodynamo#download) 
which is just a matter of passing an an initialized `AmazonDynamoDBClient` and telling PocoDynamo which 
DynamoDB tables you intend to use:

```csharp
container.Register(c => new PocoDynamo(new AmazonDynamoDBClient(...))
    .RegisterTable<Rockstar>()
    .RegisterTable<RockstarAlbum>()
);
```

Then before using PocoDynamo, call `InitSchema()` to tell it to automatically go through and create all 
DynamoDB Tables that were registered but don't yet exist in DynamoDB: 

```csharp
var dynamo = container.Resolve<IPocoDynamo>();
dynamo.InitSchema();
```

So the first time `InitSchema()` is run it will create both `Rockstar` and `RockstarAlbum` tables but will 
no longer create any tables on any subsequent runs. After `InitSchema()` has completed we're assured that 
both `Rockstar` and `RockstarAlbum` tables exist so we can start using PocoDynamo's typed APIs to populate 
them with Data:

```csharp
dynamo.PutItems(new Rockstar[] { ... });
dynamo.PutItems(new RockstarAlbum[] { ... });
```

> Behind the scenes PocoDynamo efficiently creates the minimum number of 
[BatchWriteItem](http://docs.aws.amazon.com/amazondynamodb/latest/APIReference/API_BatchWriteItem.html)
requests as necessary to store all Rockstar and RockstarAlbum's.

Now that we have data we can query we can register the AutoQuery Data plugin along with the `Rockstar` 
and `RockstarAlbum` DynamoDB Tables we want to be able to query: 

```csharp
Plugins.Add(new AutoQueryDataFeature { MaxLimit = 100 }
    .AddDataSource(ctx => ctx.DynamoDbSource<Rockstar>())
    .AddDataSource(ctx => ctx.DynamoDbSource<RockstarAlbum>())
);
```

### RockstarAlbum POCO Table Definition

Where `RockstarAlbum` is just a simple POCO and can be used as-is throughout all of ServiceStack's libraries
inc. OrmLite, Redis, Caching Providers, Serializers, etc:

```csharp
public class RockstarAlbum
{
    [AutoIncrement]
    public int Id { get; set; }

    [References(typeof(Rockstar))]
    public int RockstarId { get; set; }

    [Index]
    public string Genre { get; set; }

    public string Name { get; set; }
}
```

PocoDynamo uses the same generic metadata attributes in **ServiceStack.Interfaces** as OrmLite. 

When this POCO is created in OrmLite it creates: 

 - A `RockstarAlbum` table with an `Id` auto incrementing **Primary Key**
 - The `RockstarId` as the **Foreign Key** for the `Rockstar` table 
 - Adds an **Index** on the `Genre` column. 

Whereas in DynamoDB, PocoDynamo creates: 

 - The `RockstarAlbum` table with the `Id` as an auto incrementing **Range Key**
 - The `RockstarId` as the **Hash Key** 
 - Creates a [Local Secondary Index](http://docs.aws.amazon.com/amazondynamodb/latest/developerguide/LSI.html) for the Genre attribute.

## Typed AutoQuery DynamoDB Queries

Since the properties we want to query are explicitly typed we can make use of ServiceStack's nice typed 
Service Client API's to call this Service and fetch Kurt Cobains **Grunge** Albums out of the first 5 recorded:

```csharp
var response = client.Get(new QueryRockstarAlbums { //QUERY 
    RockstarId = kurtCobainId, //Key Condition
    IdBetween = new[]{ 1, 5 }, //Key Condition
    Genre = "Grunge",          //Filter Condition
});

response.PrintDump(); // Pretty print results to Console
```

As illustrated in the comments, DynamoDB AutoQuery performs the most efficient DynamoDB Query required in 
order to satisfy this request where it will create a 
[Query Request](http://docs.aws.amazon.com/amazondynamodb/latest/developerguide/QueryAndScan.html#QueryAndScan.Query)
with the `RockstarId` and `IdBetween` conditions added to the **Key Condition** and the remaining `Genre`
added as a **Filter Expression**.

If we instead wanted to fetch all of Kurt Cobains **Grunge** Albums where there was no longer a condition on 
the Album `Id` **Range Key**, i.e:

```csharp
var response = client.Get(new QueryRockstarAlbums { //QUERY
    RockstarId = kurtCobainId, //Key Condition
    Genre = "Grunge",          //Key Condition
});
```

It would instead create a **Query Request** configured to use the Genre **Local Secondary Index** and have
added both `RockstarId` Hash Key and index `Genre` to the **Key Condition**.

But if you instead wanted to view all Grunge Albums, i.e:

```csharp
var response = client.Get(new QueryRockstarAlbums { //SCAN
    Genre = "Grunge"            //Filter Condition
});
```

As no Hash Key was specified it would instead create a **SCAN Request** where as there's no index, it adds 
all conditions to the **Filter Expression**.

## AutoQuery DynamoDB Global Index Queries

For times when you need to perform an efficient **Query Request** across multiple hash keys you will need to 
create a [Global Secondary Index](http://docs.aws.amazon.com/amazondynamodb/latest/developerguide/GSI.html).
Luckily this is easy to do in PocoDynamo where you can define Global Indexes with a simple POCO class definition:

```csharp
public class RockstarAlbumGenreIndex : IGlobalIndex<RockstarAlbum>
{
    [HashKey]
    public string Genre { get; set; }

    [RangeKey]
    public int Id { get; set; }

    public string Name { get; set; }    // projected property
    public int RockstarId { get; set; } // projected property
}
```

Global Indexes can be thought of as "automatically synced tables" specified with a different Hash Key. 
Just like DynamoDB tables you can specify the **Hash Key** you want to globally query and create the Index 
on as well as a separate **Range Key** you want to be able to perform efficient **Key Condition** queries on. 
You'll also want to specify any properties you want returned when querying the Global Index so they'll be 
automatically projected and stored with the Global Index, ensuring fast access.

Then to have PocoDynamo create the Global Index it should be referenced on the table the Global Index is on:

```csharp
[References(typeof(RockstarAlbumGenreIndex))]
public class RockstarAlbum { ... }
```

When referenced, `InitSchema()` will create the `RockstarAlbumGenreIndex` Global Secondary Index when it
creates the `RockstarAlbum` DynamoDB Table.

With the Global Index created we can now query it just like we would any other DynamoDB AutoQuery but instead
of querying a table, we query the Index instead:

```csharp
public class QueryRockstarAlbumsGenreIndex : QueryData<RockstarAlbumGenreIndex>
{
    public string Genre { get; set; }     // Hash Key
    public int[] IdBetween { get; set; }  // Range Key
    public string Name { get; set; }
}
```

Once defined you can query it just like any other AutoQuery Service where you're now able to perform 
efficient queries by **Genre** across all Rockstar Album's:

```csharp
var response = client.Get(new QueryRockstarAlbumsGenreIndex //QUERY
{
    Genre = "Grunge",              //Key Condition
    IdBetween = new[] { 1, 1000 }, //Key Condition
});
```

## Custom POCO Result Mappings

A noticeable difference from querying a Global Index instead of the Table directly is that results are
returned in a different `RockstarAlbumGenreIndex` POCO. Luckily we can use AutoQuery's 
[Custom Results Feature](/autoquery#returning-custom-results)
to map the properties back into the original table `RockstarAlbum` with:

```csharp
public class QueryRockstarAlbumsGenreIndex : QueryData<RockstarAlbumGenreIndex,RockstarAlbum> 
{ 
    public string Genre { get; set; }
    public int[] IdBetween { get; set; }
    public string Name { get; set; }
}
```

Now when we query the Index we get our results populated in `RockstarAlbum` DTO's instead:

```csharp
QueryResponse<RockstarAlbum> response = client.Get(new QueryRockstarAlbumsGenreIndex
{
    Genre = "Grunge",              //Key Condition
    IdBetween = new[] { 1, 1000 }, //Key Condition
});
```

## Caching AutoQuery Services

One of the many benefits of AutoQuery Services being just regular ServiceStack Services is that we get
access to ServiceStack's rich ecosystem of enhanced functionality around existing Services. An example added
in this release is ServiceStack's new HTTP Caching feature which lets you easily cache a Service with
the new `[CacheResponse]` attribute, letting you declaratively specify how long you want to cache identical 
requests for on the **Server** as well as a `MaxAge` option for instructing the **Client** how long they should
consider their local cache is valid for and any custom `Cache-Control` behavior you want them to have, e.g:

```csharp
[Route("/rockstar-albums")]
[CacheResponse(Duration = 60, MaxAge = 30, CacheControl = CacheControl.MustRevalidate)]
public class QueryRockstarAlbums : QueryData<RockstarAlbum>
{
    public int? Id { get; set; }         
    public int? RockstarId { get; set; }
    public string Genre { get; set; }
    public int[] IdBetween { get; set; }
}
```

So with just the above single Request DTO we've declaratively created a fully-queryable DynamoDB AutoQuery 
Service that transparently executes the most ideal DynamoDB queries for each request, has it's optimal 
representation efficiently cached on both Server and clients, whose Typed DTO can be reused as-is on the 
client to call Services with an end-to-end Typed API using any
[.NET Service Client](/csharp-client), 
that's also available to external developers in a clean typed API, natively in their preferred language of 
choice, accessible with just a right-click menu integrated inside VS.NET, Xcode, Android Studio, IntelliJ 
and Eclipse - serving both PCL Xamarin.iOS/Android as well as native iOS and Android developers by just  
[Adding a ServiceStack Reference](/add-servicestack-reference)
to the base URL of a remote ServiceStack Instance - all without needing to write any implementation!

## More Info

For more examples exploring different AutoQuery Data features checkout the
[AutoQuery Data Tests](https://github.com/ServiceStack/ServiceStack/blob/master/tests/ServiceStack.WebHost.Endpoints.Tests/AutoQueryDataTests.cs)
and [AutoQuery DynamoDB Tests](https://github.com/ServiceStack/ServiceStack/blob/master/tests/ServiceStack.WebHost.Endpoints.Tests/AutoQueryDataTests.Dynamo.cs)
that can be compared on a feature-by-feature basis against the existing
[AutoQuery Tests](https://github.com/ServiceStack/ServiceStack/blob/master/tests/ServiceStack.WebHost.Endpoints.Tests/AutoQueryTests.cs)
they were originally based on.


# AutoQuery CRUD
Source: https://docs.servicestack.net/autoquery/crud

AutoQuery Services includes support for implementing much of a CRUD Services logic declaratively, including support for multi-tenancy, 
optimistic concurrency, declarative validation, Auto Mapping external of Request/Respond DTOs to data model properties, 
auto populating then using full #Script Expressions that can be used for example to populate timestamps, 
authenticating user information, generating new UUIDs, etc.

Just like AutoQuery, CRUD Services are ServiceStack Services where you can continue using the same functionality to 
specify optimal user-defined routes for HTTP APIs, same Request/Response and Attribute filters to apply custom logic and 
continue enjoying the entire ecosystem around ServiceStack Services including being able to invoke them via 
[gRPC](/grpc/), [MQ endpoints](/messaging) and its rich client ecosystem for enabling end-to-end Typed APIs with 
[Add ServiceStack Reference](/add-servicestack-reference).

AutoQuery Services are fast & emit clean optimal "pure serialized POCO" wire-format, they're built on OrmLite's high-performance 
APIs where all AutoQuery APIs are `async` by default but also also offers native sync APIs if needing to enlist any of
AutoQuery's functionality in custom sync methods (that are unable to be converted into viral async APIs).

Importantly AutoQuery Services are "future-proofed" and can be overridden with a custom implementation that can either choose to augment 
the existing AutoQuery functionality and enhance it with custom behavior (e.g. if not possible to implement declaratively) or if needed its 
entire implementation can be replaced without breaking its design contract & existing client integrations, should it be necessary to
reimplement later if the Service needs to be constructed to use alternative data sources.

## Rapidly develop data-driven systems

As AutoQuery lets you declaratively develop Services by just defining their API Contract with POCO DTOs you're able to develop entire 
data-driven systems in a fraction of the time that it would take to implement them manually. In addition AutoQuery Services are semantically
richer as all capabilities are declaratively defined around typed data models which makes it possible to build higher-level generic features
like ServiceStack's Studio [Instant UI for AutoQuery Services](/studio-autoquery).

With AutoQuery you can now build entire Apps declaratively to develop high-performance capable Services accessible via ServiceStack's 
industry leading [myriad of Service endpoints](/why-servicestack#features-overview) and rich metadata services, all without needing to write any implementation!

For a sample of the productivity enabled checkout the [Bookings CRUD](https://github.com/NetCoreApps/BookingsCrud) demo to create a multi-user ASP.NET Core Booking System from scratch within minutes with full Audit History, fine-grained permissions, declarative validation, run adhoc queries & export to Excel by just defining code-first high-performance AutoQuery CRUD Typed APIs 

<lite-youtube class="w-full mx-4 my-4" width="560" height="315" videoid="rSFiikDjGos" style="background-image: url('https://img.youtube.com/vi/rSFiikDjGos/maxresdefault.jpg')"></lite-youtube>

## Creating AutoQuery CRUD Services

Just like [AutoQuery](/autoquery/rdbms), you just need to provide the typed Request DTOs definition for your DB Table APIs and 
AutoQuery automatically provides the implementation for the Service. 

To enlist Auto CRUD behavior your Request DTOs need to implement one of the following interfaces which dictates the behavior of the Service:

  - `ICreateDb<Table>` - Create new Table Entry
  - `IUpdateDb<Table>` - Update existing Table Entry 
  - `IPatchDb<Table>`  - Partially update existing Table Entry 
  - `IDeleteDb<Table>` - Delete existing Table Entry 

All Request DTOs also require either an `IReturn<T>` or `IReturnVoid` marker interface to specify the return type of the Service. 

::: info
Can use built-in `IReturn<EmptyResponse>` for an "empty" response where as `IReturnVoid` returns "no" response.
:::

Let's go through a simple example, starting with a simple POCO OrmLite data model we want to add to our RDBMS:

```csharp
public class Rockstar
{
    [AutoIncrement]
    public int Id { get; set; }
    public string FirstName { get; set; }
    public string LastName { get; set; }
    public int? Age { get; set; }
    public DateTime DateOfBirth { get; set; }
    public DateTime? DateDied { get; set; }
    public LivingStatus LivingStatus { get; set; }
}
```

We can create a Service that **inserts** a new `Rockstar` by defining all the properties we want to allow API consumers to provide when creating a new Rockstar:

```csharp
public class CreateRockstar : ICreateDb<Rockstar>, IReturn<CreateRockstarResponse> 
{
    public string FirstName { get; set; }
    public string LastName { get; set; }
    public int? Age { get; set; }
    public DateTime DateOfBirth { get; set; }
}

public class CreateRockstarResponse
{
    public int Id { get; set; } // Id is auto populated with RDBMS generated Id
    public ResponseStatus ResponseStatus { get; set; }
}
```

When ServiceStack starts it generates the implementation for this Service, which can now insert Rockstars using your populated Request DTO:

```csharp
var client = new JsonApiClient(baseUrl);

client.Post(new CreateRockstar {
    FirstName = "Kurt",
    LastName = "Cobain",
    Age = 27,
    DateOfBirth = new DateTime(20,2,1967),
});
```

Similarly you can define **Update** and **Delete** Services the same way, e.g:

```csharp
public class UpdateRockstar : Rockstar,
    IUpdateDb<Rockstar>, IReturn<UpdateRockstarResponse> {}

public class UpdateRockstarResponse
{
    public int Id { get; set; } // Id is auto populated with RDBMS generated Id
    public Rockstar Result { get; set; } // selects & returns latest DB Rockstar
    public ResponseStatus ResponseStatus { get; set; }
}
```

By convention if your Response DTO contains any of these properties it will be automatically populated:

 - `T Id` - The Primary Key
 - `T Result` - The POCO you want to return (can be a subset of DB model)
 - `int Count` - Return the number of rows affected (typically 1, but Deletes can be >1)

Delete Services need only a Primary Key, e.g:

```csharp
public class DeleteRockstar : IDeleteDb<Rockstar>, IReturnVoid 
{
    public int Id { get; set; }
}
```

and to Query the Rockstar table you have the [full featureset of AutoQuery](/autoquery/rdbms) for a complete set of CRUD Services without needing to provide any implementations.

## Custom AutoQuery CRUD Implementation

Just as you can create [Custom AutoQuery Implementations](/autoquery/rdbms.html#custom-autoquery-implementations) to override the default AutoQuery behavior
you can also override AutoQuery CRUD implementations by creating implementations with AutoQuery CRUD Request DTOs and calling the relevate `IAutoQueryDb` method, e.g:

```csharp
public class MyCrudServices(IAutoQueryDb autoQuery) : Service
{
    public object Post(CreateRockstar request) => autoQuery.Create(request, base.Request);
    public object Put(UpdateRockstar request) => autoQuery.Update(request, base.Request);
    public object Delete(DeleteRockstar request) => autoQuery.Delete(request, base.Request);
}

// Async
public class MyCrudServices(IAutoQueryDb autoQuery) : Service
{
    public Task<object> Post(CreateRockstar request) => autoQuery.CreateAsync(request, base.Request);
    public Task<object> Put(UpdateRockstar request) => autoQuery.UpdateAsync(request, base.Request);
    public Task<object> Delete(DeleteRockstar request) => autoQuery.DeleteAsync(request, base.Request);
}
```

### Custom implementations using OrmLite Typed APIs

It's not strictly necessary to use `IAutoQueryDb` APIs to implement custom AutoQuery implementations as you could instead use OrmLite to implement similar CRUD behavior, e.g:

```csharp
public class MyCrudServices : Service
{
    public object Post(CreateRockstar request) 
    {
        var id = (int) Db.Insert(request.ConvertTo<Rockstar>(), selectIdentity:true);
        return new CreateRockstarResponse {
            Id = id
        };
    }

    public object Put(UpdateRockstar request)
    {
        Db.UpdateNonDefaults(request.ConvertTo<Rockstar>(), x => x.Id == request.Id);
        return new UpdateRockstarResponse {
            Id = id,
            Result = Db.SingleById<Rockstar>(id),
        };
    }
    
    public void Delete(DeleteRockstar request)
    {
        Db.DeleteById<Rockstar>(request.Id);
    }
}
```

Async version:

```csharp
public class MyCrudServices : Service
{
    public async Task<object> Post(CreateRockstar request) 
    {
        var id = (int) await Db.InsertAsync(request.ConvertTo<Rockstar>(), selectIdentity:true);
        return new CreateRockstarResponse {
            Id = id
        };
    }

    public object Put(UpdateRockstar request)
    {
        await Db.UpdateNonDefaultsAsync(request.ConvertTo<Rockstar>(), x => x.Id == request.Id);
        return new UpdateRockstarResponse {
            Id = id,
            Result = await Db.SingleByIdAsync<Rockstar>(id),
        };
    }
    
    public Task Delete(DeleteRockstar request)
    {
        await Db.DeleteByIdAsync<Rockstar>(request.Id);
    }
}
```

The above are equivalents of typical AutoQuery CRUD APIs using OrmLite directly, however if the AutoQuery APIs includes [POCO references](/ormlite/reference-support), you'll need to OrmLite's `Save()` API to save the reference complex types as well, e.g:

```csharp
public class MyCrudServices : Service
{
    public object Post(CreateRockstar request) 
    {
        var row = request.ConvertTo<Rockstar>();
        Db.Save(row, references: true);
        return new CreateRockstarResponse {
            Id = row.Id
        };
    }
}
```

## AutoQuery CRUD Attributes

AutoQuery CRUD extends existing [querying functionality in AutoQuery](/autoquery/rdbms) with additional features covering common functionality in CRUD operations:

 - `[AutoApply]` - Apply built-in composite generic behavior
 - `[AutoPopulate]` - Populate data models with generic user & system info
 - `[AutoFilter]` - Apply pre-configured filters to query operations
 - `[AutoMap]` - Map System Input properties to Data Model fields
 - `[AutoDefault]` - Specify to fallback default values when not provided
 - `[AutoIgnore]` - Ignore mapping Request DTO property to Data Model

Each of these are covered in more detail in the docs and examples below.

### Advanced CRUD Example

Lets now explore a more advanced example that implements Audit information as well as layered support for multi-tenancy to see how you can easily compose features.

So lets say you have an interface that all tables you want to contain Audit information implements:

```csharp
public interface IAudit 
{
    DateTime CreatedDate { get; set; }
    string CreatedBy { get; set; }
    string CreatedInfo { get; set; }
    DateTime ModifiedDate { get; set; }
    string ModifiedBy { get; set; }
    string ModifiedInfo { get; set; }
    DateTime? SoftDeletedDate { get; set; }
    string SoftDeletedBy { get; set; }
    string SoftDeletedInfo { get; set; }
}
```

It's not required, but it's also useful to have a concrete base table which could be annotated like:

```csharp
public abstract class AuditBase : IAudit
{
    public DateTime CreatedDate { get; set; }
    [Required]
    public string CreatedBy { get; set; }
    [Required]
    public string CreatedInfo { get; set; }

    public DateTime ModifiedDate { get; set; }
    [Required]
    public string ModifiedBy { get; set; }
    [Required]
    public string ModifiedInfo { get; set; }

    [Index] //Check if Deleted
    public DateTime? SoftDeletedDate { get; set; }
    public string SoftDeletedBy { get; set; }
    public string SoftDeletedInfo { get; set; }
}
```

#### AutoPopulate Examples

We can then create a base Request DTO that all Audit Create Services will implement:

```csharp
[ValidateIsAuthenticated]
[AutoPopulate(nameof(IAudit.CreatedDate),  Eval = "utcNow")]
[AutoPopulate(nameof(IAudit.CreatedBy),    Eval = "userAuthName")] //or userAuthId
[AutoPopulate(nameof(IAudit.CreatedInfo),  Eval = "`${userSession.DisplayName} (${userSession.City})`")]
[AutoPopulate(nameof(IAudit.ModifiedDate), Eval = "utcNow")]
[AutoPopulate(nameof(IAudit.ModifiedBy),   Eval = "userAuthName")] //or userAuthId
[AutoPopulate(nameof(IAudit.ModifiedInfo), Eval = "`${userSession.DisplayName} (${userSession.City})`")]
public abstract class CreateAuditBase<Table,TResponse> : ICreateDb<Table>, IReturn<TResponse> {}
```

The `*Info` examples is a superfluous example showing that you can evaluate any `#Script` expression. Typically you'd only save User Id or Username.

These all call [#Script Methods](https://sharpscript.net/docs/methods) which you can [add/extend yourself](https://sharpscript.net/docs/script-pages#extend), e.g:

```csharp
public override void Configure()
{
    // Register custom script methods
    ScriptContext.ScriptMethods.Add(new MyScripts());
}

// Custom #Script Methods, see: https://sharpscript.net/docs/methods
public class MyScripts : ScriptMethods
{
    public string tenantId(ScriptScopeContext scope)
    {
        var req = scope.GetRequest();
        var requestDto = req.Dto;
        return requestDto is IHasTenantId hasTenantId
            ? hasTenantId.TenantId // Explicitly set on Request DTO
            : req.AbsoluteUri.RightPart("//").LeftPart('.'); //Fallback to use subdomain
    }
}

// Populate Post.TenantId property with `tenantId` #Script Method
[AutoPopulate(nameof(Post.TenantId), Eval = "tenantId")]
public class CreatePost : ICreatDb<Post>, IReturn<IdResponse> 
{
    public string Name { get; set; }
    public string Content { get; set; }
}
```

### AutoPopulate

The `[AutoPopulate]` attribute tells AutoCrud that you want the DB Table to automatically populate these properties, which can be populated using any of its
properties below:

 - **Value** - A constant value that can be used in C# Attributes, e.g `Value="Foo"`
 - **Expression** - A Lightweight [#Script](https://sharpscript.net/) Expression that results in a constant value that's only evaluated once and cached globally, e.g. `Expression = "date(2001,1,1)"`, useful for values that can't be defined in C# Attributes like `DateTime`, can be any [#Script Method](https://sharpscript.net/docs/default-scripts).
 - **Eval** - A [#Script](https://sharpscript.net/) Expression that's cached per request. E.g. `Eval="utcNow"` calls the `utcNow` Script method which returns `DateTime.UtcNow` which is cached for that request so all other `utcNow` expressions will return the same exact value. 
 - **NoCache** - Don't cache the expression, evaluate it each time.

AutoCrud makes extensive usage of `#Script` expressions for much of its declarative functionality which always executes their cached ASTs so expressions are only parsed once and still fast to evaluate even when results are not cached.

Lets now layer on additional generic functionality by inheriting and extending the base class with additional functionality, e.g. if we want our table to support [Multitenancy](/multitenancy) we could extend it with:

```csharp
[AutoPopulate(nameof(IAuditTenant.TenantId), Eval = "Request.Items.TenantId")]
public abstract class CreateAuditTenantBase<Table,TResponse> 
    : CreateAuditBase<Table,TResponse> {}
```

Where `TenantId` is added in a Global Request Filter (e.g. after inspecting the authenticated UserSession to determine the tenant they belong to), e.g:

```csharp
const string TenantId = nameof(TenantId);

void SetTenant(IRequest req, IResponse res, object dto)
{
    var userSession = req.SessionAs<AuthUserSession>();
    if (userSession.IsAuthenticated)
    {
        req.SetItem(TenantId, userSession.City switch {
            "London" => 10,
            "Perth"  => 11,
            //...
            _        => 100,
        });
    }
}
    
GlobalRequestFilters.Add(SetTenant);        // HTTP Requests
GlobalMessageRequestFilters.Add(SetTenant); // MQ Requests
```

Now we easily implement custom "Audited" and "Multi Tenant" CRUD Services by inheriting these base Services. 

Here's an example of our custom Table that implements our `AuditBase` class with a `TenantId` to capture the Tenant the record should be saved to:

```csharp
public class RockstarAuditTenant : AuditBase
{
    [Index]
    public int TenantId { get; set; }
    [AutoIncrement]
    public int Id { get; set; }
    public string FirstName { get; set; }
    public string LastName { get; set; }
    public int? Age { get; set; }
    public DateTime DateOfBirth { get; set; }
    public DateTime? DateDied { get; set; }
    public LivingStatus LivingStatus { get; set; }
}
```

Our service can now implement our base Audit & Multitenant enabled service:

```csharp
public class CreateRockstarAuditTenant 
    : CreateAuditTenantBase<RockstarAuditTenant, CreateRockstarResponse>
{
    public string FirstName { get; set; }
    public string LastName { get; set; }
    public int? Age { get; set; }
    public DateTime DateOfBirth { get; set; }
}
```

And all the decorated properties will be automatically populated when creating the Rockstar with `CreateRockstarAuditTenant`, e.g:

```csharp
client.Post(new CreateRockstarAuditTenant {
    FirstName = "Kurt",
    LastName = "Cobain",
    Age = 27,
    DateOfBirth = new DateTime(20,2,1967),
});
```

We can create the same base classes for Updates:

```csharp
[ValidateIsAuthenticated]
[AutoPopulate(nameof(IAudit.ModifiedDate), Eval = "utcNow")]
[AutoPopulate(nameof(IAudit.ModifiedBy),   Eval = "userAuthName")] //or userAuthId
[AutoPopulate(nameof(IAudit.ModifiedInfo), Eval = "`${userSession.DisplayName} (${userSession.City})`")]
public abstract class UpdateAuditBase<Table,TResponse> 
    : IUpdateDb<Table>, IReturn<TResponse> {}

[AutoFilter(nameof(IAuditTenant.TenantId), Eval="Request.Items.TenantId")]
public abstract class UpdateAuditTenantBase<Table,TResponse> 
    : UpdateAuditBase<Table,TResponse> {}

public class UpdateRockstarAuditTenant 
    : UpdateAuditTenantBase<RockstarAuditTenant, RockstarWithIdResponse>
{
    public int Id { get; set; }
    public string FirstName { get; set; }
    public LivingStatus? LivingStatus { get; set; }
}
```

::: info
the `[AutoPopulate]` properties only appear on the Data Model, not the external Request DTO since we don't want external API consumers to populate them.
:::

For Apps that prefer to never delete rows and instead mark records as deleted so an audit trail is retained, we can implement "Soft Deletes" using an UPDATE to populate the `SoftDelete*` fields behind-the-scenes:

```csharp
[ValidateIsAuthenticated]
[AutoPopulate(nameof(IAudit.SoftDeletedDate), Eval = "utcNow")]
[AutoPopulate(nameof(IAudit.SoftDeletedBy),   Eval = "userAuthName")] //or userAuthId
[AutoPopulate(nameof(IAudit.SoftDeletedInfo), Eval = "`${userSession.DisplayName} (${userSession.City})`")]
public abstract class SoftDeleteAuditBase<Table,TResponse> 
    : IUpdateDb<Table>, IReturn<TResponse> {}

[AutoFilter(QueryTerm.Ensure, nameof(IAuditTenant.TenantId),  Eval = "Request.Items.TenantId")]
public abstract class SoftDeleteAuditTenantBase<Table,TResponse> 
    : SoftDeleteAuditBase<Table,TResponse> {}

public class SoftDeleteAuditTenant 
    : SoftDeleteAuditTenantBase<RockstarAuditTenant, RockstarWithIdResponse>
{
    public int Id { get; set; }
}
```

To implement a "Real" permanently destructive DELETE you would instead implement `IDeleteDb<T>`:

```csharp
[ValidateIsAuthenticated]
[AutoFilter(QueryTerm.Ensure, nameof(IAuditTenant.TenantId),  Eval = "Request.Items.TenantId")]
public class RealDeleteAuditTenant 
    : IDeleteDb<RockstarAuditTenant>, IReturn<RockstarWithIdResponse>
{
    public int Id { get; set; }
    public int? Age { get; set; }
}
```

### Multi RDBMS Services

As they're just regular ServiceStack Services everything you’re used to that works with normal services also works with new Auto Crud Services, to
recap you can annotate the **DB Model** with the `[NamedConnection]` attribute to specify which 
[registered named connection](/multitenancy#changedb-apphost-registration) AutoQuery should use:

```csharp
[NamedConnection("Reporting")]
public class NamedRockstar : Rockstar { } //DB Model
```

Where all AutoQuery Services for that data model will query the **Reporting** database instead:

```csharp
public class CreateNamedRockstar : RockstarBase, 
    ICreateDb<NamedRockstar>, IReturn<RockstarWithIdAndResultResponse>
{
    public int Id { get; set; }
}

public class UpdateNamedRockstar : RockstarBase, 
    IUpdateDb<NamedRockstar>, IReturn<RockstarWithIdAndResultResponse>
{
    public int Id { get; set; }
}
```

#### Custom AutoQuery CRUD Services

Alternatively the `[ConnectionInfo]` can be [used on Service implementations](/multitenancy#connectioninfo-attribute), but as AutoQuery doesn't 
have them you'd need to provide custom implementations that can delegate to their respective Auto Crud API, e.g:

```csharp
[ConnectionInfo(NamedConnection = MyDatabases.Reporting)]
public class MyReportingServices(IAutoQueryDb autoQuery) : Service
{
    public Task<object> Any(CreateConnectionInfoRockstar request) => 
        autoQuery.CreateAsync(request, Request);

    public Task<object> Any(UpdateConnectionInfoRockstar request) => 
        autoQuery.UpdateAsync(request, Request);
}
```

### AutoFilter

If you're creating Soft Delete & Multi tenant services you'll want to ensure that every query only returns records in their tenant and doesn't return deleted items, which we can implement using an `[AutoFilter]`, e.g:

```csharp
[ValidateIsAuthenticated]
[AutoFilter(QueryTerm.Ensure, nameof(IAudit.SoftDeletedDate), Template = SqlTemplate.IsNull)]
[AutoFilter(QueryTerm.Ensure, nameof(IAuditTenant.TenantId),  Eval = "Request.Items.TenantId")]
public abstract class QueryDbTenant<From, Into> : QueryDb<From, Into> {}
```

The `[AutoFilter]` lets you add pre-configured filters to the query, `QueryTerm.Ensure` utilizes OrmLite's new `Ensure()` APIs which forces always applying this filter, even if the query contains other `OR` conditions.

This base class will then let you create concrete queries that doesn't return soft deleted rows and only returns rows from the same tenant as the authenticated user, e.g:

```csharp
public class QueryRockstarAudit : QueryDbTenant<RockstarAuditTenant, Rockstar>
{
    public int? Id { get; set; }
}
```

To coincide with AutoCRUD there's also support for [declarative validation](https://github.com/ServiceStack/ServiceStack/blob/master/tests/ServiceStack.WebHost.Endpoints.Tests/AutoQueryCrudTests.Validate.cs) which thanks to [#Script](https://sharpscript.net/) lets you define your Fluent Validation Rules by annotating your Request DTO properties. As it's essentially a different way to define Fluent Validation Rules, it still [needs Validation enabled](/validation#validation-feature) to run:

```csharp
Plugins.Add(new ValidationFeature());
```

### AutoMap and AutoDefault Attributes

The `[AutoDefault]` attribute allows you to specify default values that the Data Model should be populated with using the same `#Script` expression support 
available in `[AutoPopulate]` to populate constant values, cached constant expressions or results of full evaluated expressions.

The `[AutoMap]` attributes enables the flexibility of being able to maintain different external property names from their internal data models, but still
be able to declaratively map them.

Here's an example `ICreateDb<T>` AutoCrud Service that makes use of both these attributes to achieve its desired behavior:


```csharp
public class CreateRockstarAutoMapDefault : ICreateDb<Rockstar>, IReturn<RockstarWithIdResponse>
{
    [AutoMap(nameof(Rockstar.FirstName))]
    public string MapFirstName { get; set; }

    [AutoMap(nameof(Rockstar.LastName))]
    public string MapLastName { get; set; }
    
    [AutoMap(nameof(Rockstar.Age))]
    [AutoDefault(Value = 21)]
    public int? MapAge { get; set; }
    
    [AutoMap(nameof(Rockstar.DateOfBirth))]
    [AutoDefault(Expression = "date(2001,1,1)")]
    public DateTime MapDateOfBirth { get; set; }

    [AutoMap(nameof(Rockstar.DateDied))]
    [AutoDefault(Eval = "utcNow")]
    public DateTime? MapDateDied { get; set; }
    
    [AutoMap(nameof(Rockstar.LivingStatus))]
    [AutoDefault(Value = LivingStatus.Dead)]
    public LivingStatus? MapLivingStatus { get; set; }
}
```

### AutoIgnore Attributes

To send additional properties with your AutoQuery CRUD Request DTO which doesn't match the data model you can ignore the validation check
by annotating properties with the `[AutoIgnore]` Attribute, e.g:

```csharp
public class CustomRockstarService : ICreateDb<Rockstar>, IReturn<RockstarWithIdResponse>
{
    public int Id { get; set; }
    public int? Age { get; set; }
    [AutoIgnore]
    public CustomInfo CustomInfo { get;set; }
}
```

Or you can ignore validation for all properties with the same name by registering it to `AutoQuery.IgnoreCrudProperties`, e.g:

```csharp
AutoQuery.IgnoreCrudProperties.Add(nameof(CustomInfo));
```

### Apply Generic CRUD Behaviors

The AutoQuery Attributes are used to construct a metadata model of each operation used to enlist the desired functionality that each Service should have.
This metadata model can also be programmatically constructed allowing you to codify conventions by grouping annotated attributes under a single `[AutoApply]`
attribute resulting in the same behavior had the AutoQuery Request been annotated with the attributes directly, e.g:

```csharp
[AutoApply(Behavior.AuditQuery)]
public class QueryBookings { ... } // Equivalent to:

[AutoFilter(QueryTerm.Ensure, nameof(AuditBase.DeletedDate), Template = SqlTemplate.IsNull)]
public class QueryBookings { ... }


[AutoApply(Behavior.AuditCreate)]
public class CreateBooking { ... } // Equivalent to:

[AutoPopulate(nameof(AuditBase.CreatedDate),  Eval = "utcNow")]
[AutoPopulate(nameof(AuditBase.CreatedBy),    Eval = "userAuthName")]
[AutoPopulate(nameof(AuditBase.ModifiedDate), Eval = "utcNow")]
[AutoPopulate(nameof(AuditBase.ModifiedBy),   Eval = "userAuthName")]
public class CreateBooking { ... }
```

The `[AutoApply]` attribute is itself an inert marker for capturing what generic behavior you want applied to AutoQuery Services. 
All built-in behavior is declared on the `Behavior` static class:

```csharp
public static class Behavior
{
    // Auto Filter SoftDeleted Results
    public const string AuditQuery = nameof(AuditQuery);
    
    // Auto Populate CreatedDate, CreatedBy, ModifiedDate & ModifiedBy fields
    public const string AuditCreate = nameof(AuditCreate);
    
    // Auto Populate ModifiedDate & ModifiedBy fields
    public const string AuditModify = nameof(AuditModify);
    
    // Auto Populate DeletedDate & DeletedBy fields
    public const string AuditDelete = nameof(AuditDelete);
    
    // Auto Populate DeletedDate & DeletedBy fields and changes IDeleteDb operation to Update
    public const string AuditSoftDelete = nameof(AuditSoftDelete);
}
```

#### AuditAutoCrudMetadataFilter

This functionality is implemented by extending the metadata for AutoQuery CRUD Services with additional attributes in `AutoQueryFeature.AutoCrudMetadataFilters` delegate filters where they result in the same behavior as if the Request DTOs were annotated with attributes directly. E.g. Here's the built-in filter for implementing the above behaviors:

```csharp
public static void AuditAutoCrudMetadataFilter(AutoCrudMetadata meta)
{
    foreach (var applyAttr in meta.AutoApplyAttrs)
    {
        switch (applyAttr.Name)
        {
            case Behavior.AuditQuery:
                meta.Add(new AutoFilterAttribute(
                    QueryTerm.Ensure, nameof(AuditBase.DeletedDate), SqlTemplate.IsNull));
                break;
            case Behavior.AuditCreate:
            case Behavior.AuditModify:
                if (applyAttr.Name == Behavior.AuditCreate)
                {
                    meta.Add(new AutoPopulateAttribute(nameof(AuditBase.CreatedDate)) {
                        Eval = "utcNow"
                    });
                    meta.Add(new AutoPopulateAttribute(nameof(AuditBase.CreatedBy)) {
                        Eval = "userAuthName"
                    });
                }
                meta.Add(new AutoPopulateAttribute(nameof(AuditBase.ModifiedDate)) {
                    Eval = "utcNow"
                });
                meta.Add(new AutoPopulateAttribute(nameof(AuditBase.ModifiedBy)) {
                    Eval = "userAuthName"
                });
                break;
            case Behavior.AuditDelete:
            case Behavior.AuditSoftDelete:
                if (applyAttr.Name == Behavior.AuditSoftDelete)
                    meta.SoftDelete = true;

                meta.Add(new AutoPopulateAttribute(nameof(AuditBase.DeletedDate)) {
                    Eval = "utcNow"
                });
                meta.Add(new AutoPopulateAttribute(nameof(AuditBase.DeletedBy)) {
                    Eval = "userAuthName"
                });
                break;
        }
    }
}
```

You can use this same functionality to describe your own custom generic functionality, e.g. Lets say you wanted to instead populate your base class with Audit Info containing different named properties with **local** `DateTime` and UserAuth `Id`. You can define your own Behavior name for this functionality:

```csharp
[AutoApply("MyUpdate")]
public class UpdateBooking { ... }
```

and implement it with a custom `AutoCrudMetadataFilters` that populates the Audit `[AutoPopulate]` attributes on all Request DTOs marked with your Behavior name, e.g:

```csharp
void MyAuditFilter(AutoCrudMetadata meta)
{
    if (meta.HasAutoApply("MyUpdate"))
    {
        meta.Add(new AutoPopulateAttribute(nameof(MyBase.MyModifiedDate)) {
            Eval = "now"
        });
        meta.Add(new AutoPopulateAttribute(nameof(MyBase.MyModifiedBy)) {
            Eval = "userAuthId"
        });
    }
}

Plugins.Add(new AutoQueryFeature {
    AutoCrudMetadataFilters = { MyAuditFilter },
});
```

### AutoQuery CRUD Events

AutoQuery includes `OnBefore*` and `OnAfter*` (sync & async) events for `Create`, `Update`, `Patch` & `Delete` that can be used to execute custom logic before or after each AutoQuery CRUD operation. E.g. if your system implements their own Audit history via RDBMS triggers, you can use the `OnBefore` **Delete** event to update the record with deleted info before the AutoQuery CRUD operation deletes it:

```csharp
Plugins.Add(new AutoQueryFeature {
    OnBeforeDeleteAsync = async ctx => {
        if (ctx.Dto is DeleteBooking deleteBooking)
        {
            var session = await ctx.Request.GetSessionAsync();
            await ctx.Db.UpdateOnlyAsync(() => new Booking {
                DeletedBy = session.UserAuthName,
                DeletedDate = DateTime.UtcNow,
            }, where: x => x.Id == deleteBooking.Id);
        }                
    },
});
```

::: info
AutoQuery generates **async** Services by default which will invoke the `*Async` events, but if you implement a [sync Custom AutoQuery CRUD Service](/autoquery/crud#custom-autoquery-crud-services) it executes the **sync** events instead so you'd need to implement the `OnBeforeDelete` custom hook instead.
:::

### Custom Complex Mapping

Another opportunity to apply more complex custom mapping logic before resorting to creating an actual Service implementation is to make use of
ServiceStack's built-in [Auto Mapping Populator API](/auto-mapping#intercept-automapping-conversions) to intercept an AutoMapping conversion
between 2 types and apply custom logic after `ConvertTo<T>` or `PopulateWith<T>` APIs, e.g:

```csharp
AutoMapping.RegisterPopulator((Dictionary<string,object> target, CreateRockstar source) => 
{
    if (!IsAlive(source))
    {
        target[nameof(source.LivingStatus)] = LivingStatus.Dead;
    }
});
```
 
### Auto Guid's

In addition to supporting `[AutoIncrement]` to insert records with Auto Incrementing Ids, you can use `[AutoId]` to insert entities with
[RDBMS generated UUIDs](/ormlite/reference-support#auto-populated-guid-ids) where they're supported otherwise
OrmLite populates them with `Guid.NewGuid()`.

::: info
usage of inheritance isn't required & has the same behavior as using explicit properties
:::

```csharp
public abstract class RockstarBase
{
    public string FirstName { get; set; }
    public string LastName { get; set; }
    public int? Age { get; set; }
    public DateTime DateOfBirth { get; set; }
}

public class Rockstar : RockstarBase
{
    [AutoId]
    public Guid Id { get; set; }
}

public class CreateRockstarWithAutoGuid : RockstarBase, ICreateDb<Rockstar>, IReturn<RockstarWithIdResponse>
{
}
```

Or if you prefer for Id's to always be populated with `Guid.NewGuid()`, remove `[AutoId]` and populate it with `[AutoPopulate]` instead:

```csharp
[AutoPopulate(nameof(Rockstar.Id),  Eval = "nguid")]
public class CreateRockstarWithAutoGuid : RockstarBase, ICreateDb<Rockstar>, IReturn<RockstarWithIdResponse>
{
}
```

### Optimistic Concurrency

We can declaratively add support for [OrmLite's Optimistic Concurrency](/ormlite/optimistic-concurrency) by
including `ulong RowVersion` property on Auto Crud Request/Response DTOs and Data Models, e.g:

```csharp
// Data Model
public class RockstarVersion : RockstarBase
{
    [AutoIncrement]
    public int Id { get; set; }

    public ulong RowVersion { get; set; }
}

public class CreateRockstarVersion : RockstarBase, ICreateDb<RockstarVersion>,
    IReturn<RockstarWithIdAndRowVersionResponse> { }

public class UpdateRockstarVersion : RockstarBase, IPatchDb<RockstarVersion>,
    IReturn<RockstarWithIdAndRowVersionResponse>
{
    public int Id { get; set; }
    public ulong RowVersion { get; set; }
}

// Response DTO
public class RockstarWithIdAndRowVersionResponse
{
    public int Id { get; set; }
    public ulong RowVersion { get; set; }
    public ResponseStatus ResponseStatus { get; set; }
}
```

AutoQuery will populate the `RowVersion` in Response DTOs which will need to be provided whenever making changes to that entity where it will fail to update the entity if no `RowVersion` was provided or has since been modified:

```csharp
var createResponse = client.Post(new CreateRockstarVersion {
    FirstName = "Original",
    LastName = "Version",
    Age = 20,
    DateOfBirth = new DateTime(2001,7,1),
    LivingStatus = LivingStatus.Dead,
});

// throws OptimisticConcurrencyException: No RowVersion provided
client.Patch(new UpdateRockstarVersion {
    Id = createResponse.Id, 
    LastName = "UpdatedVersion",
});

// succeeds if "Original Version" wasn't modified otherwise throws OptimisticConcurrencyException 
var response = client.Patch(new UpdateRockstarVersion {
    Id = createResponse.Id, 
    LastName = "UpdatedVersion",
    RowVersion = createResponse.RowVersion,
});
```

### MQ AutoQuery CRUD Requests

As AutoQuery CRUD Services are just ServiceStack Services they can partake in its ecosystem of features like being able to 
[invoke Services via MQ](/messaging), although there's some extra consideration needed to account for the differences between HTTP and MQ Requests.
First whatever filters you've added to populate the `IRequest.Items` like tenant Id you'll also need to register in `GlobalMessageRequestFilters`
so they're executed for MQ Requests as well:

```csharp
GlobalRequestFilters.Add(SetTenant);        // HTTP Requests
GlobalMessageRequestFilters.Add(SetTenant); // MQ Requests
```

Secondly Auth Information is typically sent in the HTTP Request Headers, but they need to be included in the Request DTO to send Authenticated 
MQ Requests, which can either implement `IHasSessionId` for normal [Session Auth Providers](/auth/authentication-and-authorization#session-authentication-overview), e.g:

```csharp
public class CreateRockstarAuditTenant 
  : CreateAuditTenantBase<RockstarAuditTenant, RockstarWithIdAndResultResponse>, IHasSessionId
{
    public string SessionId { get; set; } //Authenticate MQ Requests
    //...
}
```

Alternatively they can implement `IHasBearerToken` for [stateless Bearer Token](/auth/authentication-and-authorization#authentication-per-request-auth-providers)
Auth providers like JWT or API Keys.

If you're publishing an MQ Request inside a HTTP Service you can use the `PopulateRequestDtoIfAuthenticated` extension method which populates the Request 
DTO from the Authenticated HTTP Request, e.g:

```csharp
public class AutoCrudMqServices : Service
{        
    public void Any(CreateRockstarAuditTenantMq request)
    {
        var mqRequest = request.ConvertTo<CreateRockstarAuditTenant>();
        Request.PopulateRequestDtoIfAuthenticated(mqRequest);
        PublishMessage(mqRequest);
    }
}
```

In this case if using [Background MQ](/background-mq), it will execute the `CreateRockstarAuditTenant` request in a background thread, populating the MQ Request Context with the session identified by the `IRequest.GetSessionId()`.

#### Publishing Requests to OneWay Endpoint

You can also send MQ requests directly by [publishing to the OneWay HTTP endpoint](/messaging#oneway-http-requests-are-published-to-mq-then-executed), which if your AppHost is registered with an MQ Server, it will publish the message to the MQ and auto populate Request DTOs that implements `IHasSessionId` or `IHasBearerToken`, either if implicitly sent from an Authenticated client:

```csharp
var authResponse = authClient.Post(new Authenticate {
    provider = "credentials",
    UserName = "admin@email.com",
    Password = "p@55wOrd",
    RememberMe = true,
});

authClient.SendOneWay(new CreateRockstarAuditTenant {
    FirstName = nameof(CreateRockstarAuditTenant),
    LastName = "SessionId",
    Age = 20,
    DateOfBirth = new DateTime(2002,2,2),
});
```

Or from an anonymous client with the explicit `BearerToken` or `SessionId` properties populated, e.g:

```csharp
client.SendOneWay(new CreateRockstarAuditMqToken {
    BearerToken = JwtUserToken,
    FirstName = nameof(CreateRockstarAuditMqToken),
    LastName = "JWT",
    Age = 20,
    DateOfBirth = new DateTime(2002,2,2),
});
```

To save populating the `BearerToken` in each request, you can set it once on the Service Client which will automatically populate it on Request DTOs:

```csharp
client.BearerToken = jwtUserToken;
```

## AutoQuery CRUD Features

Building upon AutoQuery is a number of other features that increase the capabilities of AutoQuery Services & provide instant utility, including:

 - [Declarative Validation](/declarative-validation)
 - [Executable Audit Log](/autoquery/audit-log)
 - [Instantly Servicify with AutoGen](/autoquery/autogen)


# AutoQuery CRUD Executable Audit Log
Source: https://docs.servicestack.net/autoquery/audit-log

In addition to being able to declaratively develop [AutoQuery](/autoquery/) and [CRUD](/autoquery/crud) APIs without needing to implement them, 
you're also able to enable a **recorded history of Executable Audit information** over all AutoCrud operations in an executable audit log that 
in addition to maintaining an automated recorded history of every change to an entity also exhibits "EventSourcing-like capabilities" in being 
able to recreate the entities state using the latest Services implementation by replaying all AutoCrud operations in order, which can be 
applied on a granular entity, table level, or in the unlikely case that all System DB writes are performed through AutoQuery CRUD Services, 
it's capable of re-creating the entire DB state from just its Audit history, although is dependent on whether all changes made to
AutoCrud Services are backwards compatible.

Being able to rebuild your Systems DB by replaying audit history events is a nice property that can serve as an integrity check to
verify that all changes leading up to the current DB state has been recorded. As data is the most important part of most systems it
can be beneficial to maintain a change history of when items were created, modified and deleted (and by whom) as we're used to 
when using a VCS for our source code. Typically this means also employing "non destructive" approaches to system design like "Soft Deletes" 
which you can declaratively implement with Auto CRUD.

## Executable Crud Audit Events

This feature tries to obtain some of the nice features of Event Sourcing but without the additional complexity by allowing you to 
capture all CRUD operations in an executable log whilst still retaining your RDBMS as your master authority. 
This feature doesn’t require any additional dev overhead as your AutoCrud Request DTOs are the recorded events.

To enable this feature you just need to register an [ICrudEvents](https://github.com/ServiceStack/ServiceStack/blob/master/src/ServiceStack.Server/CrudEvents.cs) 
provider which will let you persist your events in any data store, but typically you’d use OrmLiteCrudEvents to persist it in 
the same RDBMS that the AutoCrud requests are already writing to, e.g:

```csharp
public class ConfigureAutoQuery : IHostingStartup
{
    public void Configure(IWebHostBuilder builder) => builder
        .ConfigureServices(services => {
            // Enable Audit History
            services.AddSingleton<ICrudEvents>(c =>
                new OrmLiteCrudEvents(c.GetRequiredService<IDbConnectionFactory>()) {
                    // NamedConnections = { SystemDatabases.Reporting }
                });
           
            services.AddPlugin(new AutoQueryFeature {
                MaxLimit = 1000,
                //IncludeTotal = true,
            });
        })
        .ConfigureAppHost(appHost => {
            appHost.Resolve<ICrudEvents>().InitSchema();
        });
}
```

If you’re using Multitenancy features or multiple RDBMS’s in your AutoCrud DTOs you can add them to NamedConnections where 
it will create an CrudEvent table in each of the RDBMS’s used.

and that’s all that’s required, now every AutoCrud operation will persist the Request DTO and associative metadata in the 
Event entry below within a DB transaction:

```csharp
public class CrudEvent : IMeta
{
    [AutoIncrement]
    public long Id { get; set; }    
    // AutoCrudOperation, e.g. Create, Update, Patch, Delete, Save
    public string EventType { get; set; }    
    public string Model { get; set; }         // DB Model Name    
    public string ModelId { get; set; }       // Primary Key of DB Model
    public DateTime EventDate { get; set; }   // UTC
    public long? RowsUpdated { get; set; }    // How many rows were affected
    public string RequestType { get; set; }   // Request DTO Type    
    public string RequestBody { get; set; }   // Serialized Request Body    
    public string UserAuthId { get; set; }    // UserAuthId if Authenticated    
    public string UserAuthName { get; set; }  // UserName or unique User Identity
    public string RemoteIp { get; set; }      // Remote IP of the Request
    public string Urn { get; set; }           // URN format: urn:{requestType}:{ModelId}

    // Custom Reference Data with or with non-integer Primary Key
    public int? RefId { get; set; }
    public string RefIdStr { get; set; }
    public Dictionary<string, string> Meta { get; set; }
}
```

## Full Executable Audit History

With what's captured this will serve as an Audit History of state changes for any row by querying the `Model` & `ModelId` columns, e.g:

```csharp
var dbEvents = (OrmLiteCrudEvents)container.Resolve<ICrudEvents>();
var rowAuditEvents = dbEvents.GetEvents(Db, nameof(Rockstar), id);
```

The contents of the Request DTO stored as JSON in `RequestBody`. You can quickly display the contents of any JSON in human-friendly 
HTML with the [htmlDump](https://sharpscript.net/docs/html-scripts#htmldump) script if you're using `#Script`, `@Html.HtmlDump(obj)` 
if you're using Razor or just the static `ViewUtils.HtmlDump(obj)` method to get a raw pretty-formatted HTML String.

## Replay AutoCrud Requests

If all your database was created with AutoCrud Services you could delete its rows and re-create it by just re-playing all your 
AutoCrud DTOs in the order they were executed, which can be done with:

```csharp
var eventsPlayer = new CrudEventsExecutor(appHost);
foreach (var crudEvent in dbEvents.GetEvents(db))
{
    await eventsPlayer.ExecuteAsync(crudEvent);
}
```

The `CrudEventsExecutor` uses your AppHost's `ServiceController` to execute the message, e,g. same execution pipeline MQ Requests use, 
so it will execute your AppHost's `GlobalMessageRequestFilters/Async` if you have any custom logic in Request Filters 
(e.g. Multi TenantId example above). It also executes authenticated AutoCrud requests as the original AutoCrud Request Authenticated User, 
which just like [JWT Refresh Tokens](/auth/jwt-authprovider#requires-user-auth-repository-or-iusersessionsource)
will require either using an AuthRepository or if you're using a Custom Auth Provider you can implement an `IUserSessionSource` to 
load User Sessions from a custom data store.

When replaying the Audit Events it will use the original primary key, even if you're using `[AutoIncrement]` Primary Keys, 
this will let you re-create the state of a single entry, e.g:

```csharp
db.DeleteById<Rockstar>(id);
var rowAuditEvents = dbEvents.GetEvents(Db, nameof(Rockstar), id);
foreach (var crudEvent in rowAuditEvents)
{
    await eventsPlayer.ExecuteAsync(crudEvent);
}
```

If for instance you wanted it to execute through your latest logic with any enhancements or bug fixes, etc.


## Ignoring Crud Events

You can selectively choose to ignore capturing events by returning `null` in the `EventsFilter` when registering `OrmLiteCrudEvents`, e.g:

```csharp
new OrmLiteCrudEvents(c.Resolve<IDbConnectionFactory>()) {
    EventsFilter = (row,context) => MyShouldIgnore(context) 
        ? null
        : row
}
```

The `CrudContext` contains all the relevant information about the AutoQuery Crud request, including:

```csharp
public class CrudContext
{
    public IRequest Request { get; private set; }
    public IDbConnection Db { get; private set; }
    public ICrudEvents Events { get; private set; }
    public string Operation { get; set; }
    public object Dto { get; private set; }
    public Type ModelType { get; private set; }
    public Type RequestType { get; private set; }
    public Type ResponseType { get; private set; }
    public ModelDefinition ModelDef { get; private set; }
    public PropertyAccessor IdProp { get; private set; }
    public PropertyAccessor ResultProp { get; private set; }
    public PropertyAccessor CountProp { get; private set; }
    public PropertyAccessor RowVersionProp { get; private set; }
    
    public object Id { get; set; }    
    public object Response { get; set; }    
    public long? RowsUpdated { get; set; }
}
```

Alternatively you can ignore recording the event for requests tagged with `IRequest.Items[Keywords.IgnoreEvent]`, e.g:

```csharp
GlobalRequestFilters.Add((req, res, dto) => {
    if (MyShouldIgnore(dto))
        req.Items[Keywords.IgnoreEvent] = bool.TrueString;
});
```


# AutoQuery AutoGen CRUD Services
Source: https://docs.servicestack.net/autoquery/autogen

Long time users of ServiceStack will know it's a staunch proponent of **code-first development** where your C# Types retains the master authority of your App's logic, although there are a number of times where you have to work with existing databases which would require significant effort to create the initial code-first Data Models. Historically we've pointed people to use [OrmLite's T4 Template Support](/ormlite/autogen-t4#t4-template-support) which provides a decent initial stab, however it's limited in its capability and offers a sub par development experience.

<lite-youtube class="w-full mx-4 my-4" width="560" height="315" videoid="NaJ7TW-Q_pU" style="background-image: url('https://img.youtube.com/vi/NaJ7TW-Q_pU/maxresdefault.jpg')"></lite-youtube>

### Code Generation of AutoQuery & CRUD Services

Now with AutoCrud we can add a lot more value in this area as AutoCrud's declarative nature allows us to easily generate AutoQuery & Crud Services by just emitting declarative Request DTOs.

You can then add the generated DTOs to your ServiceModel's to quickly enable AutoQuery Services for your existing databases.

<img src="/img/pages/svg/servicify.svg" width="100%">

To enable this feature you you just need to initialize `GenerateCrudServices` in your `AutoQueryFeature` plugin, e.g:

```csharp
Plugins.Add(new AutoQueryFeature {
    MaxLimit = 1000,
    GenerateCrudServices = new GenerateCrudServices {}
});
```

If you don't have an existing database, you can quickly test this out with a Northwind SQLite database available from [https://github.com/NetCoreApps/NorthwindAuto](https://github.com/NetCoreApps/NorthwindAuto):

:::sh
x download NetCoreApps/NorthwindAuto
:::

As you'll need to use 2 terminal windows, I'd recommend opening the project with **VS Code** which has great multi-terminal support:

:::sh
code NorthwindAuto
:::

### Register DB Connection

The important parts of this project is the registering the OrmLite DB Connection, the above configuration and the local **northwind.sqlite** database, i.e:

```csharp
container.AddSingleton<IDbConnectionFactory>(c =>
    new OrmLiteConnectionFactory(MapProjectPath("~/northwind.sqlite"), SqliteDialect.Provider));
```

When using [Endpoint Routing](/endpoint-routing) the DB Factory also needs to be initialized on `GenerateCrudServices`, the easiest way to do that would be to register AutoQueryFeature plugin in `Configure.Db.cs` e.g:

```csharp
public class ConfigureDb : IHostingStartup
{
    public void Configure(IWebHostBuilder builder) => builder
        .ConfigureServices((context, services) => {
            var dbFactory = new OrmLiteConnectionFactory(
                context.Configuration.GetConnectionString("DefaultConnection"),
                SqliteDialect.Provider);
            container.AddSingleton<IDbConnectionFactory>(c => dbFactory);

            services.AddPlugin(new AutoQueryFeature {
                MaxLimit = 1000,
                GenerateCrudServices = new GenerateCrudServices {
                    DbFactory = dbFactory,
                }
            });
            // ...
        });
}
```

## Export Code-First DTOs

After restarting your App with AutoGen's `GenerateCrudServices` enabled you can export the auto-generated APIs and Data Models into code-first C# classes

<lite-youtube class="w-full mx-4 my-4" width="560" height="315" videoid="mFyMgg7c3vg" style="background-image: url('https://img.youtube.com/vi/mFyMgg7c3vg/maxresdefault.jpg')"></lite-youtube>

### Generating AutoQuery APIs and Data Models

The development experience is essentially the same as [Add ServiceStack Reference](/add-servicestack-reference) where you'll need to run the .NET Core App in 1 terminal:

:::sh
dotnet run
:::

Then use the `x` dotnet tool to download all the AutoQuery & Crud Services for all tables in the configured DB connection:

:::sh
`x csharp https://localhost:5001 -path /crud/all/csharp`
:::

If you're running a mix of autogenerated AutoGen AutoQuery APIs with existing typed AutoQuery APIs, you can just 
generate the **new** Services with: 

:::sh
x csharp https://localhost:5001 -path /crud/new/csharp
:::

Which you can then copy into your ServiceModel project.

::: tip
If no schema is provided, a default schema is used which depends on the Dialect Provider, eg SQL Server, PostgreSQL etc.
Multiple schema support requires the AutoQueryFeature to be configured with [multiple schemas](#multiple-schemas-and-rdbms-connections).
:::

### Updating Generated Services

If your RDBMS schema changes you'd need to restart your .NET App, then you can update all existing `dtos.cs` with:

:::sh
x csharp
:::

i.e. the same experience as updating normal DTOs.

### Switch to code-first dev model

After generating `dtos.cs` AutoGen is no longer needed and can now be removed by removing `GenerateCrudServices`

```csharp
Plugins.Add(new AutoQueryFeature {
    MaxLimit = 1000,
    // GenerateCrudServices = new GenerateCrudServices {}
});
```

All functionality and features can now be added to annotating & enhancing your code-first C# Typed DTOs.

### AutoGen specific options in AutoGen DTOs

When using AutoGen to generate Typed AutoQuery DTOs for your RDBMS Tables:

:::sh
`x csharp https://localhost:5001 -path /crud/all/csharp`
:::

The generated `dtos.cs` includes AutoGen-specific options that can be used to maintain multiple custom RDBMS Tables and AutoQuery APIs, e.g. you could maintain one for each of your different RDBMS schemas:

```csharp
/* Options:
//...
//IncludeCrudOperations: 
Schema: custom
//NamedConnection: 
//NoCache: 
//IncludeTables: 
//ExcludeTables: 
//AuthSecret: 
*/
```

### AutoGen Code Generation Customizations

AutoGen also supports a number of options to customize its generated code:

- **IncludeCrudOperations** `string[]` - Which AutoCrud APIs to include: `Query`, `Create`, `Update`, `Patch`, `Delete`
- **Schema** `string` - The RDBMS Schema you want AutoQuery Services generated for
- **NamedConnection** `string` - The NamedConnection you want AutoQuery Services generated for
- **NoCache** `boolean` - Do not use cached DB Table Schemas, re-fetch latest
- **IncludeTables** `string[]` - Allow List to specify only the tables you would like to have code-generated
- **ExcludeTables** `string[]` - Block List to exclude tables from code-generation
- **AuthSecret** `string` - The Admin AuthSecret to access Service in Release mode

For example you can use an empty array to only generate Data Models without any AutoQuery APIs:

:::sh
x csharp https://localhost:5001 -path /crud/all/csharp -q IncludeCrudOperations=[]
:::

Only generate read-only APIs by limiting generation to Query AutoQuery Request DTOs:

:::sh
x csharp https://localhost:5001 -path /crud/all/csharp -q IncludeCrudOperations=[Query]
:::

Only generate Read, Create and Update APIs (i.e. no Delete):

:::sh
x csharp https://localhost:5001 -path /crud/all/csharp -q IncludeCrudOperations=[Query,Create,Patch]
:::

These customized generated classes are also available from your App's built-in endpoints:

:::{.table .table-striped}
| Type | URL |
| --- | --- |
| All Services (C#) | `https://localhost:5001/crud/all/csharp` |
| Only New Services (C#) | `https://localhost:5001/crud/new/csharp` |
| Read Only Services (C#) | `https://localhost:5001/crud/all/csharp?IncludeCrudOperations=[Query]` |
| Only Data Models (C#) | `https://localhost:5001/crud/all/csharp?IncludeCrudOperations=[]` |
| New Auto Generated Services (C#) | `https://localhost:5001/crud/new/csharp` |
| Generate DTOs in alt languages (e.g. TypeScript) | `https://localhost:5001/crud/all/typescript` |
:::

## AutoRegister AutoGen AutoQuery Services

To recap we've now got an integrated scaffolding solution where we can quickly generate code-first AutoQuery Services and integrate them into our App to quickly build an AutoQuery Service layer around our existing database.

But we can raise the productivity level even higher by instead of manually importing the code-generated Services into our project we just tell ServiceStack to do it for us.

This is what the magical `AutoRegister` flag does for us:

```csharp
Plugins.Add(new AutoQueryFeature {
    GenerateCrudServices = new GenerateCrudServices {
        DbFactory = dbFactory,
        AutoRegister = true,
        //....
    }
});
```

### Instantly Servicify Northwind DB with gRPC

To show the exciting potential of this feature we'll demonstrate one valuable use-case of creating a [grpc](/grpc/) project, mixing in AutoQuery configuration to instantly Servicifying the Northwind DB, browsing the generated Services from ServiceStack's [Metadata Page](/metadata-page), explore the gRPC RPC Services `.proto` then create a new Dart App to consume the gRPC Services:

> YouTube: [youtu.be/5NNCaWMviXU](https://youtu.be/5NNCaWMviXU)

[![](/img/pages/release-notes/v5.9/autogen-grpc.png)](https://youtu.be/5NNCaWMviXU)

#### Step-by-step Guide

See the annotated guide below to follow along:

Create a new [grpc](https://github.com/NetCoreTemplates/grpc) .NET Core project and open it in VS Code:

:::sh
x new grpc NorthwindApi
code NorthwindApi
:::

Inside VS Code open a Terminal Window and [mix in](/mix-tool) the required configuration:

:::sh
cd NorthwindApi
x mix autocrudgen sqlite northwind.sqlite
:::

Which will mix in the [autocrudgen](https://gist.github.com/gistlyn/464a80c15cb3af4f41db7810082dc00c) gist to enable AutoQuery and tell it to Auto Generate AutoQuery and CRUD Services for all tables in the registered RDBMS (default schema):

```csharp
public class ConfigureDb : IHostingStartup
{
    public void Configure(IWebHostBuilder builder)
    {
        builder.ConfigureServices((context,services) =>
        {
            var dbFactory = new OrmLiteConnectionFactory(
                context.Configuration.GetConnectionString("DefaultConnection"),
                SqliteDialect.Provider);
                
            services.AddSingleton<IDbConnectionFactory>(dbFactory);
                
            services.AddPlugin(new AutoQueryFeature {
                MaxLimit = 1000,
                GenerateCrudServices = new GenerateCrudServices {
                    DbFactory = dbFactory,
                    AutoRegister = true
                }
            });
        });
    }
}
```

The [sqlite](https://gist.github.com/gistlyn/768d7b330b8c977f43310b954ceea668) gist registers an 
[OrmLite.Sqlite](https://github.com/ServiceStack/ServiceStack.OrmLite) RDBMS connection with our App which we want to configure to connect to a **northwind.sqlite** database:

```csharp
public void Configure(IServiceCollection services)
{
    services.AddSingleton<IDbConnectionFactory>(new OrmLiteConnectionFactory(
        Configuration.GetConnectionString("DefaultConnection"),
        SqliteDialect.Provider));
}
```

Then we apply the [northwind.sqlite](https://gist.github.com/gistlyn/97d0bcd3ebd582e06c85f8400683e037) gist to add the **northwind.sqlite** database to our new project.

Now that our App's configured we can run it with:

:::sh
dotnet run
:::

Where it will start the ServiceStack gRPC App on 3 ports configured in **appsettings.json**:

 - `5001` - Enables access from existing HTTP/1.1 clients and proxies
 - `5002` - Enables a secure gRPC Channel
 - `5003` - Enables an insecure gRPC Channel

```json
{
  "Kestrel": {
    "Endpoints": {
      "Https": {
        "Url": "https://*:5001",
        "Protocols": "Http1"
      },
      "GrpcSecure": {
        "Url": "https://*:5051",
        "Protocols": "Http2"
      },
      "GrpcInsecure" : {
        "Url": "http://*:5054",
        "Protocols": "Http2"
      }
    }
  }
}
```

Once running you can view your Apps metadata page at `https://localhost:5001` to inspect all the Services that were generated.

#### Create Dart gRPC Console App

It's also now accessible via [ServiceStack's gRPC endpoint](/grpc/) which opens your generated Services up to [Google's high-performance gRPC ecosystem](https://grpc.io) which enables typed, high-performance integrations into exciting platforms like [Flutter](https://flutter.dev) which uses the [Dart](https://dart.dev) programming language to create Reactive, high-performance native Android and iOS Apps. 

We can test Dart's gRPC integration and development workflow in a new Dart Console App we can create with:

```bash
mkdir dart-grpc && cd dart-grpc
pub global activate stagehand
stagehand console-full
```

We'll need to update **pubspec.yaml** with the required gRPC dependencies:

```yaml
dependencies:
  fixnum: ^0.10.11
  async: ^2.2.0
  protobuf: ^1.0.1
  grpc: ^2.1.3    
```

When you save **pubspec.yaml** Dart's VS Code extension will automatically fetch any new dependencies which can also be manually run with:

:::sh
pub get
:::

We can then use the [protoc support in the dotnet tools](/grpc#public-grpc-protoc-service-and-ui) to download our `.proto` Services descriptor and generate Dart's gRPC classes with a single command:

:::sh
`x proto-dart https://localhost:5001 -out lib`
:::

We're now all set to consume our gRPC Services using the protoc generated gRPC proxy in our `main()` function in **main.dart**:

```dart
import 'dart:io';
import 'package:grpc/grpc.dart';
import 'package:dart_grpc/services.pb.dart';
import 'package:dart_grpc/services.pbgrpc.dart';

void main(List<String> arguments) async {
    var client = GrpcServicesClient(ClientChannel('localhost', port:5054,
      options:ChannelOptions(credentials: ChannelCredentials.insecure())));

    var response = await client.getQueryCategory(QueryCategory());
    print(response.results);
    exit(0);
}
```

Which can be run with:

:::sh
dart bin\main.dart
:::

### Calling gRPC SSL Services

The [Dart gRPC Docs](/grpc/dart#dart-protoc-grpc-ssl-example) shows how we can connect to it via our gRPC SSL endpoint by running the openssl scripts in [grpc/scripts](https://github.com/NetCoreTemplates/grpc/tree/master/scripts) to generate our **dev.crt** and **prod.crt** SSL Certificates that you can configure in your in your **GrpcSecure** endpoint with:

```json
{
  "Kestrel": {
    "Endpoints": {
      "GrpcSecure": {
        "Url": "https://*:5051",
        "Protocols": "Http2",
        "Certificate": {
          "Path": "dev.pfx",
          "Password": "grpc"
        }
      }
    }
  }
}
```

Where you'll then be able to access the secure gRPC SSL endpoints using the generated **dev.crt** certificate in your Dart App:

```dart
import 'dart:io';
import 'package:grpc/grpc.dart';
import 'package:dart_grpc/services.pb.dart';
import 'package:dart_grpc/services.pbgrpc.dart';

GrpcServicesClient createClient({CallOptions options}) {
  return GrpcServicesClient(ClientChannel('localhost', port:5051,
    options:ChannelOptions(credentials: ChannelCredentials.secure(
        certificates: File('dev.crt').readAsBytesSync(),
        authority: 'localhost'))), options:options);
}

void main(List<String> args) async {

    var client = createClient();
    var response = await client.getQueryCategory(QueryCategory());
    print(response.results);

    exit(0);
}
```

### AutoGen's AutoRegister Implementation

Whilst the `AutoRegister = true` flag on its face may seem magical, it's simply an instruction that tells ServiceStack to register the **new** AutoQuery Services it already knows about and register them as if they were normal code-first Services that we had written ourselves.

More accurately, behind-the-scenes it uses the Metadata Type structure it constructed in generating the Services & Types, i.e. the same Types used to project into its Add ServiceStack Reference's generated C#, TypeScript, (and other languages) which are also the same Types that are manipulated when customizing code-generation, gets used to generate .NET Types in memory on Startup with Reflection.Emit. 

Barring any issues with the projection into IL, externally the end result is indistinguishable to a normal code-first ServiceStack Service manually created by a developer - An important point as to why these solutions compose well with the rest of ServiceStack, just as an AutoQuery Service is a normal ServiceStack Service, these auto generated & auto registered ServiceStack Services are regular Auto Query Services. 

The primary difference is that they only exist in a .NET Assembly in memory created on Startup, not in code so they're not "statically visible" to a C# compiler, IDE, tools, etc. But otherwise they're regular typed ServiceStack Services and can take advantage of the ecosystem around Services including [Add ServiceStack Reference](/add-servicestack-reference) & other Metadata Pages and Services, etc.

### CreateCrudServices Instructions

Peeking deeper behind the `AutoRegister` flag will reveal that it's a helper for adding an empty `CreateCrudServices` instance, i.e. it's equivalent to:

```csharp
Plugins.Add(new AutoQueryFeature {
    GenerateCrudServices = new GenerateCrudServices {
        CreateServices = {
            new CreateCrudServices()
        }
        //....
    }
});
```

#### Multiple Schemas and RDBMS Connections

This instructs ServiceStack to generate Services for the default option, i.e. all tables in the Database of the default registered Database connection and default schema.

Although should you wish to, you can also generate Services for multiple Databases and RDBMS Schemas within the same App.

With this you could have a single API Gateway Servicifying access to multiple System RDBMS Tables & Schemas, e.g:

```csharp
Plugins.Add(new AutoQueryFeature {
    GenerateCrudServices = new GenerateCrudServices {
        DbFactory = dbFactory,
        CreateServices = {
            new CreateCrudServices(),
            new CreateCrudServices { Schema = "AltSchema" },
            new CreateCrudServices { NamedConnection = "Reporting" },
            new CreateCrudServices { NamedConnection = "Reporting", Schema = "AltSchema" },
        }
        //....
    }
});
```

These will generated Service Contracts & DTO Types with the Multitenancy [NamedConnection](/autoquery/rdbms#named-connection) & OrmLite `[Schema]` attribute required for routing AutoQuery Services to use the appropriate RDBMS connection of Schema. 
 
Although there are potential conflicts if there are identical table names in each RDBMS/Schema as it has to go back and rewrite the Metadata References to use a non-ambiguous name, first tries using the NamedConnection, then the schema then a combination when both exists, if it's still ambiguous it gives up and ignores it. If you do run into conflicts, the recommendation is to "eject" the generated `.cs` sources and manually update them to use your preferred unique names.

### Customize Code Generation to include App Conventions

Being able to instantly generate AutoQuery Services for all your RDBMS tables is nice, but it's even nicer if you could easily customize the code-generation!

Together with the flexibility of the new declarative validation support you can compose a surprisingly large amount of your App's logic using the versatility of C# to automate embedding your App's conventions by annotating them on declarative Request DTOs.

The existing code-generation already infers a lot from your RDBMS schema which you can further augment using the available `GenerateCrudServices` filters:

 - `ServiceFilter` - called with every Service Operation
 - `TypeFilter` - called with every DTO Type
 - `IncludeService` - a predicate to return whether the **Service** should be included
 - `IncludeType` - a predicate to return whether the **Type** should be included
 - `TableSchemasFilter` - an action to modify the `List<TableSchema>` that AutoGen uses to generate data models

For an illustration of this in action, here's a typical scenario of how the Northwind AutoQuery Services could be customized:

 - Controlling which Tables **not to generate Services for** in `ignoreTables`
 - Which tables not to generate **Write Crud Services** for in `readOnlyTables`
 - Which tables to **restrict access** to in different roles in `protectTableByRole` 
 - Example of **additional validation** to existing tables in `tableRequiredFields`
   - Adds the `[ValidateNotEmpty]` attribute to Services accessing the table and the `[Required]` OrmLite attribute for the Data Model DTO Type.

```csharp
var ignoreTables = new[] { "IgnoredTable", }; // don't generate AutoCrud APIs for these tables
var readOnlyTables = new[] { "Region" };
var protectTableByRole = new Dictionary<string,string[]> {
    ["Admin"]    = new[] { nameof(CrudEvent), nameof(ValidationRule) },
    ["Accounts"] = new[] { "Order", "Supplier", "Shipper" },
    ["Employee"] = new[] { "Customer", "Order", "OrderDetail" },
    ["Manager"]  = new[] { "Product", "Category", "Employee", "UserAuth", "UserAuthDetails" },
};
var tableRequiredFields = new Dictionary<string,string[]> {
    ["Shipper"] = new[]{ "CompanyName", "Phone" },
};

Plugins.Add(new AutoQueryFeature {
    MaxLimit = 100,
    GenerateCrudServices = new GenerateCrudServices
    {
        DbFactory = dbFactory,
        ServiceFilter = (op,req) => 
        {
            // Require all Write Access to Tables to be limited to Authenticated Users
            if (op.IsCrudWrite())
            {
                op.Request.AddAttributeIfNotExists(new ValidateRequestAttribute("IsAuthenticated"), 
                    x => x.Validator == "IsAuthenticated");
            }

            // Limit Access to specific Tables
            foreach (var tableRole in protectTableByRole)
            {
                foreach (var table in tableRole.Value)
                {
                    if (op.ReferencesAny(table))
                        op.Request.AddAttribute(new ValidateHasRoleAttribute(tableRole.Key));
                }
            }

            // Add [ValidateNotEmpty] attribute on Services operating Tables with Required Fields
            if (op.DataModel != null && tableRequiredFields.TryGetValue(op.DataModel.Name, out var required))
            {
                var props = op.Request.Properties.Where(x => required.Contains(x.Name));
                props.Each(x => x.AddAttribute(new ValidateNotEmptyAttribute()));
            }
        },
        TypeFilter = (type, req) => 
        {
            // Add OrmLite [Required] Attribute on Tables with Required Fields
            if (tableRequiredFields.TryGetValue(type.Name, out var requiredFields))
            {
                var props = type.Properties.Where(x => requiredFields.Contains(x.Name));
                props.Each(x => x.AddAttribute(new RequiredAttribute()));
            }
        },
        //Don't generate the Services or Types for Ignored Tables
        IncludeService = op => !ignoreTables.Any(table => op.ReferencesAny(table)) &&
            !(op.IsCrudWrite() && readOnlyTables.Any(table => op.ReferencesAny(table))),

        IncludeType = type => !ignoreTables.Contains(type.Name),
    }
});

Plugins.Add(new ValidationFeature()); // Enable Validation
```

Additionally, the `TableSchemasFilter` can be used to modify the schema used by AutoGen to generate the types associated with your AutoQuery APIs. 
This gives you the opportunity to filter or modify the schema after they are pulled from the database.
For example, we could `Remove` tables based on naming, or alter column definitions to assist with any schema issues.

```csharp
GenerateCrudServices = new GenerateCrudServices {
    AutoRegister = true,
    AddDataContractAttributes = false,
    TableSchemasFilter = tableSchemas =>
    {
        // Don't include tables starting with an underscore
        tableSchemas.RemoveAll(tableSchema => tableSchema.Name.StartsWith("_"));
        // Don't include columns of "geometry" type.
        tableSchema.Columns.ToList().RemoveAll(x => x.DataTypeName == "geometry");
    }
}
```

To assist in code-generation a number of high-level APIs are available to help with identifying Services, e.g:

 - `operation.IsCrud()` - Is read-only AutoQuery or AutoCrud write Service
 - `operation.IsCrudWrite()` - Is AutoCrud write Service
 - `operation.IsCrudRead()` - Is AutoQuery read-only Service
 - `operation.ReferencesAny()` - The DTO Type is referenced anywhere in the Service (e.g. Request/Response DTOs, Inheritance, Generic Args, etc)
 - `type.InheritsAny()` - The DTO inherits any of the specified type names
 - `type.ImplementsAny()` - The DTO implements any of the specified interface type names


### Mixing generated AutoQuery Services & existing code-first Services

The expected use-case for these new features is that you'd create a new project that points to an existing database to bootstrap your project with code-first AutoQuery Services using the dotnet tool to download the generated types, i.e:

:::sh
`x csharp https://localhost:5001 -path /crud/all/csharp`
:::

At which point you'd "eject" from the generated AutoQuery Services (forgetting about this feature), copy the generated types into your **ServiceModel** project and continue on development as code-first Services just as if you'd created the Services manually.

But the `GenerateCrudServices` feature also supports a "hybrid" mode where you can also just generate Services for any **new** AutoQuery Services that don't exist, i.e. for tables for which there are no existing services which you can access their generated Services from:

:::sh
`x csharp https://localhost:5001 -path /crud/new/csharp`
:::

The existing `/crud/all/csharp` Service continues to return generated Services for all Tables but will stitch together and use existing types where they exist.

> If your new code first services are missing, remember to make sure your AppHost is scanning the assembly they belong to by using `typeof(MyGeneratedType).Assembly` in your `AppHost` base constructor.

### Trying it out

We now have all the features we need to quickly servicify an existing database that we can easily customize to apply custom App logic to further protect & validate access.

So you can quickly explore these new features locally, you can download the enhanced Northwind example with this customization above in the new [github.com/NetCoreApps/NorthwindCrud](https://github.com/NetCoreApps/NorthwindCrud) project which you can download & run with:

```bash
x download NetCoreApps/NorthwindCrud
cd NorthwindCrud
dotnet run
```

This example App is also configured with other new features in incoming release including Crud Events in 
[Startup.cs](https://github.com/NetCoreApps/NorthwindCrud/blob/master/Startup.cs):

```csharp
// Add support for auto capturing executable audit history for AutoCrud Services
container.AddSingleton<ICrudEvents>(c => new OrmLiteCrudEvents(c.Resolve<IDbConnectionFactory>()));
container.Resolve<ICrudEvents>().InitSchema();
```

As well as support for dynamically generated db rules in 
[Configure.Validation.cs](https://github.com/NetCoreApps/NorthwindCrud/blob/master/Configure.Validation.cs):

```csharp
services.AddSingleton<IValidationSource>(c => 
    new OrmLiteValidationSource(c.Resolve<IDbConnectionFactory>()));

appHost.Resolve<IValidationSource>().InitSchema();
```

To be able to test the custom code generation the example is pre-populated with 3 users with different roles in 
[Configure.Auth.cs](https://github.com/NetCoreApps/NorthwindCrud/blob/master/Configure.Auth.cs):

```csharp
// Register Users that don't exist
void EnsureUser(string email, string name, string[] roles=null)
{
    if (authRepo.GetUserAuthByUserName(email) != null) 
        return;
    
    authRepo.CreateUserAuth(new UserAuth {
        Email = email,
        DisplayName = name,
        Roles = roles?.ToList(),
    }, password:"p@ss");
}

EnsureUser("employee@gmail.com", name:"A Employee",   roles:new[]{ "Employee" });
EnsureUser("accounts@gmail.com", name:"Account Dept", roles:new[]{ "Employee", "Accounts" });
EnsureUser("manager@gmail.com",  name:"The Manager",  roles:new[]{ "Employee", "Manager" });
```

Of which you can also find published on [NorthwindCrud's home page](https://github.com/NetCoreApps/NorthwindCrud).

### AutoGen Customizations

AutoGen's [Instantly Servicify existing Systems](/servicify) feature works by automatically generating the AutoQuery & Crud APIs and Data Models for all tables in the configured RDBMS's. Further customization of the DataModel Names, the user-defined Route Path they're hosted at & the name of individual AutoQuery APIs for each operation using the `GenerateOperationsFilter`. 

So if you had an existing table name called `applications` the default convention based names would be:
 - Data Model: `Applications`
 - APIs: `CreateApplications`, `PatchApplications`, `QueryApplications`, etc
 - Route: `/applications`, `/applications/{Id}`

You can change each of these default conventions with the new `GenerateOperationsFilter`, e.g:

```csharp
Plugins.Add(new AutoQueryFeature {
    MaxLimit = 1000,
    GenerateCrudServices = new GenerateCrudServices {
        DbFactory = dbFactory,
        AutoRegister = true,
        GenerateOperationsFilter = ctx => {
            if (ctx.TableName == "applications")
            {
                ctx.DataModelName = "Application";
                ctx.PluralDataModelName = "Apps";
                ctx.RoutePathBase = "/apps";
                ctx.OperationNames = new Dictionary<string, string> {
                    [AutoCrudOperation.Create] = "CreateApp",
                    [AutoCrudOperation.Patch] = "ModifyApp",
                };
            }
        }
    }
});
```

Would result in:
 - Data Model: `Application`
 - APIs: `QueryApps`, `CreateApp`, `ModifyApp`
 - Route: `/apps`, `/apps/{Id}`

### Retrying Dart gRPC Example

We can see an immediate effect of these customizations in **NorthwindCrud** where most APIs now require Authentication:

![](/img/pages/release-notes/v5.9/northwindcrud-metadata.png)

If we then try to run our Dart `main.dart` example against the customized **NorthwindCrud** APIs by first regenerating gRPC protoc Types:

:::sh
`x proto-dart https://localhost:5001 -out lib`
:::

Then try rerunning `main.dart` where it will now fail with an **Unauthorized** exception:

![](/img/pages/release-notes/v5.9/northwindcrud-noauth.png)

To now be able to access most Services we'll need to [Authenticate as registered user](/grpc/dart#dart-grpc-authenticated-request-example).

As NorthwindCrud is [configured to use JWT](https://github.com/NetCoreApps/NorthwindCrud/blob/master/Configure.Auth.cs) we can create an Authenticated gRPC client by adding the populated JWT Token from an Authenticated Request into the **Authorization** gRPC metadata Header:

```dart
GrpcServicesClient createClient({CallOptions options}) {
  return GrpcServicesClient(ClientChannel('localhost', port:5054,
    options:ChannelOptions(credentials: ChannelCredentials.insecure())), 
    options:options);
}

void main(List<String> arguments) async {
    var authResponse = await createClient().postAuthenticate(
        Authenticate()..provider='credentials'..userName='manager@gmail.com'..password='p@ss');

    var authClient = createClient(options:CallOptions(metadata:{ 
            'Authorization': 'Bearer ${authResponse.bearerToken}' 
        }));

    var response = await authClient.getQueryCategory(QueryCategory());
    print(response.results);
    exit(0);
}
```

Now when we rerun `main.dart` we'll be able to access our Northwind categories again:

![](/img/pages/release-notes/v5.9/northwindcrud-jwtauth.png)


# AutoQuery CRUD Bookings Demo
Source: https://docs.servicestack.net/autoquery/bookings-crud

The powerfully productive combination of [AutoQuery](/autoquery/rdbms) and [Locode](/locode/) can be used to give **Authorized Users an Instant UI** to access AutoQuery Services resulting in an immediate fully queryable (inc. export to Excel) & management UI over system tables within minutes. By virtue of being normal ServiceStack Services, AutoQuery APIs also inherit ServiceStack's ecosystem of features like [Add ServiceStack Reference](/add-servicestack-reference) enabling high-performance end-to-end typed API access in all popular Web, Mobile & Desktop platforms.

## Creating a multi-user .NET Core Booking system in minutes!

To see the rapid development of AutoQuery in action we've created a quick demo showing how to create a simple multi-user Booking System from an empty [web](https://github.com/NetCoreTemplates/web) project, [mixed in](/mix-tool) with the preferred RDBMS & Auth layered functionality, before enabling [Validation](/validation), [AutoQuery](/autoquery/rdbms), Admin Users & [CRUD Event Log](/autoquery/audit-log) plugins - to lay the foundational features before building our App by first defining its `Booking` data model & its surrounding **Query**, **Create**, **Update** and **Soft Delete** Typed CRUD APIs with rich validation enforced by declarative Validation attributes and multi-layer authorization rules & access permissions protected using Authorization attributes.

All declarative functionality is accessible in Locode which is used to create new Employee & Manager Users, before signing in with each to hit the ground running and start entering new bookings using Locode's capability-based UI, with each change visible in its **Audit History**.

<lite-youtube class="w-full mx-4 my-4" width="560" height="315" videoid="rSFiikDjGos" style="background-image: url('https://img.youtube.com/vi/rSFiikDjGos/maxresdefault.jpg')"></lite-youtube>

### Download and Run

The quickest way to run the [Bookings AutoQuery Example](https://github.com/NetCoreApps/BookingsCrud) is to install the [x tool](/dotnet-tool), download & run the repo:

```bash
x download NetCoreApps/BookingsCrud
cd BookingsCrud\Acme
dotnet run
```

### Custom project from Scratch

If you have different App requirements you can instead create a project from scratch that integrates with your existing preferred infrastructure - the [mix tool](/mix-tool) and ServiceStack's layered [Modular Startup](/modular-startup) configurations makes this a cinch, start with an empty `web` project:

:::sh
x new web ProjectName
:::

Then mix in your desired features. E.g. In order for this project to be self-hosting it utilizes the embedded SQLite database, which we can configure along with configuration to enable popular Authentication providers and an RDBMS SQLite Auth Repository with:

:::sh
x mix auth auth-db sqlite
:::

But if you also wanted to enable the new [Sign in with Apple](/auth/signin-with-apple) and use SQL Server you'll instead run:

:::sh
x mix auth-ext auth-db sqlserver
:::

You can view all DB and Auth options available by searching for available layered gist configurations by tag:

```bash
x mix [db]
x mix [auth]
```

Typically the only configuration that needs updating is your DB connection string in [Configure.Db.cs](https://github.com/NetCoreApps/BookingsCrud/blob/main/Acme/Configure.Db.cs), in this case it's changed to use a persistent SQLite DB:

```csharp
services.AddSingleton<IDbConnectionFactory>(new OrmLiteConnectionFactory(
    Configuration.GetConnectionString("DefaultConnection") 
        ?? "bookings.sqlite",
    SqliteDialect.Provider));
```

You'll also want to create RDBMS tables for any that doesn't exist:

```csharp
using var db = appHost.Resolve<IDbConnectionFactory>().Open();
db.CreateTableIfNotExists<Booking>();
```

### Create Booking CRUD Services

The beauty of AutoQuery is that we only need to focus on the definition of our C# POCO Data Models which OrmLite uses to create the RDBMS tables and AutoQuery reuses to generates the Typed API implementations enabling us to build full functional high-performance systems with rich querying capabilities that we can further enhance with declarative validation & authorization permissions and rich integrations with the most popular platforms without needing to write any logic.

The `Booking` class defines the Data Model whilst the remaining AutoQuery & CRUD Services define the typed inputs, outputs and behavior of each API available that Queries and Modifies the `Booking` table.

An added utilized feature are the `[AutoApply]` attributes which applies generic behavior to AutoQuery Services.
The `Behavior.Audit*` behaviors below depend on the same property names used in the 
[AuditBase.cs](https://github.com/ServiceStack/ServiceStack/blob/master/src/ServiceStack.Interfaces/AuditBase.cs) 
class where:

  - `Behavior.AuditQuery` - adds an [Ensure AutoFilter](/autoquery/crud#autofilter) to filter out any deleted records
  - `Behavior.AuditCreate` - populates the `Created*` and `Modified*` properties with the Authenticated user info
  - `Behavior.AuditModify` - populates the `Modified*` properties with the Authenticated user info
  - `Behavior.AuditSoftDelete` - changes the behavior of the default **Real Delete** to a **Soft Delete** by  
   populating the `Deleted*` properties

```csharp
public class Booking : AuditBase
{
    [AutoIncrement]
    public int Id { get; set; }
    public string Name { get; set; }
    public RoomType RoomType { get; set; }
    public int RoomNumber { get; set; }
    public DateTime BookingStartDate { get; set; }
    public DateTime? BookingEndDate { get; set; }
    public decimal Cost { get; set; }
    public string Notes { get; set; }
    public bool? Cancelled { get; set; }
}

public enum RoomType
{
    Single,
    Double,
    Queen,
    Twin,
    Suite,
}

[AutoApply(Behavior.AuditQuery)]
public class QueryBookings : QueryDb<Booking>
{
    public int[] Ids { get; set; }
}

[ValidateHasRole("Employee")]
[AutoApply(Behavior.AuditCreate)]
public class CreateBooking
    : ICreateDb<Booking>, IReturn<IdResponse>
{
    public string Name { get; set; }
    [ApiAllowableValues(typeof(RoomType))]
    public RoomType RoomType { get; set; }
    [ValidateGreaterThan(0)]
    public int RoomNumber { get; set; }
    public DateTime BookingStartDate { get; set; }
    public DateTime? BookingEndDate { get; set; }
    [ValidateGreaterThan(0)]
    public decimal Cost { get; set; }
    public string Notes { get; set; }
}

[ValidateHasRole("Employee")]
[AutoApply(Behavior.AuditModify)]
public class UpdateBooking
    : IPatchDb<Booking>, IReturn<IdResponse>
{
    public int Id { get; set; }
    public string Name { get; set; }
    [ApiAllowableValues(typeof(RoomType))]
    public RoomType? RoomType { get; set; }
    [ValidateGreaterThan(0)]
    public int? RoomNumber { get; set; }
    public DateTime? BookingStartDate { get; set; }
    public DateTime? BookingEndDate { get; set; }
    [ValidateGreaterThan(0)]
    public decimal? Cost { get; set; }
    public bool? Cancelled { get; set; }
    public string Notes { get; set; }
}

[ValidateHasRole("Manager")]
[AutoApply(Behavior.AuditSoftDelete)]
public class DeleteBooking : IDeleteDb<Booking>, IReturnVoid
{
    public int Id { get; set; }
}
```

### Single Patch Partial Update API

Previously the Edit UI required the full update `IUpdateDb<T>` API, but now supports falling back to using a partial `IPatchDb<T>` API (if exists) where it will instead **only update the modified fields** that have changed. 

Ultimately this means for most cases you'll only need to provide a single `IPatchDb<T>` API to update your data model as it allows for the most flexible functionality of only updating any **non-null** values provided. This does mean that every property other than the primary key should either be a **nullable reference or Value Type** (i.e. using `Nullable`). 

Using `IPatchDb<T>` Partial Updates are also beneficial in [crud audit logs](/autoquery/audit-log) as they only capture the fields that have changed instead of full record `IUpdateDb<T>` updates.

`IPatchDb<T>` APIs can also be used to reset fields to `null` by specifying them in a `Reset` DTO string collection Property or **Request Param**, e.g. `?reset=Field1,Field2`.

## Manage in Locode

After defining your AutoQuery APIs, start your App then you can use the built-in [Locode UI](/locode/) to manage Bookings at:

<h3 class="text-4xl text-center text-indigo-800 pb-3"><span class="text-gray-300">https://example.org</span>/locode/</h3>

[![](/img/pages/locode/bookings-locode.png)](/locode/)


# Why not OData?
Source: https://docs.servicestack.net/autoquery/why-not-odata

[Microsoft's own Services Design guidelines](http://msdn.microsoft.com/en-us/library/ms954638.aspx) provides a good initial summary on why OData-like services are a Services anti-pattern:

 - There is virtually no contract. A service consumer has no idea how to use the service (for example, what are valid Command arguments, encoding expectations, and so on).
 - The interface errs on the side of being too liberal in what it will accept. 
 - The contract does not provide enough information to consumers on how to use the service. If a consumer must read something other than the service's signature to understand how to use the service, the factoring of the service should be reviewed.
 - Consumers are expected to be familiar with the database and table structures prior to consuming the Web service. This results in a tight coupling between service providers and consumers.
 - Performance will suffer due to dependencies on late binding and encoding/decoding between boundaries within the same service.

This is ultimately where many auto querying solutions fall down, they're typically executed with black-box binary implementations 
which only understand their opaque query languages normal Services wouldn't support, are exposed on unnatural routes you wouldn't use 
and return unclean verbose wire formats normal Services wouldn't return. So when it comes to needing to replace their 
implementation-specific APIs, it's often not feasible to reverse engineer a new implementation to match its existing Services contract and 
would need to resort in creating a new incompatible API, breaking existing clients and violating its Systems

### OData Example

We previously used one of [Netflix's OData examples to illustrate this](http://stackoverflow.com/a/9579090/85785) showing how to query for movies with specific ratings, a service available before [Netflix retired their OData catalog](http://developer.netflix.com/blog/read/Changes_to_the_Public_API_Program):

 > http://odata.netflix.com/Catalog/Titles?$filter=Type%20eq%20'Movie'%20and%20(Rating%20eq%20'G'%20or%20Rating%20eq%20'PG-13')

This service is effectively coupled to a Table/View called `Titles` and a column called `Type`. You're also coupled to the OData binary implementation inhibiting future optimizations or the ability to move to an optimal implementation in future e.g. leveraging a Search Index to serve part or the entire request. Use of special operators illegal in C#/.NET variable names like `$filter` shows that OData makes a point of exposing an API that wouldn't be developed naturally, it's effectively an isolated technology stack processing queries tunneled within its own custom namespace.

### Out of band knowledge in Free-form expressions

In order to understand how to consume this service you also have to be familiar with [the OData specification](http://www.odata.org/documentation/odata-version-4-0/) which due to its size and complexity ensures OData queries effectively become an opaque text blob invisible to your application that can only be processed by an OData binary that understands the OData spec. This was one of the major disadvantages of SOAP and WS-* specifications which due to its size and complexity forced the use of a SOAP Framework to be able to create services as opposed to simple HTTP API's which allow any language on any platform with a HTTP Server to be able to create Web Services. A pitfall free-form expressions encourage is having knowledge and opinions baked into client libraries, eventually mandating the use of specific consumer implementations. This is avoided with well-defined API boundaries ensuring that any service, of any complexity, can be called with just a URL and the API's published message forms.

### Tight Coupling of Internals

This service also requires knowledge of the internal structure of Netflix's DB schema to know what table and columns to query, more importantly once an OData API for your data model is published and has clients binded to it in production, the DB schema effectively becomes frozen since the OData query-space can reference any table and any column that was exposed.

### The ideal impl-agnostic movie ratings API

In contrast, if you were to create the service without using OData it would something like:

> http://api.netflix.com/movies?ratings=G,PG-13

i.e. just capturing the actual intent of the query, leaves complete freedom in how to best service the request whilst retaining the ability to evolve the underlying implementation without breaking existing clients.

## Goals of Service Design

The primary benefits of Services are that they offer the highest level of software re-use, they're [Real Computers all the way down](https://mythz.servicestack.net/#messaging) retaining the ability to represent anything. Especially at this level, encapsulation and its external interactions are paramount which sees the [Service Layer as its most important Contract](http://stackoverflow.com/a/15369736/85785), constantly evolving to support new capabilities whilst serving and outliving its many consumers. 

Extra special attention should be given to Service design with the primary goals of exposing its capabilities behind [consistent and self-describing](/why-servicestack#goals-of-service-design), intent-based [tell-dont-ask](http://pragprog.com/articles/tell-dont-ask) APIs - given its importance, it's not something that should be dictated by an internal implementation. 

A Services ability to encapsulate complexity is what empowers consumers to be able to perform higher-level tasks like provisioning a cluster of AWS servers or being able to send a tweet to millions of followers in seconds with just a simple HTTP request, i.e. being able to re-use existing hardened functionality without the required effort, resources and infrastructure to facilitate the request yourself. To maximize accessibility it's recommended for Service Interfaces to retain a flat structure, customizable with key value pairs so they're accessible via the built-in QueryString and FormData support present in all HTTP clients, from HTML Forms to command-line utilities like [curl](http://curl.haxx.se/).

## Unnecessary Complexity

Another reason we're opposed to considering technologies like OData is the sheer amount of unnecessary complexity of the implementation itself. Minimizing complexity is at the core essence of ServiceStack, it's why ServiceStack exists and remains the primary design goal in how features are implemented with the least complexity and cognitive overhead required.

### OData is Big

By contrast OData is comically large, there's literally an [entire Organization](http://www.odata.org/) created around it, sporting its own [blog](http://www.odata.org/blog/), [mailing list](http://www.odata.org/join-the-odata-discussion/), multiple [spec versions](http://www.odata.org/documentation/odata-version-4-0/) and [client libraries](http://www.odata.org/documentation/odata-version-4-0/) of which it appears only the Microsoft sponsored client libraries implement the latest v4 of the OData spec, as-is the nature of complicated rolling specs. 

Measuring size by weight shows `Microsoft.Data.OData.dll` alone weighs in at **1,287kb**, even more than `ServiceStack.dll`, surprising given [ServiceStack does a lot](https://servicestack.net/features). Include OData's required `Microsoft.Data.Edm.dll` and `System.Spatial.dll` NuGet dependencies and the payload increases another 50%, include integration with WebApi and client OData libraries and it bloats up further again.

### Why not Complexity

Imagine how much knowledge and cognitive overhead would be required to create a simple web app if every feature was over-engineered in this way? Every new feature introduces a complexity cost which is [why it's critically important](https://mythz.servicestack.net/#engineering) to ensure any complexity introduced [remains proportional](https://gist.github.com/cookrn/4015437) with the [needs being solved](http://worrydream.com/ABriefRantOnTheFutureOfInteractionDesign/). 

The needs in this case is [simplifying](http://www.infoq.com/presentations/Simple-Made-Easy) the creation and consumption of data-driven services, something which could easily have been implemented as a single feature point, has instead [been over-engineered](http://www.tele-task.de/player/embed/5819/0/?iframe) beyond belief and turned into something you can go on a training course and get certifications for! 

[Large implementations](http://steve-yegge.blogspot.com/2007/12/codes-worst-enemy.html) weakens our ability to reason about a system, to make informed decisions, to understand the impact of customization's and optimizations or identify the underlying cause of unintended behavior.

### Adding new Features without new Complexity

Rather than tacking on new libraries or inventing different ways/concepts/specs/dsl's for doing new things, features in ServiceStack are applied thoughtfully so they naturally integrate with its [existing architecture](/architecture-overview) maximizing re-use and leveraging existing functionality wherever possible, strengthening the existing mental model and ensuring new abstractions or concepts only get added for that of which is truly new.

## [Introducing AutoQuery](/autoquery#introducing-autoquery)

The solution to overcome most of OData issues is ultimately quite simple: enhance the ideal API the developer would naturally write and complete their implementation for them! This is essentially the philosophy behind AutoQuery which utilizes conventions to automate creation of intent-based self-descriptive APIs that are able to specify configurable conventions and leverage extensibility options to maximize the utility of AutoQuery services.


# Text to Blazor CRUD App
Source: https://docs.servicestack.net/autoquery/text-to-blazor

[Text to Blazor](https://servicestack.net/text-to-blazor) lets you rapidly generate new Blazor Admin CRUD Apps from just a text description.

<lite-youtube class="max-w-7xl aspect-video" videoid="Bd283EYJKxM" style="background-image: url('https://img.youtube.com/vi/Bd283EYJKxM/maxresdefault.jpg')"></lite-youtube>

[![](/img/pages/okai/text-to-blazor-prompt.webp)](https://servicestack.net/text-to-blazor)

<div class="pb-4 not-prose flex justify-center">
<a href="https://servicestack.net/text-to-blazor" class="text-3xl text-indigo-600 hover:text-indigo-800">https://servicestack.net/text-to-blazor</a>
</div>

This will query 5 different leading AI coding models to generate 5x different Data Models, APIs, DB Migrations and Admin UIs which you choose amongst to pick the best one that matches your requirements for your new CRUD App:

[![](/img/pages/okai/text-to-blazor-premium.webp)](/text-to-blazor)

### Using AI to only generate Data Models

Whilst the result is a working CRUD App, the approach taken is very different from most AI tools
which uses AI to generate the entire App that ends up with a whole new code-base developers didn't write
which they'd now need to maintain.

Instead AI is only used to **generate the initial Data Models** within a **TypeScript Declaration file** 
which we've found is the best format supported by AI models that's also the best typed DSL for defining
data models with minimal syntax that's easy for humans to read and write.

### Download preferred Blazor Vue CRUD App

Once you've decided on the Data Models that best matches your requirements, you can download your preferred 
generated Blazor Vue CRUD App:

[![](/img/pages/okai/text-to-blazor-download.webp)](https://servicestack.net/text-to-blazor)

### Blazor Admin App

**Admin Only** - is ideal for internal Admin Apps where the Admin UI is the Primary UI

![](/img/pages/okai/okai-blazor-admin.webp)

### Blazor Vue App

**UI + Admin** - Creates a new [blazor-vue](https://blazor-vue.web-templates.io) template, ideal for Internet or public facing Apps which sports a full-featured content rich UI for a Web App's users whilst providing a back-office Admin UI for Admin Users to manage the App's data.

![](/img/pages/okai/okai-blazor-vue.webp)

Clicking on the **Admin UI** button will take you to the Admin UI at `/admin`:

![](/img/pages/okai/okai-blazor-vue-admin.webp)

## Run Migrations

After downloading you'll then need to run the DB Migrations to create the App's Identity Auth and DB Tables:

:::sh
npm run migrate
:::

## Instant CRUD UI

Upon which you can hit the ground running and start using the Admin UI to manage the new Data Model RDBMS Tables!

:::youtube 8buo_ce3SNM
Using AutoQuery CRUD UI in a Text to Blazor App
:::

## Audited Data Models

The TypeScript Data Models enable a rapid development experience for defining an App's Data Models which are used
to generate the necessary AutoQuery CRUD APIs to support an Admin UI. 

An example of the productivity of this approach is the effortless support for maintaining a detailed audit history for changes to select tables by inheriting from the `AuditBase` base class, e.g:

```ts
export class Job extends AuditBase {
    ...
}
```

Which can then be regenerated using the name of the TypeScript Model definitions:

:::sh
npx okai Jobs.d.ts
:::

This will include additional `CreatedBy`, `CreatedDate`, `ModifiedBy`, `ModifiedDate`, `DeletedBy` and `DeletedDate`
properties to the specified Table and also generates the necessary 
[Audit Behaviors](https://docs.servicestack.net/autoquery/crud#apply-generic-crud-behaviors) 
on the AutoQuery APIs to maintain the audit history for each CRUD operation.

### AutoQuery CRUD Audit Log

As the **blazor-admin** and **blazor-vue** templates are configured to use 
[AutoQuery's Audit Log](/autoquery/audit-log) in its 
[Configure.AutoQuery.cs](https://github.com/NetCoreTemplates/blazor-admin/blob/main/MyApp/Configure.AutoQuery.cs)
the Audit Behaviors also maintains an Audit Trail of all CRUD operations, viewable in the Admin UI:

![](/img/pages/okai/okai-audit-form.webp)

## Customize Data Models

The generated CRUD Data Models and APIs can be further customized by authoring the
[TypeScript Data Models](/autoquery/okai-models)


# Generate CRUD APIs &#x2B; UI
Source: https://docs.servicestack.net/autoquery/okai-models

## AI powered Rapid App Development Workflow

The `okai` npm tool works similar to the online [Text to Blazor App](https://servicestack.net/text-to-blazor) creator
except it's a local tool that can add additional functionality to an existing project:

<ascii-cinema src="/img/pages/okai/okai-prompt-jobs.cast"
    loop="true" poster="npt:00:20" theme="dracula" rows="24" />

The syntax for adding a new feature to your ServiceStack App is `npx okai <prompt>`, e.g:

:::sh
npx okai "The kind of Feature you would like to add"
:::

Where it will generate the Data Models, AutoQuery CRUD APIs, DB Migrations and Admin UI for the 
selected feature which you'll see after selecting the LLM Data Models you want to use, e.g:

```sh
Selected 'deepseek-r1:70b' data models

Saved: /projects/MyApp/MyApp.ServiceModel/Jobs.d.ts
Saved: /projects/MyApp/MyApp.ServiceModel/Jobs.cs
Saved: /projects/MyApp/wwwroot/admin/sections/Jobs.mjs
Saved: /projects/MyApp/wwwroot/admin/sections/index.mjs
Saved: /projects/MyApp/Migrations/Migration1001.cs

Run 'dotnet run --AppTasks=migrate' to apply new migration and create tables

To regenerate classes, update 'Jobs.d.ts' then run:
$ okai Jobs.d.ts
```

Where okai will generate everything needed to support the feature in your App, including:

- `MyApp.ServiceModel/Jobs.d.ts` - TypeScript Data Models
- `MyApp.ServiceModel/Jobs.cs` - AutoQuery CRUD APIs and Data Models
- `wwwroot/admin/sections/Jobs.mjs` - Admin UI Section
  - requires `blazor-admin` or `blazor-vue` template
- `MyApp/Migrations/Migration1001.cs` - DB Migrations
  - requires project with [OrmLite DB Migrations](https://docs.servicestack.net/ormlite/db-migrations) 

## Creating Data Models from Scratch

You can also choose to create your TypeScript Data Models from scratch if you prefer not to start with generated AI Models, by running:

:::sh
npx okai init Todos.d.ts
:::

This will create a basic Data Model and run the code generation to generate the necessary files for it:

```txt
Saved: /projects/Acme/Acme.ServiceModel/api.d.ts
Saved: /projects/Acme/Acme.ServiceModel/Todos.cs
Saved: /projects/Acme/Acme/Migrations/Migration1002.cs
Saved: /projects/Acme/Acme/wwwroot/admin/sections/Todos.mjs
Saved: /projects/Acme/Acme/wwwroot/admin/sections/index.mjs
Saved: /projects/Acme/Acme.ServiceModel/Todos.d.ts

Run 'npm run migrate' to apply the new migration and create the new tables or:
$ dotnet run --AppTasks=migrate
```

With `Todos.d.ts` include the a reference to the [api.d.ts](https://okai.servicestack.com/api.d.ts) schema
and the necessary header config specifying which files it should generate along with an empty class where
you can start adding your Data Models for this feature:

```ts
/// <reference path="./api.d.ts" />
export type Config = {
  prompt:    "New Todo"
  api:       "~/Acme.ServiceModel/Todos.cs"
  migration: "~/Acme/Migrations/Migration1002.cs"
  uiMjs:     "~/Acme/wwwroot/admin/sections/Todos.mjs"
}

@tag("Todos")
export class Todo {
  id: number
  name: string
}
```

## Removing Data Models

If for whatever reason don't want the generated Data Models anymore, you can remove them from your code-base with:

:::sh
npx okai rm Todos.d.ts
:::

Which will remove the `*.d.ts` Data Models and all its associated generated files.

## Run Migrations

In order to create the necessary tables for any new functionality, you'll need to run the DB Migrations.

If migrations have never been run before, you can run the `migrate` npm script to create the initial database:

:::sh
npm run migrate
:::

This also lets you recreate it from scratch by running it after deleting the App's database (e.g. `App_Data/app.db`)

### Rerun Last Migration

If migrations have already been run, run the `rerun:last` npm script instead to **drop** and **re-run** the last migration:

:::sh
npm run rerun:last
:::

## Customize Data Models

The data models defined in the TypeScript Declaration file e.g. `Jobs.d.ts` is what drives the
generation of the Data Models, APIs, DB Migrations and Admin UIs.

This can be further customized by editing the TypeScript Declaration file and re-running the `okai` tool
with the name of the TypeScript Declaration file, e.g. `Jobs.d.ts`:

:::sh
npx okai Jobs.d.ts
:::

Which will re-generate the Data Models, APIs, DB Migrations and Admin UIs based on the updated Data Models.

![](/img/pages/okai/okai-Employees.webp)

:::tip
You only need to specify the `Jobs.d.ts` TypeScript filename (i.e. not the filepath) from
anywhere within your .NET solution
:::

### Live Code Generation

If you'd prefer to see the generated code in real-time you can add the `--watch` flag to watch the 
TypeScript Declaration file for changes and automatically re-generate the generated files on Save:

:::sh
npx okai Jobs.d.ts --watch
:::

<video autoplay="autoplay" loop="loop" controls>
    <source src="https://media.servicestack.com/videos/okai-watch.mp4" type="video/mp4">
</video>

## Declarative AI powered Features

The approach okai uses is very different from most AI tools which typically uses AI to generate an 
entire App or source code for a feature, instead okai only uses AI to generate the initial Data Models within 
a TypeScript Declaration `*.d.ts` file which we've found is best format supported by AI models that's also the 
best typed DSL for defining data models with minimal syntax that's easy for humans to read and write.

This is possible in ServiceStack since a significant portion of an App's functionality can be
[declaratively applied](https://docs.servicestack.net/locode/declarative) inc. 
[AutoQuery CRUD APIs](https://docs.servicestack.net/autoquery/crud) which can be implemented using only
Request DTOs to define the shape of the API to implement.

From the Data Models, the rest of the feature is generated using declarative classes depending
on the template used. 

### Generated Admin CRUD UI

To generate a CRUD Admin UI you'll need to use okai within a new Blazor Admin project or 
Blazor Vue ([blazor-vue](https://blazor-vue.web-templates.io)) project:

:::sh
x new blazor-admin Acme
:::

Which support a "Modular no-touch" Admin UI that will appear under a new group in the Admin Sidebar:

![](/img/pages/okai/okai-blazor-admin.webp)

## Modular Code Generation

Instead of unleashing AI on your code-base unabated, okai only uses AI to generate isolated functionality 
into grouped "no touch" source files that can be easily maintained and extended.

Creating a new Project with a similar prompt above would create a new project with the new source files
(marked `*`) added to the existing project:

### APIs

```files
/MyApp.ServiceModel
    Bookings.cs
    api.d.ts*
    Employees.cs*
    Employees.d.ts*
```

### Migration

```files
/MyApp/Migrations
    Migration1000.cs
    Migration1001.cs*
```

### UI

```files
/MyApp/wwwroot/admin
    /sections
        Bookings.mjs
        Employees.mjs*
        index.mjs*
    index.html
```

## Audited Data Models

The Instant CRUD UI also includes effortless support for maintaining a detailed audit history for changes to 
select tables by inheriting from the `AuditBase` base class, e.g:

```ts
export class Job extends AuditBase {
    ...
}
```

This will include additional `CreatedBy`, `CreatedDate`, `ModifiedBy`, `ModifiedDate`, `DeletedBy` and `DeletedDate`
properties to the specified Table and also generates the necessary [Audit Behaviors](https://docs.servicestack.net/autoquery/crud#apply-generic-crud-behaviors)
on the AutoQuery APIs to maintain the audit history for each CRUD operation.

### AutoQuery CRUD Audit Log

As the **blazor-admin** and **blazor-vue** templates are configured to use the [AutoQuery CRUD Executable Audit Log](https://docs.servicestack.net/autoquery/audit-log)
in its [Configure.AutoQuery.cs](https://github.com/NetCoreTemplates/blazor-admin/blob/main/MyApp/Configure.AutoQuery.cs)
the Audit Behaviors will also maintain an Audit Trail of all CRUD operations which can be viewed in the Admin UI:

![](/img/pages/okai/okai-audit-form.webp)

## TypeScript Schema

In addition to being a great DSL for defining Data Models, using TypeScript also lets us define a schema
containing all the C# Types, interfaces, and attributes used in defining APIs, DTOs and Data Models in 
the accompanying [api.d.ts](https://okai.servicestack.com/api.d.ts) file.

This now lets us use TypeScript to define the [Bookings.cs](https://github.com/NetCoreTemplates/blazor-vue/blob/main/MyApp.ServiceModel/Bookings.cs) 
AutoQuery APIs and Data Models which blazor-admin uses instead in its [Bookings.d.ts](https://github.com/NetCoreTemplates/blazor-admin/blob/main/MyApp.ServiceModel/Bookings.d.ts):

```ts
/// <reference path="./api.d.ts" />
export type Config = {
    prompt:    "New Booking"
    api:       "~/MyApp.ServiceModel/Bookings.cs"
    migration: "~/MyApp/Migrations/Migration1001.cs"
    uiMjs:     "~/MyApp/wwwroot/admin/sections/Bookings.mjs"
}

export enum RoomType {
  Single,
  Double,
  Queen,
  Twin,
  Suite,
}

@Read.route("/bookings","GET")
@Read.route("/bookings/{Id}","GET")
@Read.description("Find Bookings")
@Create.route("/bookings","POST")
@Create.description("Create a new Booking")
@Update.notes("Find out how to quickly create a <a href='https://youtu.be/nhc4MZufkcM'>C# Bookings App from Scratch</a>")
@Update.route("/booking/{Id}","PATCH")
@Update.description("Update an existing Booking")
@Delete.route("/booking/{Id}","DELETE")
@Delete.description("Delete a Booking")
@tag("Bookings")
@icon({svg:"<svg>...</svg>"})
@notes("Captures a Persons Name & Room Booking information")
@description("Booking Details")
@validateHasRole("Employee")
export class Booking extends AuditBase {
  @autoIncrement()
  id: number
  @Create.description("Name this Booking is for")
  @validateNotEmpty()
  name: string
  roomType: RoomType
  @validateGreaterThan(0)
  roomNumber: number
  @intlDateTime(DateStyle.Long)
  bookingStartDate: Date
  @intlRelativeTime()
  bookingEndDate?: Date
  @intlNumber({currency:"USD"})
  @validateGreaterThan(0)
  cost: decimal
  @ref({model:"nameof(Coupon)",refId:"nameof(Coupon.Id)",refLabel:"nameof(Coupon.Description)"})
  @references("typeof(Coupon)")
  couponId?: string
  @reference()
  discount?: Coupon
  @input({type:"textarea"})
  notes?: string
  cancelled?: boolean
  @reference({selfId:"nameof(CreatedBy)",refId:"nameof(User.UserName)",refLabel:"nameof(User.DisplayName)"})
  employee: User
}

@tag("Bookings")
@icon({svg:"<svg>...</svg>"})
export class Coupon extends AuditBase {
  id: string
  description: string
  discount: number
  expiryDate: Date
}
```

The benefit of this approach being that you can make a change to the Data Models and rerun the okai tool
to regenerate the AutoQuery APIs, DB Migrations and Admin UIs.

:::sh
npx okai Bookings.d.ts
:::

Which will regenerate its:
- APIs: [MyApp.ServiceModel/Bookings.cs](https://github.com/NetCoreTemplates/blazor-admin/blob/main/MyApp.ServiceModel/Bookings.cs)
- DB Migration: [MyApp/Migrations/Migration1000.cs](https://github.com/NetCoreTemplates/blazor-admin/blob/main/MyApp/Migrations/Migration1000.cs)
- Admin UI: [/wwwroot/admin/sections/Bookings.mjs](https://github.com/NetCoreTemplates/blazor-admin/blob/main/MyApp/wwwroot/admin/sections/Bookings.mjs)

What files will be generated is controlled by its `Config` section: 

```ts
export type Config = {
    prompt:    "New Booking"
    api:       "~/MyApp.ServiceModel/Bookings.cs"
    migration: "~/MyApp/Migrations/Migration1001.cs"
    uiMjs:     "~/MyApp/wwwroot/admin/sections/Bookings.mjs"
}
```

So if you no longer want the code regeneration to update the DB Migration for it, you can just remove it
from the Config.

## Rerunning Code Generation

The data models defined in the TypeScript Declaration file e.g. `Bookings.d.ts` is what drives the
generation of the Data Models, APIs, DB Migrations and Admin UIs.

This can be further customized by editing the TypeScript Declaration file and re-running the `okai` tool
with the name of the TypeScript Declaration file, e.g. `Bookings.d.ts`:

:::sh
npx okai Bookings.d.ts
:::

Which will re-generate the Data Models, APIs, DB Migrations and Admin UIs based on the updated Data Models.

![](/img/pages/okai/okai-Employees.webp)

Or add `--watch` to watch the TypeScript `*.d.ts` file for changes and automatically run code generation on Save:

:::sh
npx okai Bookings.d.ts --watch
:::

:::tip
You only need to specify the `Bookings.d.ts` TypeScript filename (i.e. not the filepath) from 
anywhere within your .NET solution
:::

### Single Data Model

One challenge with this approach is that there's only a single class used to define attributes for the Data Model,
Request and Response DTOs for all AutoQuery CRUD APIs.

### Smart API and Data Model attributes 

The okai tool resolves some issues with smart generation of attributes where any **"Data Model Attributes"**
like `[Icon]` class and `[AutoIncrement]` property attributes are only generated on the Data Model:

```ts
@icon({svg:"<svg>...</svg>"})
export class Booking {
    @autoIncrement()
    id: number
    @intlNumber({currency:"USD"})
    cost: decimal
}
```

Whilst **"API Attributes"** like `[Tag]` and `[ValidateHasRole]` class attribute and `[ValidateGreaterThan]` 
property attributes and are only generated on the APIs Request DTOs:

```ts
@tag("Bookings")
@validateHasRole("Employee")
export class Booking {
    @validateGreaterThan(0)
    cost: decimal
}
```

### Using C# Types in TypeScript Models

As JavaScript only has a limited set of types, the TypeScript **api.d.ts** schema also includes the 
built-in C# Types used when defining APIs, DTOs and Data Models which you'll be able to use when your
APIs need to use a specific .NET type, e.g:

```ts
export class Booking extends AuditBase {
  id: number
  name: string
  roomNumber: number
  bookingStartDate: Date
  bookingEndDate?: DateOnly
  cost: decimal
  cancelled?: boolean
}
```
 
Which uses the `DateOnly` and `decimal` .NET Types in its code generation:

```csharp
public class Booking : AuditBase
{
    [AutoIncrement]
    public int Id { get; set; }
    public string Name { get; set; }
    public int RoomNumber { get; set; }
    public DateTime BookingStartDate { get; set; }
    public DateOnly? BookingEndDate { get; set; }
    public decimal Cost { get; set; }
    public bool? Cancelled { get; set; }
}
```

### API Targeted Attributes

When you need to add attributes to a specific API Request DTO you can use a **CRUD prefix** to have it only
applied to that specific AutoQuery API, e.g:

```ts
@Read.route("/bookings","GET")
@Read.route("/bookings/{Id}","GET")
@Create.route("/bookings","POST")
```

Where it would only the generated on the AutoQuery API that it targets, e.g:

```csharp
[Route("/bookings", "GET")]
[Route("/bookings/{Id}", "GET")]
public class QueryBookings : QueryDb<Booking> { ... }

[Route("/bookings", "POST")]
public class CreateBooking : ICreateDb<Booking>, IReturn<IdResponse> { ... }
```

In addition to `Create.*`, `Read.*`, `Update.*`, `Delete.*` attributes to target specific AutoQuery CRUD APIs, 
you can also use `Write.*` to target all `Create`, `Update`, `Delete` write APIs.

### Ambiguous Attributes

Attributes that can be annotated on both the Data Model and API Request DTOs like `[Notes]` and `[Description]` 
are only generated on the Data Model and require using targeted attributes to apply to them to 
API Request DTOs, e.g:

```ts
@Read.description("Find Bookings")
@Create.description("Create a new Booking")
@Update.notes("Find out how to quickly create a <a href='https://youtu.be/nhc4MZufkcM'>C# Bookings App from Scratch</a>")
@Update.description("Update an existing Booking")
@Delete.description("Delete a Booking")
@notes("Captures a Persons Name & Room Booking information")
@description("Booking Details")
export class Booking extends AuditBase { ... }
```

Where the non-prefixed `@notes` and `@description` attributes are only generated on the Data Model whilst the 
targeted attributes are generated on their respective DTOs, e.g: 

```csharp
[Description("Find Bookings")]
public class QueryBookings : QueryDb<Booking> { ... }

[Description("Create a new Booking")]
public class CreateBooking : ICreateDb<Booking>, IReturn<IdResponse> { ... }

[Notes("Find out how to quickly create a <a href='https://youtu.be/nhc4MZufkcM'>C# Bookings App from Scratch</a>")]
[Description("Update an existing Booking")]
public class UpdateBooking : IPatchDb<Booking>, IReturn<IdResponse> { ... }

[Description("Delete a Booking")]
public class DeleteBooking : IDeleteDb<Booking>, IReturnVoid { ... }
    
[Description("Booking Details")]
[Notes("Captures a Persons Name & Room Booking information")]
public class Booking : AuditBase { ... }
```

### Special Attribute Values

There's special behavior for `"nameof(...)"` and `"typeof(...)"` string attribute values where: 

```ts
export class Booking extends AuditBase {
    @ref({model: "nameof(Coupon)", refId: "nameof(Coupon.Id)", refLabel: "nameof(Coupon.Description)"})
    @references("typeof(Coupon)")
    couponId?: string
}
```

Will be generated with native C# syntax, i.e. instead of as strings:

```csharp
public class Booking : AuditBase
{
    [Ref(Model=nameof(Coupon),RefId=nameof(Coupon.Id),RefLabel=nameof(Coupon.Description))]
    [References(typeof(Coupon))]
    public string? CouponId { get; set; }
}
```

### Changing Default Attributes

To improve the default out-of-the-box experience some attributes are included by default, including:

 - `[Icon]` attribute on Data Models based on the Data Model name
   - prevent by adding empty `@icon()` attribute
 - `[AutoIncrement]` on `id` number properties if no other `[PrimaryKey]` attribute is defined
   - prevent by adding `@primaryKey()` or `@autoId()`
 - `[Validate*]` attributes added to Create/Update APIs on non-nullable properties
   - prevent by adding empty `@validate()` attribute

Here's an example which changes the default behavior for the default attributes above:

```ts
@icon()
export class Todo {
    @primaryKey()
    id: number
    @validate()
    name: string
}
```

Which will generate the C# APIs without the `[Icon]` and `[Validate]` attributes and replace `[AutoIncrement]`
with `[PrimaryKey]`, e.g:

```csharp
public class CreateTodo : ICreateDb<Todo>, IReturn<IdResponse>
{
    [ValidateGreaterThan(0)]
    public int Id { get; set; }
    public string Name { get; set; }
}

public class Todo
{
    [PrimaryKey]
    public int Id { get; set; }
    public string Name { get; set; }
}
```

### Modifying ApplicationUser

In many cases the AI Models will want to generate a `User` class for their AI models. But as Blazor Apps
are already configured to use an `ApplicationUser` Identity Auth User class, the C# code generation only generates
the `User` class in a block comment with an instruction to merge it with your existing `User` class if you want to, e.g:

```csharp
/* merge with User DTO
/// <summary>
/// Interface defining the structure for a JobApplication.
/// Represents a user's application to a specific job.
/// </summary>
public class User
{
    [AutoIncrement]
    public int Id { get; set; }
    public string FirstName { get; set; }
    public string LastName { get; set; }
    public string Email { get; set; }
    /// <summary>
    /// Optional URL to the user's resume
    /// </summary>
    public string? ResumeUrl { get; set; }
}
*/
```

If you wish to add additional properties, you'll first need to add it your `ApplicationUser` class, e.g:

```csharp
public class ApplicationUser : IdentityUser
{
    public string? FirstName { get; set; }
    public string? LastName { get; set; }
    public string? DisplayName { get; set; }
    public string? ProfileUrl { get; set; }
    /// <summary>
    /// Optional URL to the user's resume
    /// </summary>
    public string? ResumeUrl { get; set; }
}
```

### Regenerating Identity Auth EF Migrations

You'll then need to regenerate the EF Migration to update the `AspNetUsers` table with the new columns by
running the `init-ef` npm script:

:::sh
npm run init-ef
:::

Which will delete the existing Migrations and create a new Migration to update the Identity Auth tables:

```json
{
    "scripts": {
        "init-ef": "node -e 'fs.readdirSync(`Migrations`).filter(x => !x.startsWith(`Migration`)).forEach(x => fs.rmSync(`Migrations/${x}`))' && dotnet ef migrations add CreateIdentitySchema",
    }
}
```

You can then delete your Primary Database (e.g. App_Data/app.db) and re-run the `migrate` npm script to recreate it:

:::sh
npm run migrate
:::

If you want the additional property to also be included in API Responses you'll also need to add it to your `User` DTO, e.g:

```csharp
/// <summary>
/// Public User DTO
/// </summary>
[Alias("AspNetUsers")]
public class User
{
    public string Id { get; set; }
    public string UserName { get; set; }
    public string? FirstName { get; set; }
    public string? LastName { get; set; }
    public string? DisplayName { get; set; }
    public string? ProfileUrl { get; set; }

    public string? ResumeUrl { get; set; }
}
```

Which OrmLite and AutoQuery will use to query Identity Auth's `AspNetUsers` table.

### Custom APIs

When you need more fine-grained control over the generated APIs, you can "takeover" the generation of
an AutoQuery API by explicitly defining it yourself.

So if you prefer to use explicit API Request DTOs instead of targeted API attributes or need to control
the exact properties generated in each API, you can define the API Request DTOs yourself where when exists 
will skip generation for that API.

To showcase the differences between the single class approach, you can rewrite the above single class
approach with an explicit class for each AutoQuery API:

```ts
export enum RoomType {
  Single,
  Double,
  Queen,
  Twin,
  Suite,
}

@tag("Bookings")
@notes("Captures a Persons Name & Room Booking information")
@route("/bookings","GET")
@route("/bookings/{Id}","GET")
@autoApply(Behavior.AuditQuery)
@description("Find Bookings")
export class QueryBookings extends QueryDb<Booking> {
  id?: number
}

@tag("Bookings")
@route("/bookings","POST")
@autoApply(Behavior.AuditCreate)
@description("Create a new Booking")
@validateHasRole("Employee")
export class CreateBooking implements ICreateDb<Booking>, IReturn<IdResponse> {
  name?: string
  roomType?: RoomType
  @validateGreaterThan(0)
  roomNumber?: number
  bookingStartDate?: Date
  bookingEndDate?: Date
  @validateGreaterThan(0)
  cost?: decimal
  couponId?: string
  discount?: Coupon
  @input({type:"textarea"})
  notes?: string
  cancelled?: boolean
}

@tag("Bookings")
@route("/bookings","PATCH")
@autoApply(Behavior.AuditModify)
@description("Create a new Booking")
@validateHasRole("Employee")
export class UpdateBooking implements IPatchDb<Booking>, IReturn<IdResponse> {
  name?: string
  roomType?: RoomType
  @validateGreaterThan(0)
  roomNumber?: number
  bookingStartDate?: Date
  bookingEndDate?: Date
  @validateGreaterThan(0)
  cost?: decimal
  couponId?: string
  discount?: Coupon
  @input({type:"textarea"})
  notes?: string
  cancelled?: boolean
}

@tag("Bookings")
@route("/bookings/{Id}","DELETE")
@autoApply(Behavior.AuditSoftDelete)
@description("Delete a Booking")
@validateHasRole("Manager")
export class DeleteBookings implements IDeleteDb<Booking>, IReturnVoid {
  id?: number
}

@tag("Bookings")
@notes("Captures a Persons Name & Room Booking information")
@route("/bookings","GET")
@route("/bookings/{Id}","GET")
@description("Find Bookings")
export class Booking extends AuditBase {
  @autoIncrement()
  id: number
  @Create.description("Name this Booking is for")
  @Create.validateNotEmpty()
  name: string
  roomType: RoomType
  roomNumber: number
  @intlDateTime(DateStyle.Long)
  bookingStartDate: Date
  @intlRelativeTime()
  bookingEndDate?: Date
  @intlNumber({currency:"USD"})
  cost: decimal
  @ref({model:"nameof(Coupon)",refId:"nameof(Coupon.Id)",refLabel:"nameof(Coupon.Description)"})
  @references("typeof(Coupon)")
  couponId?: string
  @reference()
  discount?: Coupon
  @Write.input({type:"textarea"})
  notes?: string
  cancelled?: boolean
  @reference({selfId:"nameof(CreatedBy)",refId:"nameof(User.UserName)",refLabel:"nameof(User.DisplayName)"})
  employee: User
}

@description("Discount Coupons")
export class Coupon extends AuditBase {
  id: string
  description: string
  discount: number
  expiryDate: Date
}

@tag("Bookings")
@route("/coupons","GET")
@autoApply(Behavior.AuditQuery)
@description("Find Coupons")
export class QueryCoupons extends QueryDb<Coupon> {
  id?: string
}

@tag("Bookings")
@route("/coupons","POST")
@autoApply(Behavior.AuditCreate)
@description("Create a new Create")
@validateHasRole("Employee")
export class CreateCoupon implements ICreateDb<Coupon>, IReturn<IdResponse> {
  id: string
  description: string
  discount: number
  expiryDate: Date
}

@tag("Bookings")
@route("/coupons","PATCH")
@autoApply(Behavior.AuditModify)
@description("Create a new Coupon")
@validateHasRole("Employee")
export class UpdateCoupon implements IPatchDb<Coupon>, IReturnVoid {
  id: string
  description?: string
  discount?: number
  expiryDate?: Date
}

@tag("Bookings")
@route("/coupons/{Id}","DELETE")
@autoApply(Behavior.AuditSoftDelete)
@description("Delete a Coupon")
@validateHasRole("Manager")
export class DeleteCoupon implements IDeleteDb<Coupon>, IReturnVoid {
  id?: string
}
```


# Generate CRUD APIs and UIs for existing DBs
Source: https://docs.servicestack.net/autoquery/okai-db

A core piece of functionality in the [Text to Blazor CRUD App](/autoquery/text-to-blazor) feature is distilling an AI Prompt into TypeScript classes that can be [further customized](/autoquery/okai-models#customize-data-models)
to generate AutoQuery CRUD APIs and Admin UIs for managing the underlying RDBMS tables.

## TypeScript Data Models

Using TypeScript is an effortless way to define data models, offering a DSL-like minimal boilerplate format that's human-friendly to read and write which can leverage TypeScript's powerful Type System is validated against the referenced [api.d.ts](https://okai.servicestack.com/api.d.ts) schema to provide a rich authoring experience 
with strong typing and intellisense - containing all the C# Types, interfaces, and attributes used in defining APIs, DTOs and Data Models.

### Blueprint for Code Generation

The TypeScript Data Models serve as the blueprint for generating everything needed to support the feature 
in your App, including the AutoQuery **CRUD APIs**, **Admin UIs** and **DB Migrations** that can re-create the necessary tables from scratch.

## 1. Generate RDBMS Metadata

The first step in generating TypeScript Data Models is to capture the metadata from the existing RDBMS tables which
we can do with the `App.json` [AppTask](https://docs.servicestack.net/app-tasks) below which uses your App's configured
RDBMS connection to generate the Table Definitions for all tables in the specified RDBMS connection and schema
to the file of your choice (e.g `App_Data/App.json`):

```csharp
AppTasks.Register("App.json", args =>
  appHost.VirtualFiles.WriteFile("App_Data/App.json",ClientConfig.ToSystemJson(
      migrator.DbFactory.GetTables(namedConnection:null, schema:null))));
```

This task can then be run from the command line with:

:::sh
dotnet run --AppTasks=App.json
:::

Which generates `App_Data/App.json` containing the table definition metadata for all tables in 
the specified RDBMS, e.g:

```json
[
  {
    "name": "AspNetUserClaims",
    "columns": [
      {
        "columnName": "Id",
        "columnOrdinal": 0,
        "columnSize": -1,
        "numericPrecision": 0,
        "numericScale": 0,
        "isUnique": true,
        "isKey": true,
        "baseCatalogName": "techstacks",
        "baseColumnName": "Id",
        "baseSchemaName": "public",
        "baseTableName": "AspNetUserClaims",
        "dataType": "System.Int32",
        "allowDBNull": false,
        "providerType": 9,
        "isAliased": false,
        "isExpression": false,
        "isAutoIncrement": true,
        "isRowVersion": false,
        "isHidden": false,
        "isLong": false,
        "isReadOnly": false,
        "dataTypeName": "integer",
        "columnDefinition": "INTEGER PRIMARY KEY AUTOINCREMENT"
      },
    ],
  ...
]
```

### Different Connection or DB Schema

If you prefer to generate the metadata for a different connection or schema, you can create a new AppTask 
with your preferred `namedConnection` and/or `schema`, e.g:

```csharp
AppTasks.Register("Sales.json", args =>
  appHost.VirtualFiles.WriteFile("Sales.json", ClientConfig.ToSystemJson(
    migrator.DbFactory.GetTables(namedConnection:"reports",schema:"sales"))));
```

That you could then generate with:

:::sh
dotnet run --AppTasks=Sales.json
:::

## 2. Generate TypeScript Data Models

The next step is to generate TypeScript Data Models from the captured metadata which can be done with the `okai` tool
by running the `convert` command with the path to the `App.json` JSON table definitions which will generate the 
TypeScript Data Models to stdout which can be redirected to a file in your **ServiceModel** project, e.g:

:::sh
npx okai convert App_Data/App.json > ../MyApp.ServiceModel/App.d.ts  
:::

## 3. Generate CRUD APIs and Admin UIs

The data models defined in the `App.d.ts` TypeScript Declaration file is what drives the generation of the Data Models, APIs, DB Migrations and Admin UIs. This can be further customized by editing the TypeScript Declaration file and re-running the `okai` tool with just the filename, e.g:

:::sh
npx okai App.d.ts
:::

Which will re-generate the Data Models, APIs, DB Migrations and Admin UIs based on the updated Data Models.

![](/img/pages/okai/npx-okai-App.png)

:::tip
You only need to specify the `App.d.ts` TypeScript filename (i.e. not the filepath) from
anywhere within your .NET solution
:::

## Live Code Generation

If you'd prefer to see the generated code in real-time you can add the `--watch` flag to watch the
TypeScript Declaration file for changes and automatically re-generate the generated files on Save:

:::sh
npx okai App.d.ts --watch
:::

<video autoplay="autoplay" loop="loop" controls>
    <source src="https://media.servicestack.com/videos/okai-watch.mp4" type="video/mp4">
</video>


# Free LLM Chat Prompts
Source: https://docs.servicestack.net/autoquery/okai-chat

## okai chat

As part of the development of [okai](/autoquery/okai-models) for generating [Blazor CRUD Apps from a text prompt](/autoquery/text-to-blazor) using your preferred AI Models, we've also made available a generic **chat** prompt that can be used as a convenient way to conduct personal research against many of the worlds most popular Large Language Models - for Free!

:::{.px-8}
![](/img/pages/okai/okai-chat.webp)
:::

You can just start immediately using the `npx okai chat` script to ask LLMs for assistance:

:::sh
npx okai chat "command to copy a folder with rsync?"
:::

This will use the default model (currently codestral:22b) to answer your question.

### Select Preferred Model

You can also use your preferred model with the `-m <model>` flag with either the model **name** or its **alias**, e.g you can use 
[Microsoft's PHI-4 14B](https://techcommunity.microsoft.com/blog/aiplatformblog/introducing-phi-4-microsoft%E2%80%99s-newest-small-language-model-specializing-in-comple/4357090) 
model with:

:::sh
npx okai -m phi chat "command to copy folder with rsync?"
:::

### List Available Models

We're actively adding more great performing and leading experimental models as they're released. 
You can view the list of available models with `ls models`:

:::sh
npx okai ls models
:::

Which at this time will return the following list of available models along with instructions for how to use them:

```txt
USAGE (5 models max):
a) OKAI_MODELS=codestral,llama3.3,flash
b) okai -models codestral,llama3.3,flash <prompt>
c) okai -m flash chat <prompt>

FREE MODELS:
claude-3-haiku            (alias haiku)
codestral:22b             (alias codestral)
deepseek-r1:32b          
deepseek-r1:671b          (alias deepseek-r1)
deepseek-r1:70b          
deepseek-r2:32b          
deepseek-v3:671b          (alias deepseek)
gemini-flash-1.5         
gemini-flash-1.5-8b       (alias flash-8b)
gemini-flash-2.0          (alias flash)
gemini-flash-lite-2.0     (alias flash-lite)
gemini-flash-thinking-2.0 (alias flash-thinking)
gemini-pro-2.0            (alias gemini-pro)
gemma2:9b                 (alias gemma)
gpt-3.5-turbo             (alias gpt-3.5)
gpt-4o-mini              
llama3.1:70b              (alias llama3.1)
llama3.3:70b              (alias llama3.3)
llama3:8b                 (alias llama3)
mistral-nemo:12b          (alias mistral-nemo)
mistral-small:24b         (alias mistral-small)
mistral:7b                (alias mistral)
mixtral:8x22b            
mixtral:8x7b              (alias mixtral)
nova-lite                
nova-micro               
phi-4:14b                 (alias phi,phi-4)
qwen-plus                
qwen-turbo               
qwen2.5-coder:32b         (alias qwen2.5-coder)
qwen2.5:32b              
qwen2.5:72b               (alias qwen2.5)
qwq:32b                   (alias qwq)
qwq:72b                  

PREMIUM MODELS: *
claude-3-5-haiku         
claude-3-5-sonnet        
claude-3-7-sonnet         (alias sonnet)
claude-3-sonnet          
gemini-pro-1.5           
gpt-4                    
gpt-4-turbo              
gpt-4o                   
mistral-large:123b       
nova-pro                 
o1-mini                  
o1-preview               
o3-mini                  
qwen-max                 

 * requires valid license:
a) SERVICESTACK_LICENSE=<key>
b) SERVICESTACK_CERTIFICATE=<LC-XXX>
c) okai -models <premium,models> -license <license> <prompt>
```

Where you'll be able to use any of the great performing inexpensive models listed under `FREE MODELS` for Free.
Whilst ServiceStack customers with an active commercial license can also use any of the  more expensive
and better performing models listed under `PREMIUM MODELS` by either:

 a) Setting the `SERVICESTACK_LICENSE` Environment Variable with your **License Key**
 b) Setting the `SERVICESTACK_CERTIFICATE` Variable with your **License Certificate**
 c) Inline using the `-license` flag with either the **License Key** or **Certificate**

### FREE for Personal Usage

To be able to maintain this as a free service we're limiting usage as a tool that developers can use for personal
assistance and research by limiting usage to **60 requests /hour** which should be more than enough for most 
personal usage and research whilst deterring usage in automated tools.

:::tip info
Rate limiting is implemented with a sliding [Token Bucket algorithm](https://en.wikipedia.org/wiki/Token_bucket) that replenishes 1 additional request every 60s
:::


# gRPC SSL Configuration
Source: https://docs.servicestack.net/grpc/ssl

By default gRPC projects uses ASP.NET Core's trusted Development certificate (typically created on install), or can be configured with:

:::sh
dotnet dev-certs https --trust
:::

Many other languages requires this development certificate in order to establish a secure SSL connection, which can be exported with:

## Exporting your Development Certificate

Export your localhost self-signed .NET Core development certificate with:

:::sh
dotnet dev-certs https --export-path .
:::

If that fails see if you can diagnose and resolve the issue from the verbose output:

:::sh
dotnet dev-certs https --export-path . --verbose
:::

If you can't keep copy of the certificates **thumbprint**, then export it via Windows Certificate Manager:

:::sh
certmgr
:::

1. Go to `Personal > Certificates`
2. Select certificate **Issued To** `localhost`
    - If you have multiple certificates it's likely the one that expires the latest (double-check with thumbprint above to make sure)
3. Click on `Action > All Tasks > Export`
4. In the Export Wizard select **No, do not export the private key**
5. Select 2nd option **Base-64 encoded X.509 (.CER)**
6. Save to `localhost.cer`

### Generating a new Development Certificate

Should you prefer, you can create and use your own self-signed certificate using this OpenSSL script.

A quick way to download them is using the [mix tool](/mix-tool):

:::sh
x mix -name ProjectName gen.https.sh
:::

Otherwise you can create local text files and manually copy them with the contents below:

#### [gen-dev.https.sh](https://github.com/NetCoreTemplates/grpc/blob/master/scripts/gen-dev.https.sh)

```shell
PASSWORD=grpc
if [ $# -ge 1 ]
  then
    PASSWORD=$1
fi

cat <<EOT >>dev.config
[ req ]
default_bits       = 2048
default_md         = sha256
default_keyfile    = dev.key
prompt             = no
encrypt_key        = no

distinguished_name = dn
req_extensions     = v3_req
x509_extensions    = x509_req
string_mask        = utf8only

[ dn ]
commonName             = localhost dev cert
emailAddress           = test@localtest.me
countryName            = US
stateOrProvinceName    = DE
localityName           = Wilmington
organizationName       = Todo World

[ x509_req ]
subjectKeyIdentifier   = hash
authorityKeyIdentifier = keyid,issuer
basicConstraints       = critical, CA:false
keyUsage               = critical, keyEncipherment
subjectAltName         = @alt_names
# extendedKeyUsage  = serverAuth, clientAuth
nsComment              = "OpenSSL Generated Certificate"

[ v3_req ]
subjectKeyIdentifier   = hash
basicConstraints       = critical, CA:false
subjectAltName         = @alt_names
# extendedKeyUsage  = serverAuth, clientAuth
nsComment              = "OpenSSL Generated Certificate"

[ alt_names ]
DNS.1                  = localhost
EOT

openssl req -config dev.config -new -out dev.csr.pem
openssl x509 -req -days 365 -extfile dev.config -extensions v3_req -in dev.csr.pem -signkey dev.key -out dev.crt
openssl pkcs12 -export -out dev.pfx -inkey dev.key -in dev.crt -password pass:$PASSWORD
rm dev.config dev.csr.pem
# cp dev.pfx ../MyApp
```

Linux or WSL Bash:

:::sh
./gen-dev.https.sh
:::

Windows:

:::sh
bash gen-dev.https.sh
:::

Options:

:::sh
gen-dev.https.sh $PASSWORD
:::

### Trust Certificate on Windows

Import the pfx certificate:

```bash
powershell Import-PfxCertificate -FilePath dev.pfx Cert:\LocalMachine\My -Password (ConvertTo-SecureString grpc -asplaintext -force) -Exportable
```

Trust the certificate by importing the pfx certificate into your trusted root:

:::sh
powershell Import-Certificate -FilePath dev.crt -CertStoreLocation Cert:\CurrentUser\Root
:::

### Trust Certificate on Linux or macOS

See [Configuring HTTPS in ASP.NET Core across different platforms](https://devblogs.microsoft.com/aspnet/configuring-https-in-asp-net-core-across-different-platforms/) for examples of trusting SSL Certificates on different platforms.

Although recommended it's not necessary to trust self-signed certificates to enable secure gRPC SSL endpoints as servers and clients 
can be configured to use these OpenSSL generated self-signed certificates without out-of-band certificate registration.

## Generating a new Production Certificate

#### [gen-prod.https.sh](https://github.com/NetCoreTemplates/grpc/blob/master/scripts/gen-prod.https.sh)

```shell
DOMAIN=todoworld.servicestack.net
if [ $# -ge 1 ]
  then
    DOMAIN=$1
fi

PASSWORD=grpc
if [ $# -ge 2 ]
  then
    PASSWORD=$2
fi

cat <<EOT >>prod.config
[ req ]
default_bits       = 2048
default_md         = sha256
default_keyfile    = prod.key
prompt             = no
encrypt_key        = no
distinguished_name = dn
req_extensions     = v3_req
x509_extensions    = x509_req
string_mask        = utf8only
[ dn ]
commonName             = TodoWorld prod cert
emailAddress           = todoworld@servicestack.net
countryName            = US
stateOrProvinceName    = DE
localityName           = Wilmington
organizationName       = Todo World
[ x509_req ]
subjectKeyIdentifier   = hash
authorityKeyIdentifier = keyid,issuer
basicConstraints       = critical, CA:false
keyUsage               = critical, keyEncipherment
subjectAltName         = @alt_names
# extendedKeyUsage     = serverAuth, clientAuth
nsComment              = "OpenSSL Generated Certificate"
[ v3_req ]
subjectKeyIdentifier   = hash
basicConstraints       = critical, CA:false
subjectAltName         = @alt_names
# extendedKeyUsage     = serverAuth, clientAuth
nsComment              = "OpenSSL Generated Certificate"
[ alt_names ]
DNS.1                  = $DOMAIN
EOT

openssl req -config prod.config -new -out prod.csr.pem
openssl x509 -req -days 365 -extfile prod.config -extensions v3_req -in prod.csr.pem -signkey prod.key -out prod.crt
openssl pkcs12 -export -out prod.pfx -inkey prod.key -in prod.crt -password pass:$PASSWORD
rm prod.config prod.csr.pem
# cp prod.pfx ../MyApp
# cp prod.crt ../MyApp/wwwroot/grpc.crt
```

Either replace `DOMAIN=...` and `PASSWORD=...` with your domain and password or specify them as arguments, e.g:

Linux or WSL Bash:

:::sh
./gen-prod.https.sh $DOMAIN $PASSWORD
:::

Windows:

:::sh
bash gen-prod.https.sh $DOMAIN $PASSWORD
:::

### .NET Core Configuration

When configuring a custom SSL Certificate directly in a .NET Core App you'll need to configure the **GrpcSecure** endpoint 
with the combined [PKCS #12](https://en.wikipedia.org/wiki/PKCS_12) **.pfx** certificate, e.g:

```json
{
  "Kestrel": {
    "Endpoints": {
      "GrpcSecure": {
        "Url": "https://*:5051",
        "Protocols": "Http2",
        "Certificate": {
          "Path": "dev.pfx",
          "Password": "grpc"
        }
      }
    }
  }
}
```

### Nginx

When hosting public gRPC endpoints its HTTP/2 endpoints are generally incompatible with existing HTTP/1.1 gateways and proxies
that should effectively be treated as different channels and hosted on different ports.

Nginx added [native support for gRPC in v1.13.10](https://www.nginx.com/blog/nginx-1-13-10-grpc/) which works as well you'd expect
where you can proxy gRPC requests to downstream .NET Core gRPC SSL and plain-text endpoints, but it doesn't support proxying 
HTTP/2 requests on the same port as proxying standard HTTP/1.1 requests so you'll need to use a different port if you have
other standard HTTP websites you're proxying on the same server.

Below is the nginx configuration used in [https://todoworld.servicestack.net](https://todoworld.servicestack.net) which covers
the most popular gRPC hosting scenarios:

#### Plain text gRPC

```nginx
server {
    listen      50054 http2;
    server_name todoworld.servicestack.net;

    location / {
        grpc_pass grpc://127.0.0.1:5054;
    }
}
```

### SSL terminated gRPC endpoint

```nginx
server {
    listen      50051 http2 ssl;
    server_name todoworld.servicestack.net;

    location / {
        grpc_pass grpc://127.0.0.1:5054;
    }

    ssl_certificate /home/deploy/apps/certs/todoworld/prod.crt;
    ssl_certificate_key /home/deploy/apps/certs/todoworld/prod.key;
}
```

### Proxying Internal SSL gRPC Requests

```nginx
server {
    listen      50052 http2 ssl;
    server_name todoworld.servicestack.net;

    location / {
        grpc_pass grpcs://127.0.0.1:5051;
    }

    ssl_certificate /home/deploy/apps/certs/todoworld/prod.crt;
    ssl_certificate_key /home/deploy/apps/certs/todoworld/prod.key;
}
```

### Integration tests of different gRPC endpoints

You can quickly test each of these gRPC Endpoints by downloading the [C# Add ServiceStack Reference](/csharp-add-servicestack-reference) DTOs with:

:::sh
`x csharp https://todoworld.servicestack.net`
:::

Which can be used to test gRPC Services on each of the different gRPC endpoints below:

```csharp
public static GrpcServiceClient SecureProdClient(int port) => 
    new GrpcServiceClient($"https://todoworld.servicestack.net:{port}",
        new X509Certificate2("https://todoworld.servicestack.net/grpc.crt".GetBytesFromUrl()),
        GrpcUtils.AllowSelfSignedCertificatesFrom("todoworld.servicestack.net"));

public static GrpcServiceClient InsecureProdClient(int port)
{
    GrpcClientFactory.AllowUnencryptedHttp2 = true;
    return new GrpcServiceClient($"http://todoworld.servicestack.net:{port}");
}

// SSL Nginx -> plain-text .NET Core
var client = SecureProdClient(50051);

// SSL Nginx -> SSL .NET Core
var client = SecureProdClient(50052);

// Text Nginx -> Text .NET Core
var client = InsecureProdClient(50054);
```

You can also test directly against the gRPC endpoints on the .NET Core server:

```csharp
// SSL .NET Core
var client = SecureProdClient(5051);

// Text .NET Core
var client = InsecureProdClient(5054);
```

### Troubleshooting

If you're experiencing network connection issues trying to connect with your own gRPC hosted service, make sure you've opened
access to each of the non-standard ports used. Example using Ubuntu's UFW firewall:

:::sh
ufw allow 50051
:::

### Lets Encrypt

[Let's Encrypt](https://letsencrypt.org) has the nice property that it provides free, automated certificates from an open CA that's trusted
in most operating systems and browsers and whilst it's possible to use Lets Encrypt for public gRPC endpoints although it's generally discouraged
and not recommended for usage in internal applications, from [Jacob Hoffman-Andrews](https://twitter.com/j4cob) of Let's Encrypt:

> In general, I recommend that people don’t use Let’s Encrypt certificates for gRPC or other internal RPC services. In my opinion, it’s both easier and safer to generate a single-purpose internal CA using something like minica and generate both server and client certificates with it. That way you don’t have to open up your RPC servers to the outside internet, plus you limit the scope of trust to just what’s needed for your internal RPCs, plus you can have a much longer certificate lifetime, plus you can get revocation that works.

Whilst it's not recommended to use Let's Encrypts short-lived certificates for securing gRPC endpoints, the easiest way to use them is to 
have them SSL terminated at your reverse proxy fronting your .NET Core App and have it proxy gRPC Requests to an internal plain-text gRPC endpoint,
nginx example:

```nginx
server {
    listen      50051 http2 ssl;
    server_name $DOMAIN;

    location / {
        grpc_pass grpc://127.0.0.1:5054;
    }

    ssl_certificate /etc/letsencrypt/live/$DOMAIN/fullchain.pem;   # managed by Certbot
    ssl_certificate_key /etc/letsencrypt/live/$DOMAIN/privkey.pem; # managed by Certbot
}
```

They could also be used to secure the gRPC endpoint on your .NET Core App as well but that would require coordinating the re-creation of a **.pfx** certificate after Lets Encrypt certificates are renewed.


# Smart Generic C# / F# / VB.NET Service Client
Source: https://docs.servicestack.net/grpc/generic

## C# Generic GrpcServiceClient TodoWorld Example

[![](/img/pages/grpc/csharp-generic.png)](https://youtu.be/K0QAUQPJNtM)

::: info YouTube
[youtu.be/K0QAUQPJNtM](https://youtu.be/K0QAUQPJNtM)
:::

Install [x dotnet tool](/web-tool):
    
:::sh
dotnet tool install --global x 
:::

Create a new C# App:

:::sh
dotnet new console
:::

Add [ServiceStack.GrpcClient](https://www.nuget.org/packages/ServiceStack.GrpcClient) NuGet Package:

:::sh
dotnet add package ServiceStack.GrpcClient
:::

Add TodoWorld DTOs:

:::sh
`x csharp https://todoworld.servicestack.net`
:::
    
Use TodoWorld DTOs with generic `GrpcServiceClient` to call TodoWorld gRPC Service:

### C# gRPC insecure Example

```csharp
using System;
using System.Threading.Tasks;
using ServiceStack;
using TodoWorld.ServiceModel;

namespace TodoWorld
{
    class Program
    {
        public static async Task Main(string[] args)
        {
            ProtoBuf.Grpc.Client.GrpcClientFactory.AllowUnencryptedHttp2 = true;
            var client = new GrpcServiceClient("http://todoworld.servicestack.net:5054");

            var response = await client.GetAsync(new Hello { Name = "gRPC C#" });

            Console.WriteLine(response.Result);
        }
    }
}
```

Override `Program.cs` with the above C# Example: 

:::sh
x mix todoworld-cs
:::

Run example:

:::sh
dotnet run
:::

### C# gRPC SSL Example

```csharp
using System;
using System.Threading.Tasks;
using System.Security.Cryptography.X509Certificates;
using ServiceStack;
using TodoWorld.ServiceModel;

namespace TodoWorld
{
    class Program
    {
        public static async Task Main(string[] args)
        {
            var client = new GrpcServiceClient("https://todoworld.servicestack.net:50051", 
                new X509Certificate2("https://todoworld.servicestack.net/grpc.crt".GetBytesFromUrl()), 
                GrpcUtils.AllowSelfSignedCertificatesFrom("todoworld.servicestack.net"));

            var response = await client.GetAsync(new Hello { Name = "gRPC C#" });

            Console.WriteLine(response.Result);
        }
    }
}
```

Override `Program.cs` with the above C# Example: 

:::sh
x mix todoworld-cs-ssl
:::

Run example:

:::sh
dotnet run
:::

### C# Local Development gRPC SSL CRUD Example

```csharp
using System.Threading.Tasks;
using ServiceStack;
using ServiceStack.Text;
using TodoWorld.ServiceModel;

namespace CSharpGeneric
{
    public class Program
    {
        public static async Task Main(string[] args)
        {
            // Certificate registration not required when using trusted local development certificate  
            var client = new GrpcServiceClient("https://localhost:5001");
            await client.PostAsync(new ResetTodos());

            //POST /todos
            var todo = (await client.PostAsync(new CreateTodo { Title = "ServiceStack" })).Result;
            $"new todo Id: {todo.Id}, Title: {todo.Title}".Print();
            
            //GET /todos
            var all = await client.GetAsync(new GetTodos());
            $"todos: {all.Results?.Count ?? 0}".Print();

            //GET /todos/1
            todo = (await client.GetAsync(new GetTodo { Id = todo.Id })).Result;
            $"get todo Id: {todo.Id}, Title: {todo.Title}".Print();

            //GET /todos
            all = await client.GetAsync(new GetTodos());
            $"todos: {all.Results?.Count ?? 0}".Print();

            //PUT /todos/1
            await client.PutAsync(new UpdateTodo { Id = todo.Id, Title = "gRPC" });

            //GET /todos/1
            todo = (await client.GetAsync(new GetTodo { Id = todo.Id })).Result;
            $"updated todo Title: {todo.Title}".Print();

            //DELETE /todos/1
            await client.DeleteAsync(new DeleteTodo { Id = todo.Id });

            //GET /todos
            all = await client.GetAsync(new GetTodos());
            $"todos: {all.Results?.Count ?? 0}".Print();
        }
    }
}
```

Refer to [/clients/csharp-generic](https://github.com/NetCoreApps/todo-world/tree/master/clients/csharp-generic)
for a complete example project.

## More Examples

For more C# `GrpcServiceClient` examples check out the integration tests at:

 - [GrpcTests.cs](https://github.com/ServiceStack/ServiceStack/blob/master/tests/ServiceStack.Extensions.Tests/GrpcTests.cs)
 - [GrpcTodoTests.cs](https://github.com/ServiceStack/ServiceStack/blob/master/tests/ServiceStack.Extensions.Tests/GrpcTodoTests.cs)
 - [GrpcAuthTests.cs](https://github.com/ServiceStack/ServiceStack/blob/master/tests/ServiceStack.Extensions.Tests/GrpcAuthTests.cs)
 - [GrpcAutoQueryTests.cs](https://github.com/ServiceStack/ServiceStack/blob/master/tests/ServiceStack.Extensions.Tests/GrpcAutoQueryTests.cs)
 - [GrpcServerEventsTests.cs](https://github.com/ServiceStack/ServiceStack/blob/master/tests/ServiceStack.Extensions.Tests/GrpcServerEventsTests.cs)

## VB.NET Generic GrpcServiceClient TodoWorld Example

[![](/img/pages/grpc/vb-generic.png)](https://youtu.be/9XTy3eOdpHw)

::: info YouTube
[youtu.be/9XTy3eOdpHw](https://youtu.be/9XTy3eOdpHw)
:::

Install [x dotnet tool](/dotnet-tool):
    
:::sh
dotnet tool install --global x 
:::

Create a new VB.NET App:

:::sh
dotnet new console -lang vb
:::

Add [ServiceStack.GrpcClient](https://www.nuget.org/packages/ServiceStack.GrpcClient) NuGet Package:

:::sh
dotnet add package ServiceStack.GrpcClient
:::

Add TodoWorld DTOs:

:::sh
x vb https://todoworld.servicestack.net
:::
    
Use TodoWorld DTOs with generic `GrpcServiceClient` to call TodoWorld gRPC Service:

### VB.NET gRPC insecure Example

```vb
Imports System
Imports System.Collections.Generic
Imports System.Threading.Tasks
Imports ServiceStack
Imports TodoWorld.ServiceModel

Module Program

    Async Function Todo() As Task
        ProtoBuf.Grpc.Client.GrpcClientFactory.AllowUnencryptedHttp2 = true
        Dim client = new GrpcServiceClient("http://todoworld.servicestack.net:5054")
        
        Dim response = Await client.GetAsync(New Hello With { .Name = "gRPC VB.NET" })

        Console.WriteLine(response.Result)
    End Function

    Sub Main(args As String())
        Task.WaitAll(Todo())
    End Sub

End Module
```

Override `Program.vb` with the above VB.NET Example: 

:::sh
x mix todoworld-vb
:::

Run example:

:::sh
dotnet run
:::

### VB.NET gRPC SSL Example

```vb
Imports System
Imports System.Collections.Generic
Imports System.Threading.Tasks
Imports System.Security.Cryptography.X509Certificates
Imports ServiceStack
Imports TodoWorld.ServiceModel

Module Program

    Async Function Todo() As Task
        Dim client = new GrpcServiceClient("https://todoworld.servicestack.net:50051", 
                new X509Certificate2("https://todoworld.servicestack.net/grpc.crt".GetBytesFromUrl()), 
                GrpcUtils.AllowSelfSignedCertificatesFrom("todoworld.servicestack.net"))
        
        Dim response = Await client.GetAsync(New Hello With { .Name = "gRPC VB.NET" })

        Console.WriteLine(response.Result)
    End Function

    Sub Main(args As String())
        Task.WaitAll(Todo())
    End Sub

End Module
```

Override `Program.vb` with the above VB.NET Example: 

:::sh
x mix todoworld-vb-ssl
:::

Run example:

:::sh
dotnet run
:::

### VB.NET Local Development gRPC SSL CRUD Example

```vb
Imports System
Imports System.Collections.Generic
Imports System.Threading.Tasks
Imports ServiceStack
Imports TodoWorld.ServiceModel
Imports TodoWorld.ServiceModel.Types

Module Program
    Function SeqCount(c As List(Of Todo)) As Integer
        Return IF(c Is Nothing, 0, c.Count)
    End Function
    
    Async Function TodoExample() As Task
        ' Certificate registration not required when using trusted local development certificate  
        Dim client = new GrpcServiceClient("https://localhost:5001")
        Await client.PostAsync(New ResetTodos())

        'GET /todos
        Dim all = Await client.GetAsync(New GetTodos())
        Console.WriteLine($"todos: {SeqCount(all.Results)}")

        'POST /todos
        Dim todo As Todo = (Await client.PostAsync(New CreateTodo With { .Title = "ServiceStack" })).Result
        Console.WriteLine($"new todo Id: {todo.Id}, Title: {todo.Title}")
            
        'GET /todos/1
        todo = (Await client.GetAsync(New GetTodo With { .Id = todo.Id })).Result
        Console.WriteLine($"get todo Id: {todo.Id}, Title: {todo.Title}")

        'GET /todos
        all = await client.GetAsync(new GetTodos())
        Console.WriteLine($"todos: {SeqCount(all.Results)}")

        'PUT /todos/1
        Await client.PutAsync(New UpdateTodo With { .Id = todo.Id, .Title = "gRPC" })

        'GET /todos/1
        todo = (Await client.GetAsync(New GetTodo With { .Id = todo.Id })).Result
        Console.WriteLine("updated todo Title: {todo.Title}")

        'DELETE /todos/1
        Await client.DeleteAsync(new DeleteTodo With { .Id = todo.Id })

        'GET /todos
        all = Await client.GetAsync(new GetTodos())
        Console.WriteLine($"todos: {SeqCount(all.Results)}")
        
    End Function
    
    Sub Main(args As String())
        Task.WaitAll(TodoExample())
    End Sub
    
End Module
```

Refer to [/clients/vb-generic](https://github.com/NetCoreApps/todo-world/tree/master/clients/vb-generic)
for a complete example project.


## F# Generic GrpcServiceClient TodoWorld Example

[![](/img/pages/grpc/fsharp-generic.png)](https://youtu.be/y3MBaapcN-0)

::: info YouTube
[youtu.be/y3MBaapcN-0](https://youtu.be/y3MBaapcN-0)
:::

Install [x dotnet tool](/dotnet-tool):
    
:::sh
dotnet tool install --global x
:::

Create a new F# App:

:::sh
dotnet new console -lang f#
:::

Add [ServiceStack.GrpcClient](https://www.nuget.org/packages/ServiceStack.GrpcClient) NuGet Package:

:::sh
dotnet add package ServiceStack.GrpcClient
:::

Add [TaskBuilder.fs](https://www.nuget.org/packages/TaskBuilder.fs) NuGet Package

:::sh
dotnet add package TaskBuilder.fs
:::

Add TodoWorld DTOs:

:::sh
x fsharp https://todoworld.servicestack.net
:::

Register `dto.fs` source file to `*.fsproj`:

```xml
<ItemGroup>
    <Compile Include="dtos.fs"/>
    <Compile Include="Program.fs"/>
</ItemGroup>
```
    
Use TodoWorld DTOs with generic `GrpcServiceClient` to call TodoWorld gRPC Service:

### F# gRPC insecure Example

```fsharp
open System
open System.Threading
open System.Threading.Tasks
open ServiceStack
open TodoWorld.ServiceModel
open FSharp.Control.Tasks.V2

let todo () = 
    task {
        ProtoBuf.Grpc.Client.GrpcClientFactory.AllowUnencryptedHttp2 = true
        let client = new GrpcServiceClient("http://todoworld.servicestack.net:5054")
        
        let! response = client.GetAsync(new Hello(Name = "gRPC F#"))
        printfn "%s" response.Result
    }

[<EntryPoint>]
let main argv =
    todo().Wait()
    0
```

Override `Program.fs` with the above F# Example: 

    $ x mix todoworld-fs

Run example:

    $ dotnet run

### F# gRPC SSL Example

```fsharp
open System
open System.Threading
open System.Threading.Tasks
open System.Security.Cryptography.X509Certificates
open ServiceStack
open TodoWorld.ServiceModel
open FSharp.Control.Tasks.V2

let todo () = 
    task {
        let client = new GrpcServiceClient("https://todoworld.servicestack.net:50051", 
                new X509Certificate2("https://todoworld.servicestack.net/grpc.crt".GetBytesFromUrl()), 
                GrpcUtils.AllowSelfSignedCertificatesFrom("todoworld.servicestack.net"))
        
        let! response = client.GetAsync(new Hello(Name = "gRPC F#"))
        printfn "%s" response.Result
    }

[<EntryPoint>]
let main argv =
    todo().Wait()
    0
```

Override `Program.fs` with the above F# Example:

:::sh
x mix todoworld-fs-ssl
:::

Run example:

:::sh
dotnet run
:::

### F# Local Development gRPC SSL CRUD Example

```fsharp
open System
open System.Collections.Generic
open System.Threading
open System.Threading.Tasks
open ServiceStack
open TodoWorld.ServiceModel
open FSharp.Control.Tasks.V2

let todo () = 
    let seqCount (c: List<Todo>) = if c <> null then c.Count else 0    
    task {
        // Certificate registration not required when using trusted local development certificate  
        let client = new GrpcServiceClient("https://localhost:5001")
        do! client.PostAsync(new ResetTodos())

        //POST /todos
        let! t = client.PostAsync(new CreateTodo(Title = "ServiceStack"))
        let todo = t.Result;
        printfn "new todo Id: %i, Title: %s" todo.Id todo.Title

        //GET /todos
        let! all = client.GetAsync(new GetTodos())
        printfn "todos: %i" (seqCount all.Results)
        
        //GET /todos/1
        let! t = client.GetAsync(new GetTodo(Id = todo.Id))
        let todo = t.Result;
        printfn "get todo Id: %i, Title: %s" todo.Id todo.Title

        //GET /todos
        let! all = client.GetAsync(new GetTodos())
        printfn "todos: %i" (seqCount all.Results)
        
        //PUT /todos/1
        do! client.PutAsync(new UpdateTodo(Id = todo.Id, Title = "gRPC"))

        //GET /todos/1
        let! t = client.GetAsync(new GetTodo(Id = todo.Id))
        let todo = t.Result;
        printfn "updated todo Title: %s" todo.Title

        //DELETE /todos/1
        do! client.DeleteAsync(new DeleteTodo(Id = todo.Id))

        //GET /todos
        let! all = client.GetAsync(new GetTodos())
        printfn "todos: %i" (seqCount all.Results)
    }

[<EntryPoint>]
let main argv =
    todo().Wait()
    0
```

Refer to [/clients/fsharp-generic](https://github.com/NetCoreApps/todo-world/tree/master/clients/fsharp-generic)
for a complete example project.


# gRPC protoc Flutter Dart Client
Source: https://docs.servicestack.net/grpc/flutter

[![](https://raw.githubusercontent.com/NetCoreApps/todo-world/master/TodoWorld/wwwroot/assets/img/flutter/flutter-grpc-ssl.png)](https://youtu.be/t83gDzEGpac)

<lite-youtube class="w-full mx-4 my-4" width="560" height="315" videoid="UQlYodNS1xc" style="background-image: url('https://img.youtube.com/vi/UQlYodNS1xc/maxresdefault.jpg')"></lite-youtube>

## Flutter protoc generated GrpcServiceClient Example

Install [x dotnet tool](/dotnet-tool):
    
:::sh
dotnet tool install --global x 
:::

Create a new Flutter project with [Android Studio](https://developer.android.com/studio):

![](https://raw.githubusercontent.com/NetCoreApps/todo-world/master/TodoWorld/wwwroot/assets/img/flutter/new-flutter-project.png)

Add protoc generated TodoWorld DTOs and gRPC GrpcServiceClient to `lib/` folder:

:::sh
x proto-dart https://todoworld.servicestack.net -out lib
:::

Add required dependencies to **pubspec.yaml**:

```yaml
dependencies:
  fixnum: ^0.10.11
  async: ^2.2.0
  protobuf: ^1.0.1
  grpc: ^2.1.3
```

Install dependencies by running `pub get` or clicking on **Get Dependencies** link in the IDE:

![](https://raw.githubusercontent.com/NetCoreApps/todo-world/master/TodoWorld/wwwroot/assets/img/flutter/pub-get.png)

### Flutter protoc gRPC insecure Example

Use protoc generated DTOs and `GrpcServiceClient` to call TodoWorld gRPC Service in `_MyHomePageState`
class in `bin/main.dart`:

```dart
import 'package:flutter/material.dart';
import 'package:flutter_grpc/services.pbgrpc.dart';
import 'package:grpc/grpc.dart';

//...

class _MyHomePageState extends State<MyHomePage> {
  String result = '';
  GrpcServicesClient client = GrpcServicesClient(
      ClientChannel('todoworld.servicestack.net', port:50054,
          options:ChannelOptions(credentials: ChannelCredentials.insecure())));

  void _callGrpcService() async {
    var response = await client.getHello(Hello()..name="Flutter gRPC");
    setState(() {
      result = response.result;
    });
  }

  //...
}
```

Capture the result gRPC API request in the `result` String then change the Widget `build()` to 
display that instead of `_counter` then update the `floatingActionButton` to call your `_callGrpcService`
method instead:

```dart
  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: Text(widget.title),
      ),
      body: Center(
        child: Column(
          mainAxisAlignment: MainAxisAlignment.center,
          children: <Widget>[
            Text(
              'gRPC Service Example:',
            ),
            Text(
              '$result',
              style: Theme.of(context).textTheme.display1,
            ),
          ],
        ),
      ),
      floatingActionButton: FloatingActionButton(
        onPressed: _callGrpcService,
        tooltip: 'gRPC Service Example',
        child: Icon(Icons.play_arrow),
      ),
    );
  }
```

With Flutter's live-reload capability you should be able to see your changes instantly in the Android emulator
where clicking the icon should display the result of your plain-text gRPC Service Request:

![](https://raw.githubusercontent.com/NetCoreApps/todo-world/master/TodoWorld/wwwroot/assets/img/flutter/flutter-grpc-insecure.png)

### Flutter protoc gRPC SSL Example

To use gRPC SSL we'll need a copy of our gRPC's Service SSL Certificate which we can make available to our
Flutter App by saving it to our App's `assets` directory:

```bash
mkdir assets
x get https://todoworld.servicestack.net/grpc.crt -out assets
```

As loading assets is an asynchronous operation we'll need to preload it either by loading it in `main()` and
passing it as an attribute down to all our components or we can load it in our State widget's `initState()`
method:

```dart
class _MyHomePageState extends State<MyHomePage> {
  String result = '';
  GrpcServicesClient client;

  @override
  void initState() {
    super.initState();
    DefaultAssetBundle.of(context).load("assets/grpc.crt").then((bytes) => setState(() {
      client = GrpcServicesClient(
          ClientChannel('todoworld.servicestack.net', port:50051,
              options:ChannelOptions(credentials: ChannelCredentials.secure(
                  certificates: bytes.buffer.asUint8List(),
                  authority: 'todoworld.servicestack.net'
              ))));
    }));
  }

  void _callGrpcService() async {
    var response = await client.getHello(Hello()..name="gRPC SSL");
    setState(() {
      result = response.result;
    });
  }

  //...
}
```

You'll also need to update the port to refer to the gRPC SSL endpoint, update your `Hello` request
so we can verify the result is from the new gRPC SSL request. Now after live-reload has completed,
clicking on the icon will show the response of a gRPC SSL Request:

![](https://raw.githubusercontent.com/NetCoreApps/todo-world/master/TodoWorld/wwwroot/assets/img/flutter/flutter-grpc-ssl.png)

Refer to [/mobile/flutter/flutter_grpc](https://github.com/NetCoreApps/todo-world/tree/master/mobile/flutter/flutter_grpc)
for a complete example project.


# gRPC protoc Android Java Client
Source: https://docs.servicestack.net/grpc/android

[![](https://raw.githubusercontent.com/NetCoreApps/todo-world/master/TodoWorld/wwwroot/assets/img/android/android-grpc-ssl.png)](https://youtu.be/nag0hr5THug)

<lite-youtube class="w-full mx-4 my-4" width="560" height="315" videoid="nag0hr5THug" style="background-image: url('https://img.youtube.com/vi/nag0hr5THug/maxresdefault.jpg')"></lite-youtube>

## Android Java-Lite protoc generated GrpcServiceClient Example

This Android gRPC Example differentiates from the [Java gRPC Example](#java) by using the more appropriate
[Java Lite](https://github.com/protocolbuffers/protobuf/blob/master/java/lite.md) which results in a 
much smaller code size making it more suitable to be used on embedded Java platforms like Android.

In addition it uses the Android-compatible OK HTTP SSL Libraries in-place of Netty's SSL libraries and a 
custom `services.proto` allow us to specify the Java **package** we want the generated gRPC client to use.

Install [x dotnet tool](/dotnet-tool):
    
:::sh
dotnet tool install --global x 
:::

Create a new Android App with [Android Studio](https://developer.android.com/studio):

![](https://raw.githubusercontent.com/NetCoreApps/todo-world/master/TodoWorld/wwwroot/assets/img/android/new-android-project.png)
Add protoc generated TodoWorld DTOs and gRPC `GrpcServicesStub`:

```bash
cd app\src\main\java
x proto-java https://todoworld.servicestack.net
```

Modify the downloaded `services.proto` to use the **package** name of your App, e.g:

```protobuf
option java_package = "net.servicestack.androidapp";
```

Generate a **java-lite** protoc gRPC client from your modified `services.proto`:

:::sh
x proto-java-lite services.proto
:::

Update **build.gradle** with required gRPC, protobuf and OK HTTP plugins and dependencies:

```groovy
plugins {
    id 'com.google.protobuf' version '0.8.8'
    id 'idea'
}

//...

def grpcVersion = '1.27.0'

dependencies {
    implementation 'javax.annotation:javax.annotation-api:1.2'
    implementation "io.grpc:grpc-protobuf:${grpcVersion}"
    implementation "io.grpc:grpc-auth:${grpcVersion}"
    implementation "io.grpc:grpc-census:${grpcVersion}"
    implementation "io.grpc:grpc-okhttp:${grpcVersion}"
    implementation "io.grpc:grpc-stub:${grpcVersion}"

//...
}
```

Sync changes to your **build.gradle** to install the new dependencies: 

![](https://raw.githubusercontent.com/NetCoreApps/todo-world/master/TodoWorld/wwwroot/assets/img/android/gradle-sync.png)

Add the `android.permission.INTERNET` to your **AndroidManifest.xml** (before `<application/>` tag):

```xml
<uses-permission android:name="android.permission.INTERNET"/>
```

Use protoc generated DTOs and async `GrpcServicesStub` to perform non-blocking TodoWorld gRPC Service requests:

### Android Java protoc gRPC insecure Example

```java
ManagedChannel channel = ManagedChannelBuilder.forAddress(
    "todoworld.servicestack.net", 50054).usePlaintext().build();

final GrpcServicesGrpc.GrpcServicesStub client =
    GrpcServicesGrpc.newStub(channel);

fab.setOnClickListener(new View.OnClickListener() {
    client.getHello(Services.Hello.newBuilder()
        .setName("Android gRPC").build(),
        new StreamObserver<Services.HelloResponse>() {
            @Override
            public void onNext(Services.HelloResponse value) {
                Snackbar.make(view, value.getResult(), Snackbar.LENGTH_LONG)
                        .setAction("Action", null).show();
            }
            @Override public void onError(Throwable t) {}
            @Override public void onCompleted() {}
        });
});
```

Now run your App and click the Action button to make a plain-text gRPC Request:

![](https://raw.githubusercontent.com/NetCoreApps/todo-world/master/TodoWorld/wwwroot/assets/img/android/android-grpc-insecure.png)

### Android Java protoc gRPC SSL Example

To use gRPC SSL we'll need a copy of our gRPC's Service SSL Certificate which we can make available to our
Android App by saving it to our App's `assets` directory:

```bash
mkdir ..\assets
x get https://todoworld.servicestack.net/grpc.crt -out ../assets
```

Building an TLS Channel configured with a self-signed SSL Certificate requires a bit of effort with OK HTTP
so we'll include a [ChannelBuilder.java](https://gist.github.com/gistlyn/0a3311c1b72b136bdfae616507cc38af)
to wrap up the boiler plate:

:::sh
x mix grpc-android
:::

This simplifies the configuration required down to just the `grpc.crt` certificate loaded from the 
App's Asset Manager, the host and port name of the gRPC SSL Channel: 

```java
ManagedChannel channel = null;
InputStream is = null;
try {
    is = getResources().getAssets().open("grpc.crt");
    channel = ChannelBuilder.buildTls(
        "todoworld.servicestack.net", 50051, is);
    is.close();
} catch (Throwable e) {
    e.printStackTrace();
}
```

Lets update the gRPC API call to reflect we're now using an SSL channel:

```java
client.getHello(Services.Hello.newBuilder()
    .setName("gRPC SSL").build(),
```

Now after re-running our App it'll perform gRPC SSL Service requests instead:

![](https://raw.githubusercontent.com/NetCoreApps/todo-world/master/TodoWorld/wwwroot/assets/img/android/android-grpc-ssl.png)

Refer to [/mobile/java/AndroidGrpc](https://github.com/NetCoreApps/todo-world/tree/master/mobile/java/AndroidGrpc)
for a complete example project.


# gRPC protoc C# Client
Source: https://docs.servicestack.net/grpc/csharp

[![](/img/pages/grpc/csharp.png)](https://youtu.be/0TXk9y24NIw)

::: info YouTube
YouTube: [youtu.be/0TXk9y24NIw](https://youtu.be/0TXk9y24NIw)
:::

## C# protoc generated GrpcServiceClient TodoWorld Example

Install [x dotnet tool](/dotnet-tool):
    
:::sh
dotnet tool install --global x 
:::

Create a new C# Console App:

:::sh
dotnet new console
:::

Add required NuGet Packages:

:::sh
dotnet add package Google.Protobuf ServiceStack.GrpcClient
:::
    
Download TodoWorld SSL Certificate used for its gRPC HTTP/2 Services:

:::sh
$ x get https://todoworld.servicestack.net/grpc.crt 
:::

Add protoc generated TodoWorld DTOs and gRPC GrpcServiceClient:

:::sh
x proto-csharp https://todoworld.servicestack.net
:::
    
Use protoc generated DTOs and  `GrpcServiceClient` to call TodoWorld gRPC Service:

### C# smart gRPC GrpcServicesClient Example

The smart client registers a ServiceStack Interceptor to enable the richer integration features in ServiceStack
Services as found in ServiceStack's Generic `GrpcServiceClient` above, including detailed structured Exception handling,
built-in JWT, Session, Credentials Auth support, 
[Automatically refreshing Access Tokens](/auth/jwt-authprovider#automatically-refreshing-access-tokens), etc.

This ServiceStack Interceptor can be registered using `GrpcServiceStack.Client()`  when creating the protoc `GrpcServicesClient`:

```csharp
using System;
using System.Security.Cryptography.X509Certificates;
using System.Threading.Tasks;
using ServiceStack;

namespace TodoWorld
{
    class Program
    {
        static async Task Main(string[] args)
        {
            var client = new GrpcServices.GrpcServicesClient(
                GrpcServiceStack.Client("https://todoworld.servicestack.net:50051", 
                    new X509Certificate2("grpc.crt"),
                    GrpcUtils.AllowSelfSignedCertificatesFrom("todoworld.servicestack.net")));

            var response = await client.GetHelloAsync(new Hello { Name = "gRPC C#" });

            Console.WriteLine(response.Result);
        }
    }
}
```

Override `Program.cs` with the above C# Example: 

:::sh
x mix todoworld-csharp-smart
:::

Run example:

:::sh
dotnet run
:::

### protoc-only generated Service Client

Alternatively clients can opt to use the vanilla protoc generated ServiceClient without any dependency to 
**ServiceStack.GrpcClient** which will fallback to gRPC's default behavior of basic error handling with any
auth headers needing to be populated manually.

Add required core package dependencies:

:::sh
dotnet add package Grpc.Core Grpc.Net.Client
:::

### C# protoc gRPC insecure Example

```csharp
using System;
using System.Threading.Tasks;
using Grpc.Core;
using Grpc.Net.Client;

namespace TodoWorld
{
    class Program
    {
        static async Task Main(string[] args)
        {
            AppContext.SetSwitch("System.Net.Http.SocketsHttpHandler.Http2UnencryptedSupport", true);
            var client = new GrpcServices.GrpcServicesClient(
                GrpcChannel.ForAddress("http://todoworld.servicestack.net:5054"));

            var response = await client.GetHelloAsync(new Hello { Name = "gRPC C#" });

            Console.WriteLine(response.Result);
        }
    }
}
```

Override `Program.cs` with the above C# Example: 

:::sh
x mix todoworld-csharp
:::

Run example:

:::sh
dotnet run
:::

### C# protoc gRPC SSL Example

```csharp
using System;
using System.Linq;
using System.Net.Security;
using System.Security.Cryptography.X509Certificates;
using System.Threading.Tasks;
using Grpc.Core;
using Grpc.Net.Client;

namespace TodoWorld
{
    class Program
    {
        static async Task Main(string[] args)
        {
            var client = new GrpcServices.GrpcServicesClient(
                GrpcChannel.ForAddress("https://todoworld.servicestack.net:50051", new GrpcChannelOptions {
                    HttpClient = new System.Net.Http.HttpClient(new System.Net.Http.HttpClientHandler {
                        ClientCertificates = { new X509Certificate2("grpc.crt") },
                        ServerCertificateCustomValidationCallback = (req, cert, certChain, sslErrors) =>
                            cert.SubjectName.RawData.SequenceEqual(cert.IssuerName.RawData) && // self-signed
                            cert.GetNameInfo(X509NameType.DnsName, forIssuer:false) == "todoworld.servicestack.net" &&
                            (sslErrors & ~sslErrors.RemoteCertificateChainErrors) == sslErrors.None // only this
                    })
                }));

            var response = await client.GetHelloAsync(new Hello { Name = "gRPC C#" });

            Console.WriteLine(response.Result);
        }
    }
}
```

Override `Program.cs` with the above C# Example: 

:::sh
x mix todoworld-csharp-ssl
:::

Run example:

:::sh
dotnet run
:::

### C# Local Development gRPC SSL CRUD Example

```csharp
using System;
using System.Threading.Tasks;
using Grpc.Net.Client;
using TodoWorld;

namespace CSharp
{
    public class Program
    {
        static async Task Main(string[] args)
        {
            // Certificate registration not required when using trusted local development certificate  
            var client = new GrpcServices.GrpcServicesClient(GrpcChannel.ForAddress("https://localhost:5001"));
            await client.PostResetTodosAsync(new ResetTodos());

            //POST /todos
            var todo = (await client.PostCreateTodoAsync(new CreateTodo { Title = "ServiceStack" })).Result;
            Console.WriteLine($"new todo Id: {todo.Id}, Title: {todo.Title}");
            
            //GET /todos
            var all = await client.CallGetTodosAsync(new GetTodos());
            Console.WriteLine($"todos: {all.Results?.Count ?? 0}");

            //GET /todos/1
            todo = (await client.CallGetTodoAsync(new GetTodo { Id = todo.Id })).Result;
            Console.WriteLine($"get todo Id: {todo.Id}, Title: {todo.Title}");

            //GET /todos
            all = await client.CallGetTodosAsync(new GetTodos());
            Console.WriteLine($"todos: {all.Results?.Count ?? 0}");

            //PUT /todos/1
            await client.PutUpdateTodoAsync(new UpdateTodo { Id = todo.Id, Title = "gRPC" });

            //GET /todos/1
            todo = (await client.CallGetTodoAsync(new GetTodo { Id = todo.Id })).Result;
            Console.WriteLine($"updated todo Title: {todo.Title}");

            //DELETE /todos/1
            await client.CallDeleteTodoAsync(new DeleteTodo { Id = todo.Id });

            //GET /todos
            all = await client.CallGetTodosAsync(new GetTodos());
            Console.WriteLine($"todos: {all.Results?.Count ?? 0}");
        }
    }
}
```

Refer to [/clients/csharp](https://github.com/NetCoreApps/todo-world/tree/master/clients/csharp)
for a complete example project.

### More Examples

For more protoc generated `GrpcServices.GrpcServiceClient` examples check out the unit tests at:

 - [ProtocTests.cs](https://github.com/ServiceStack/ServiceStack/blob/master/tests/ServiceStack.Extensions.Tests/Protoc/ProtocTests.cs)
 - [ProtocTodoTests.cs](https://github.com/ServiceStack/ServiceStack/blob/master/tests/ServiceStack.Extensions.Tests/Protoc/ProtocTodoTests.cs)
 - [ProtocAuthTests.cs](https://github.com/ServiceStack/ServiceStack/blob/master/tests/ServiceStack.Extensions.Tests/Protoc/ProtocAuthTests.cs)
 - [ProtocServerEventsTests.cs](https://github.com/ServiceStack/ServiceStack/blob/master/tests/ServiceStack.Extensions.Tests/Protoc/ProtocServerEventsTests.cs)
 - [ProtocDynamicAutoQueryTests.cs](https://github.com/ServiceStack/ServiceStack/blob/master/tests/ServiceStack.Extensions.Tests/Protoc/ProtocDynamicAutoQueryTests.cs)


# gRPC protoc Swift Client
Source: https://docs.servicestack.net/grpc/swift

[![](/img/pages/grpc/swift.png)](https://youtu.be/FLHbN_Z9z98)

::: info YouTube
[youtu.be/FLHbN_Z9z98](https://youtu.be/FLHbN_Z9z98)
:::

## Swift protoc generated GrpcServiceClient TodoWorld Example

Install [x dotnet tool](/dotnet-tool):
    
:::sh
dotnet tool install --global x 
:::

Create a new Swift Console App:

:::sh
swift package init --type executable
:::

Add `grpc-swift` Swift Package in `Package.swift` and **"GRPC"** dependency to each target:

```swift
import PackageDescription

let package = Package(
    name: "TodoWorld",
    dependencies: [
        // Dependencies declare other packages that this package depends on.
        // .package(url: /* package url */, from: "1.0.0"),
        .package(url: "https://github.com/grpc/grpc-swift.git", from: "1.0.0-alpha.8")
    ],
    targets: [
        // Targets are the basic building blocks of a package. A target can define a module or a test suite.
        // Targets can depend on other targets in this package, and on products in packages which this package depends on.
        .target(
            name: "TodoWorld",
            dependencies: ["GRPC"]),
        .testTarget(
            name: "TodoWorldTests",
            dependencies: ["TodoWorld","GRPC"]),
    ]
)
```
    
Add protoc generated TodoWorld DTOs and gRPC GrpcServiceClient:

```bash
cd Sources/TodoWorld
x proto-swift https://todoworld.servicestack.net
```
    
Use protoc generated DTOs and `GrpcServiceClient` to call TodoWorld gRPC Service:

### Swift protoc gRPC insecure Example

```swift
import Foundation
import GRPC
import NIO
import NIOSSL

do {

    let configuration = ClientConnection.Configuration(
        target: .hostAndPort("todoworld.servicestack.net", 5054),
        eventLoopGroup: MultiThreadedEventLoopGroup(numberOfThreads: 1)
    )

    let client = GrpcServicesServiceClient(connection: ClientConnection(configuration: configuration))

    var request = Hello()
    request.name = "gRPC Swift"
    let response = try client.getHello(request).response.wait().result
    print(response)

} catch {
    print("ERROR\n\(error)")
}
```

Override `main.swift` with the above Swift Example: 

:::sh
x mix todoworld-swift
:::

Run example:

:::sh
swift run
:::

### Swift protoc gRPC SSL Example

Download TodoWorld SSL Certificate used for its gRPC HTTP/2 Services:

:::sh
x get https://todoworld.servicestack.net/grpc.crt 
:::

Use certificate when initializing ClientConnection.Configuration:

```swift
import Foundation
import GRPC
import NIO
import NIOSSL

do {

    let configuration = ClientConnection.Configuration(
        target: .hostAndPort("todoworld.servicestack.net", 50051),
        eventLoopGroup: MultiThreadedEventLoopGroup(numberOfThreads: 1),
        tls: .init(certificateChain: try NIOSSLCertificate.fromPEMFile("grpc.crt").map { .certificate($0) }, 
                   certificateVerification: .none) //TODO enable SSL verification
    )

    let client = GrpcServicesServiceClient(connection: ClientConnection(configuration: configuration))

    var request = Hello()
    request.name = "gRPC Swift"
    let response = try client.getHello(request).response.wait().result
    print(response)

} catch {
    print("ERROR\n\(error)")
}
```

Override `main.swift` with the above Swift Example: 

:::sh
x mix todoworld-swift-ssl
:::

Run example:

:::sh
swift run
:::

### Swift Local Development gRPC SSL CRUD Example

```swift
import Foundation
import GRPC
import NIO
import NIOSSL

do {

    let configuration = ClientConnection.Configuration(
        target: .hostAndPort("localhost", 5001),
        eventLoopGroup: MultiThreadedEventLoopGroup(numberOfThreads: 1),
        tls: .init(certificateChain: try NIOSSLCertificate.fromPEMFile("dev.crt").map { .certificate($0) })
    )

    let client = GrpcServicesServiceClient(connection: ClientConnection(configuration: configuration))

    print("TODO EXAMPLE")

    _ = try client.postResetTodos(ResetTodos()).response.wait()

    //POST /todos
    var createTodo = CreateTodo()
    createTodo.title = "ServiceStack"
    var todo = try client.postCreateTodo(createTodo).response.wait().result
    print("new todo Id: \(todo.id), Title: \(todo.title)")

    //GET /todos
    var all = try client.callGetTodos(GetTodos()).response.wait()
    print("todos: \(all.results.count)")

    //GET /todos/1
    var getTodo = GetTodo()
    getTodo.id = todo.id
    todo = try client.callGetTodo(getTodo).response.wait().result
    print("get todo Id: \(todo.id), Title: \(todo.title)")

    //PUT /todos/1
    var updateTodo = UpdateTodo()
    updateTodo.id = todo.id
    updateTodo.title = "gRPC"
    _ = try client.putUpdateTodo(updateTodo).response.wait()

    //GET /todos/1
    todo = try client.callGetTodo(getTodo).response.wait().result
    print("get todo Id: \(todo.id), Title: \(todo.title)")

    //DELETE /todos/1
    var deleteTodo = DeleteTodo()
    deleteTodo.id = todo.id
    _ = try client.callDeleteTodo(deleteTodo).response.wait()

    //GET /todos
    all = try client.callGetTodos(GetTodos()).response.wait()
    print("todos: \(all.results.count)")

} catch {
    print("ERROR\n\(error)")
}
```

Refer to [/clients/swift](https://github.com/NetCoreApps/todo-world/tree/master/clients/swift)
for a complete example project.


# gRPC protoc Java Client
Source: https://docs.servicestack.net/grpc/java

[![](/img/pages/grpc/java.png)](https://youtu.be/pe7oKApToDA)

::: info YouTube
[youtu.be/pe7oKApToDA](https://youtu.be/pe7oKApToDA)
:::

## Java protoc generated GrpcServiceClient TodoWorld Example

Install [x dotnet tool](/dotnet-tool):

```bash
$ dotnet tool install --global x 
```

Create a new **Gradle** Java Console App (example uses [IntelliJ IDEA Community](https://www.jetbrains.com/idea/download/)):

![](https://raw.githubusercontent.com/NetCoreApps/todo-world/master/TodoWorld/wwwroot/assets/img/java/create-01.png)

Update **build.gradle** with required dependencies:

```groovy
plugins {
    id 'java'
    id 'com.google.protobuf' version '0.8.8'
    id 'idea'
}

group 'org.example'
version '1.0-SNAPSHOT'

sourceCompatibility = 1.8

repositories {
    mavenCentral()
}

def grpcVersion = '1.25.0'
def nettyTcNativeVersion = '2.0.26.Final'
def protobufVersion = '3.11.0'

dependencies {
    implementation "io.grpc:grpc-netty:${grpcVersion}"
    implementation "io.grpc:grpc-protobuf:${grpcVersion}"
    implementation "io.grpc:grpc-stub:${grpcVersion}"
    compileOnly "javax.annotation:javax.annotation-api:1.2"

    implementation "com.google.protobuf:protobuf-java-util:${protobufVersion}"

    runtimeOnly "io.netty:netty-tcnative-boringssl-static:${nettyTcNativeVersion}"

    testImplementation "io.grpc:grpc-testing:${grpcVersion}"
    testImplementation "junit:junit:4.12"
    testImplementation "org.mockito:mockito-core:2.28.2"
}

dependencies {
    testCompile group: 'junit', name: 'junit', version: '4.12'
}
```

Add protoc generated TodoWorld DTOs and gRPC GrpcServicesBlockingStub:

```bash
$ cd src\main\java
$ x proto-java https://todoworld.servicestack.net
```
    
Use protoc generated DTOs and `GrpcServiceClient` to call TodoWorld gRPC Service:

### Java protoc gRPC insecure Example

```java
import io.grpc.ManagedChannel;
import io.grpc.ManagedChannelBuilder;

public class Program {
    public static void main(String[] args) {
        ManagedChannel channel = ManagedChannelBuilder.forAddress(
                "todoworld.servicestack.net", 5054).usePlaintext().build();

        GrpcServicesGrpc.GrpcServicesBlockingStub client = GrpcServicesGrpc.newBlockingStub(channel);

        Services.Hello request = Services.Hello.newBuilder().setName("gRPC Java").build();
        String result = client.getHello(request).getResult();

        System.out.println(result);
    }
}
```

Create `Program.java` from the above Java Example: 

```bash
$ x mix todoworld-java
```

Run example with `Shift+F10`:

![](https://raw.githubusercontent.com/NetCoreApps/todo-world/master/TodoWorld/wwwroot/assets/img/java/run-insecure.png)

### Java protoc gRPC SSL Example

Download TodoWorld SSL Certificate used for its gRPC HTTP/2 Services into **resources** folder:

```bash
$ x get https://todoworld.servicestack.net/grpc.crt -out ../resources 
```

Use certificate when initializing gRPC Channel:

```java
import io.grpc.ManagedChannel;
import io.grpc.netty.GrpcSslContexts;
import io.grpc.netty.NettyChannelBuilder;
import java.io.File;

public class Program {
    public static void main(String[] args) throws javax.net.ssl.SSLException {
        ManagedChannel channel = NettyChannelBuilder.forAddress("todoworld.servicestack.net", 50051)
            .sslContext(GrpcSslContexts.forClient()
                .trustManager(new File(Program.class.getClassLoader().getResource("grpc.crt").getFile()))
                .build())
            .build();

        GrpcServicesGrpc.GrpcServicesBlockingStub client = GrpcServicesGrpc.newBlockingStub(channel);

        Services.Hello request = Services.Hello.newBuilder().setName("gRPC Java").build();
        String result = client.getHello(request).getResult();

        System.out.println(result);
    }
}
```

Override `Program.java` with the above Java Example: 

```bash
$ x mix todoworld-java-ssl
```

Run example with `Shift+F10`:

![](https://raw.githubusercontent.com/NetCoreApps/todo-world/master/TodoWorld/wwwroot/assets/img/java/run-ssl.png)

### Java Local Development gRPC SSL CRUD Example

```java
import io.grpc.ManagedChannel;
import io.grpc.ManagedChannelBuilder;
import io.grpc.netty.GrpcSslContexts;
import io.grpc.netty.NettyChannelBuilder;
import io.netty.handler.ssl.util.InsecureTrustManagerFactory;

import javax.net.ssl.SSLException;

import static java.lang.System.out;

class Program {
    public static void main(String[] args) throws SSLException {

        ManagedChannel channel = NettyChannelBuilder.forAddress("localhost", 5001)
                .sslContext(GrpcSslContexts.forClient()
                .trustManager(InsecureTrustManagerFactory.INSTANCE) // allow localhost self-signed certificates
                .build())
            .build();

        GrpcServicesGrpc.GrpcServicesBlockingStub client = GrpcServicesGrpc.newBlockingStub(channel);

        out.println("TODO EXAMPLE");
        client.postResetTodos(Services.ResetTodos.newBuilder().build());

        //POST /todos
        Services.Todo todo = client.postCreateTodo(Services.CreateTodo.newBuilder().setTitle("ServiceStack").build()).getResult();
        out.println("new todo Id: " + todo.getId() + ", Title: " + todo.getTitle());

        //GET /todos
        Services.GetTodosResponse all = client.callGetTodos(Services.GetTodos.newBuilder().build());
        out.println("todos: " + all.getResultsCount());

        //GET /todos/1
        todo = (client.callGetTodo(Services.GetTodo.newBuilder().setId(todo.getId()).build())).getResult();
        out.println("get todo Id: " + todo.getId() + ", Title: " + todo.getTitle());

        //PUT /todos/1
        client.putUpdateTodo(Services.UpdateTodo.newBuilder().setId(todo.getId()).setTitle("gRPC").build());

        //GET /todos/1
        todo = (client.callGetTodo(Services.GetTodo.newBuilder().setId(todo.getId()).build())).getResult();
        out.println("get todo Id: " + todo.getId() + ", Title: " + todo.getTitle());

        //DELETE /todos/1
        client.callDeleteTodo(Services.DeleteTodo.newBuilder().setId(todo.getId()).build());

        //GET /todos
        all = client.callGetTodos(Services.GetTodos.newBuilder().build());
        out.println("todos: " + all.getResultsCount());
    }
}
```

Refer to [/clients/java](https://github.com/NetCoreApps/todo-world/tree/master/clients/java)
for a complete example project.


# gRPC protoc Dart Client
Source: https://docs.servicestack.net/grpc/dart

[![](/img/pages/grpc/dart.png)](https://youtu.be/fDARSMNlt50)

<lite-youtube class="w-full mx-4 my-4" width="560" height="315" videoid="UQlYodNS1xc" style="background-image: url('https://img.youtube.com/vi/UQlYodNS1xc/maxresdefault.jpg')"></lite-youtube>

## Dart protoc generated GrpcServiceClient TodoWorld Example

Install [x dotnet tool](/dotnet-tool):
    
:::sh
dotnet tool install --global x 
:::
    
Install [stagehand](https://pub.dev/packages/stagehand):

:::sh
pub global activate stagehand
:::

Create a new Dart Console App:

:::sh
stagehand console-full
:::

Add required dependencies to **pubspec.yaml**:

```yaml
dependencies:
  fixnum: ^0.10.11
  async: ^2.2.0
  protobuf: ^1.0.1
  grpc: ^2.1.3
```

Install dependencies:

:::sh
pub get
:::
    
### Generate protoc Dart gRPC Client

Add protoc generated TodoWorld DTOs and gRPC GrpcServiceClient to `lib/` folder:

:::sh
x proto-dart https://todoworld.servicestack.net -out lib
:::

### Dart protoc gRPC insecure Example

Use protoc generated DTOs and `GrpcServiceClient` to call TodoWorld gRPC Service in `bin/main.dart`:

```dart
import 'dart:io';
import 'package:grpc/grpc.dart';
import 'package:TodoWorld/services.pb.dart';
import 'package:TodoWorld/services.pbgrpc.dart';

void main(List<String> args) async {

  var client = GrpcServicesClient(ClientChannel('todoworld.servicestack.net', port:5054,
    options:ChannelOptions(credentials: ChannelCredentials.insecure())));

  var response = await client.getHello(Hello()..name = 'gRPC Dart');
  print(response.result);

  exit(0);
}
```

Override `bin/main.dart` with the above Dart Example: 

:::sh
x mix todoworld-dart -out bin
:::

Run example:

:::sh
dart run
:::

### Dart protoc gRPC SSL Example

Download TodoWorld SSL Certificate used for its gRPC HTTP/2 Services:

:::sh
x get https://todoworld.servicestack.net/grpc.crt
:::

Use certificate when initializing `GrpcServicesClient`:

```dart
import 'dart:io';
import 'package:grpc/grpc.dart';
import 'package:TodoWorld/services.pb.dart';
import 'package:TodoWorld/services.pbgrpc.dart';

void main(List<String> args) async {

  var client = GrpcServicesClient(ClientChannel('todoworld.servicestack.net', port:50051,
    options:ChannelOptions(credentials: ChannelCredentials.secure(
        certificates: File('grpc.crt').readAsBytesSync(),
        authority: 'todoworld.servicestack.net'))));

  var response = await client.getHello(Hello()..name = 'gRPC Dart');
  print(response.result);

  exit(0);
}
```

Override `bin/main.dart` with the above Dart Example: 

:::sh
x mix todoworld-dart-ssl -out bin
:::

Run example:

:::sh
dart run
:::

### Dart Local Development gRPC SSL CRUD Example

```dart
import 'dart:convert';
import 'dart:io';
import 'package:grpc/grpc.dart';
import 'package:todoworld/services.pb.dart';
import 'package:todoworld/services.pbgrpc.dart';

GrpcServicesClient createClient({CallOptions options}) {
  return GrpcServicesClient(ClientChannel('localhost', port:5001,
    options:ChannelOptions(credentials: ChannelCredentials.secure(
        certificates: File('../certs/dev.crt').readAsBytesSync(),
        authority: 'localhost'))), options:options);
}

void main(List<String> args) async {

  var client = createClient();
  await client.postResetTodos(ResetTodos());

  //POST /todos
  var todo = (await client.postCreateTodo(CreateTodo()..title = 'ServiceStack')).result;
  print('new todo Id: ${todo.id}, Title: ${todo.title}');

  //GET /todos
  var all = await client.callGetTodos(GetTodos());
  print('todos: ${all.results.length}');

  //GET /todos/1
  todo = (await client.callGetTodo(GetTodo()..id = todo.id)).result;
  print('get todo Id: ${todo.id}, Title: ${todo.title}');

  //PUT /todos/1
  await client.putUpdateTodo(UpdateTodo()..id = todo.id..title = 'gRPC');

  //GET /todos/1
  todo = (await client.callGetTodo(GetTodo()..id = todo.id)).result;
  print('get todo Id: ${todo.id}, Title: ${todo.title}');

  //DELETE /todos/1
  await client.callDeleteTodo(DeleteTodo()..id = todo.id);

  //GET /todos
  all = await client.callGetTodos(GetTodos());
  print('todos: ${all.results.length}');  
}
```

### Dart Server Events gRPC Server Stream Example

Consume [ServiceStack Server Events](/server-events) from gRPC Server Stream API:

```dart
var stream = client.serverStreamServerEvents(StreamServerEvents()..channels.add('todos'));
await for (var r in stream) {
  var obj = jsonDecode(r.json);
  if (r.selector.startsWith('todos')) {
    if (obj is Map) {
      print('EVENT ${r.selector} [${r.channel}]: #${obj['id']} ${obj['title']}');
    } else {
      print('EVENT ${r.selector} [${r.channel}]: ${obj}');
    }
  } else {
    print('EVENT ${r.selector} ${r.channels}: #${obj['userId']} ${obj['displayName']}');
  }
}
```

### Dart gRPC Server Stream Files Example

```dart
var stream = client.serverStreamFiles(StreamFiles()..paths.addAll([
  '/js/ss-utils.js',
  '/js/hot-loader.js',
  '/js/hot-fileloader.js',
]));

await for (var file in stream) {
  var text = utf8.decode(file.body);
  print('FILE ${file.name} (${file.length}): ${text.substring(0, text.length < 50 ? text.length : 50)} ...');
}
```

### Dart gRPC Authenticated Request Example

Depending on what Authentication Providers are available will determine how you can Authenticate and whether the
`AuthenticateResponse` will return a [stateless Bearer Token](/auth/authentication-and-authorization#authentication-per-request-auth-providers)
that can be used to Authenticate instead of a Server Session Id. 

Here's an example of authenticating with the common Credentials Auth and authenticating with either the 
[Session Id](/auth/sessions) or JWT Bearer Token (if [JWT is enabled](/auth/jwt-authprovider)):

```dart
// Authenticate user Username/Password Credentials Auth
var authResponse = await client.postAuthenticate(Authenticate()..provider='credentials'
  ..userName=userOrEmail..password=password);

// If using Session Auth
var authClient = createClient(options:CallOptions(metadata:{ 'X-ss-id': authResponse.sessionId }));

// If using Bearer Token stateless Auth Providers (e.g. JWT or API Key):
const bearerToken = authResponse.bearerToken; // or JWT or API Key
var authClient = createClient(options:CallOptions(metadata:{ 'Authorization': 'Bearer ${bearerToken}' }));

// Use authClient to make Authenticated Requests:
var response = await authClient.getHelloSecure(HelloSecure()..name = 'Authenticated gRPC Dart!');
print(response.result);
```

Refer to [/clients/dart](https://github.com/NetCoreApps/todo-world/tree/master/clients/dart)
for a complete example project.


# gRPC protoc GO Client
Source: https://docs.servicestack.net/grpc/go

[![](/img/pages/grpc/go.png)](https://youtu.be/FYA32J1-IA0)

::: info YouTube
[youtu.be/FYA32J1-IA0](https://youtu.be/FYA32J1-IA0)
:::

## Go protoc generated GrpcServiceClient TodoWorld Example

Install [x dotnet tool](/dotnet-tool):
    
```bash
$ dotnet tool install --global x 
```

Create new **TodoWorld** Go module:

```bash
$ go mod init TodoWorld
```

Add protoc generated TodoWorld DTOs and gRPC GrpcServiceClient to `services/` folder:

```bash
$ mkdir services
$ x proto-go https://todoworld.servicestack.net -out services
```

### Go protoc gRPC insecure Example

Create a new Go Console App in `client\main.go`:

```go
package main

import (
    context "context"
    "fmt"
    "log"

    "google.golang.org/grpc"

    pb "TodoWorld/services"
    "time"
)

func main() {
    conn, err := grpc.Dial("todoworld.servicestack.net:5054", grpc.WithInsecure())
    if err != nil {
        log.Fatalf("fail to dial: %v", err)
    }
    defer conn.Close()

    client := pb.NewGrpcServicesClient(conn)
    ctx, cancel := context.WithTimeout(context.Background(), time.Second)
    defer cancel()

    response, err := client.GetHello(ctx, &pb.Hello{Name: "gRPC Go"})
    if err != nil {
        log.Fatalf("GetHello: %v", err)
    }
    fmt.Println(response.Result)
}
```

Alternatively above Go example can be created with:

```bash
$ mkdir client
$ x mix todoworld-go -out client
```

Run example:

```bash
$ go run client\main.go
```

### Go protoc gRPC SSL Example

Download TodoWorld SSL Certificate used for its gRPC HTTP/2 Services:

```bash
$ x get https://todoworld.servicestack.net/grpc.crt 
```

Use certificate when initializing `NewGrpcServicesClient`:

```go
package main

import (
    context "context"
    "fmt"
    "log"

    "google.golang.org/grpc"
    "google.golang.org/grpc/credentials"

    pb "TodoWorld/services"
    "time"
)

func main() {
    creds, err := credentials.NewClientTLSFromFile("grpc.crt", "")
    if err != nil {
        log.Fatalf("could not process the credentials: %v", err)
    }

    conn, err := grpc.Dial("todoworld.servicestack.net:50051", grpc.WithTransportCredentials(creds))
    if err != nil {
        log.Fatalf("fail to dial: %v", err)
    }
    defer conn.Close()

    client := pb.NewGrpcServicesClient(conn)
    ctx, cancel := context.WithTimeout(context.Background(), time.Second)
    defer cancel()

    response, err := client.GetHello(ctx, &pb.Hello{Name: "gRPC Go"})
    if err != nil {
        log.Fatalf("GetHello: %v", err)
    }
    fmt.Println(response.Result)
}
```

Override `client/main.go` with the above Go Example: 

```bash
$ x mix todoworld-go-ssl -out client
```

Run example:

```bash
$ go run client\main.go
```

### Go Local Development gRPC SSL CRUD Example

```go
package main

import (
    context "context"
    "fmt"
    "log"

    "google.golang.org/grpc"
    "google.golang.org/grpc/credentials"

    "time"
    pb "todoworld/services"
)

func main() {

    // Load the certificates from disk
    creds, err := credentials.NewClientTLSFromFile("dev.crt", "localhost:5001")
    if err != nil {
        log.Fatalf("could not process the credentials: %v", err)
    }

    conn, err := grpc.Dial(address, grpc.WithTransportCredentials(creds))
    if err != nil {
        log.Fatalf("fail to dial: %v", err)
    }
    defer conn.Close()

    client := pb.NewGrpcServicesClient(conn)
    ctx, cancel := context.WithTimeout(context.Background(), time.Second)
    defer cancel()


    _, err = client.PostResetTodos(ctx, &pb.ResetTodos{})
    if err != nil {
        log.Fatalf("PostResetTodos: %v", err)
    }

    fmt.Println("TODO EXAMPLE")

    //POST /todos
    r1, err := client.PostCreateTodo(ctx, &pb.CreateTodo{Title: "ServiceStack"})
    if err != nil {
        log.Fatalf("PostCreateTodo: %v", err)
    }
    todo := r1.Result
    fmt.Println("new todo Id:", todo.Id, "Title:", todo.Title)

    //GET /todos
    all, err := client.CallGetTodos(ctx, &pb.GetTodos{})
    if err != nil {
        log.Fatalf("CallGetTodos: %v", err)
    }
    fmt.Println("todos:", len(all.GetResults()))

    //GET /todos/1
    r2, err := client.CallGetTodo(ctx, &pb.GetTodo{Id: todo.Id})
    if err != nil {
        log.Fatalf("CallGetTodo: %v", err)
    }
    todo = r2.Result
    fmt.Println("get todo Id:", todo.Id, "Title:", todo.Title)

    //PUT /todos/1
    _, err = client.PutUpdateTodo(ctx, &pb.UpdateTodo{Id: todo.Id, Title: "gRPC"})
    if err != nil {
        log.Fatalf("PutUpdateTodo: %v", err)
    }

    //GET /todos/1
    r2, err = client.CallGetTodo(ctx, &pb.GetTodo{Id: todo.Id})
    if err != nil {
        log.Fatalf("CallGetTodo: %v", err)
    }
    todo = r2.Result
    fmt.Println("get todo Id:", todo.Id, "Title:", todo.Title)

    //DELETE /todos/1
    _, err = client.CallDeleteTodo(ctx, &pb.DeleteTodo{Id: todo.Id})
    if err != nil {
        log.Fatalf("CallDeleteTodo: %v", err)
    }

    //GET /todos
    all, err = client.CallGetTodos(ctx, &pb.GetTodos{})
    if err != nil {
        log.Fatalf("CallGetTodos: %v", err)
    }
    fmt.Println("todos:", len(all.GetResults()))
}
```

Refer to [/clients/go](https://github.com/NetCoreApps/todo-world/tree/master/clients/go)
for a complete example project.


# gRPC protoc Node.js Client
Source: https://docs.servicestack.net/grpc/nodejs

[![](/img/pages/grpc/nodejs.png)](https://youtu.be/QL56lOHiXVM)

::: info YouTube
[youtu.be/QL56lOHiXVM](https://youtu.be/QL56lOHiXVM)
:::

## Node.js protoc generated GrpcServicesStub Client TodoWorld Example

Install [x dotnet tool](/dotnet-tool):
    
```bash
$ dotnet tool install --global x 
```

Create npm **package.json**:

```bash
$ npm init
```
    
Add dependencies:

```json
{
  "name": "todoworld-grpc",
  "version": "0.1.0",
  "description": "gRPC node.js Todo World Example",
  "devDependencies": {
    "@grpc/proto-loader": "^0.1.0",
    "google-protobuf": "^3.6.1",
    "grpc": "^1.11.0",
    "webpack": "^4.16.5",
    "webpack-cli": "^3.1.0"
  }
}
```

Install dependencies:

```bash
$ npm install
```

Add protoc generated TodoWorld DTOs and gRPC Service Client:

```bash
$ x proto-js-node https://todoworld.servicestack.net
```

### Node.js protoc gRPC insecure Example

Use protoc generated DTOs and `GrpcServicesClient` to call TodoWorld gRPC Service in `index.js`:

```js
const { Hello } = require('./services_pb.js');
const { GrpcServicesClient } = require('./services_grpc_pb.js');
const grpc = require('grpc');
const { promisify } = require('util');

async function main() {

    const client = new GrpcServicesClient('todoworld.servicestack.net:5054', 
        grpc.credentials.createInsecure());

    // Convert gRPC's callback APIs to await friendly promises
    const { getHello } = promisifyAll(client);
    
    let request = new Hello();
    request.setName("gRPC Node.js");
    let response = await getHello(request);
    console.log(response.getResult());
}

function promisifyAll(client) {
    const to = {};
    for (var k in client) {
        if (typeof client[k] != 'function') continue;
        to[k] = promisify(client[k].bind(client));
    }
    return to;
}

main();
```

Create `index.js` with the above Node.js Example: 

```bash
$ x mix todoworld-node
```

Run example:

```bash
$ node --no-deprecation index.js
```

### Node.js protoc gRPC SSL Example

Download TodoWorld SSL Certificate used for its gRPC HTTP/2 Services:

```bash
$ x get https://todoworld.servicestack.net/grpc.crt 
```

Use certificate when initializing `GrpcServicesClient`:

```js
const { Hello } = require('./services_pb.js');
const { GrpcServicesClient } = require('./services_grpc_pb.js');
const grpc = require('grpc');
const { promisify } = require('util');
const fs = require('fs');

async function main() {

    const client = new GrpcServicesClient('todoworld.servicestack.net:50051', 
        grpc.credentials.createSsl(fs.readFileSync('grpc.crt')));

    // Convert gRPC's callback APIs to await friendly promises
    const { getHello } = promisifyAll(client);
    
    let request = new Hello();
    request.setName("gRPC Node.js");
    let response = await getHello(request);
    console.log(response.getResult());
}

function promisifyAll(client) {
    const to = {};
    for (var k in client) {
        if (typeof client[k] != 'function') continue;
        to[k] = promisify(client[k].bind(client));
    }
    return to;
}

main();
```

Override `index.js` with the above Node.js Example: 

```bash
$ x mix todoworld-node-ssl
```

Run example:

```bash
$ node --no-deprecation index.js
```

### Node.js Local Development gRPC SSL CRUD Example

```js
const { 
    ResetTodos,
    CreateTodo,
    GetTodo,
    GetTodos,
    UpdateTodo,
    DeleteTodo,
} = require('./services_pb.js');

const { GrpcServicesClient } = require('./services_grpc_pb.js');

const grpc = require('grpc');

const { promisify } = require('util');
const fs = require('fs');

async function main() {

    const client = new GrpcServicesClient('localhost:5001', 
        grpc.credentials.createSsl(fs.readFileSync('../certs/dev.crt')));
    
    // Convert gRPC's callback APIs to await friendly promises
    const { 
        postResetTodos,
        postCreateTodo,
        callGetTodos,
        callGetTodo,
        putUpdateTodo,
        callDeleteTodo,
    } = promisifyAll(client);

    console.log('TODO EXAMPLE');
    await postResetTodos(new ResetTodos());

    //POST /todos
    request = new CreateTodo();
    request.setTitle('ServiceStack');
    var todo = (await postCreateTodo(request)).getResult();
    console.log(`new todo Id: ${todo.getId()}, Title: ${todo.getTitle()}`);

    //GET /todos
    var all = await callGetTodos(new GetTodos());
    console.log(`todos: ${all.getResultsList().length}`);

    //GET /todos/1
    request = new GetTodo();
    request.setId(todo.getId());
    todo = (await callGetTodo(request)).getResult();
    console.log(`get todo Id: ${todo.getId()}, Title: ${todo.getTitle()}`);

    //PUT /todos/1
    request = new UpdateTodo();
    request.setId(todo.getId());
    request.setTitle('gRPC');
    await putUpdateTodo(request);

    //GET /todos/1
    request = new GetTodo();
    request.setId(todo.getId());
    todo = (await callGetTodo(request)).getResult();
    console.log(`get todo Id: ${todo.getId()}, Title: ${todo.getTitle()}`);

    //DELETE /todos/1
    request = new DeleteTodo();
    request.setId(todo.getId());
    await callDeleteTodo(request);

    //GET /todos
    all = await callGetTodos(new GetTodos());
    console.log(`todos: ${all.getResultsList().length}`);
}

// Necessary until gRPC provides a native async friendly solution https://github.com/grpc/grpc-node/issues/54
function promisifyAll(client) {
    const to = {};
    for (var k in client) {
        if (typeof client[k] != 'function') continue;
        to[k] = promisify(client[k].bind(client));
    }
    return to;
}

main();
```

Refer to [/clients/js-node](https://github.com/NetCoreApps/todo-world/tree/master/clients/js-node)
for a complete example project.


# gRPC protoc Python Client
Source: https://docs.servicestack.net/grpc/python

[![](/img/pages/grpc/python.png)](https://youtu.be/rcDdabAELnA)

::: info YouTube
[youtu.be/rcDdabAELnA](https://youtu.be/rcDdabAELnA)
:::

## Python protoc generated GrpcServicesStub Client TodoWorld Example

Install [x dotnet tool](/dotnet-tool):
    
```bash
$ dotnet tool install --global x 
```

Install [grpcio-tools](https://pypi.org/project/grpcio-tools/):

```bash
$ pip install grpcio-tools
```

Add protoc generated TodoWorld DTOs and gRPC Service Client:

```bash
$ x proto-python https://todoworld.servicestack.net
```

### Python protoc gRPC insecure Example

Use protoc generated DTOs and `GrpcServicesStub` to call TodoWorld gRPC Service in `main.py`:

```python
import grpc
import services_pb2
import services_pb2_grpc

def run():
    with grpc.insecure_channel('todoworld.servicestack.net:5054') as channel:

        client = services_pb2_grpc.GrpcServicesStub(channel)
        response = client.GetHello(services_pb2.Hello(Name="gRPC Python"))
        print(response.Result)

if __name__ == '__main__':
    run()
```

Create `main.py` with the above Python Example: 

```bash
$ x mix todoworld-python
```
Run example:

```bash
$ python main.py
```

### Python protoc gRPC SSL Example

Download TodoWorld SSL Certificate used for its gRPC HTTP/2 Services:

```bash
$ x get https://todoworld.servicestack.net/grpc.crt 
```

Use certificate when initializing `GrpcServicesStub`:

```python
import grpc
import services_pb2
import services_pb2_grpc

def run():
    with open('grpc.crt', 'rb') as f:
        credentials = grpc.ssl_channel_credentials(f.read())
    with grpc.secure_channel('todoworld.servicestack.net:50051', credentials) as channel:

        client = services_pb2_grpc.GrpcServicesStub(channel)
        response = client.GetHello(services_pb2.Hello(Name="gRPC Python"))
        print(response.Result)

if __name__ == '__main__':
    run()
```

Override `main.py` with the above Python Example: 

```bash
$ x mix todoworld-python-ssl
```

Run example:

```bash
$ python main.py
```

### Python Local Development gRPC SSL CRUD Example

```python
import grpc
import services_pb2
import services_pb2_grpc

def run():

    with open('dev.crt', 'rb') as f:
        cer = f.read()
    credentials = grpc.ssl_channel_credentials(cer)
    with grpc.secure_channel('localhost:5001', credentials) as channel:

        client = services_pb2_grpc.GrpcServicesStub(channel)
        client.PostResetTodos(services_pb2.ResetTodos())

        print("TODO EXAMPLE")

        # POST /todos
        todo = client.PostCreateTodo(services_pb2.CreateTodo(Title="ServiceStack")).Result
        print(f'new todo Id: {todo.Id}, Title: {todo.Title}')

        # GET /todos
        all = client.CallGetTodos(services_pb2.GetTodos())
        print(f'todos: {len(all.Results)}')

        # GET /todos/1
        todo = (client.CallGetTodo(services_pb2.GetTodo(Id=todo.Id))).Result
        print(f'get todo Id: {todo.Id}, Title: {todo.Title}')

        # PUT /todos/1
        client.PutUpdateTodo(services_pb2.UpdateTodo(Id=todo.Id, Title='gRPC'))

        # GET /todos/1
        todo = (client.CallGetTodo(services_pb2.GetTodo(Id=todo.Id))).Result
        print(f'get todo Id: {todo.Id}, Title: {todo.Title}')

        # DELETE /todos/1
        client.CallDeleteTodo(services_pb2.DeleteTodo(Id=todo.Id))

        # GET /todos
        all = client.CallGetTodos(services_pb2.GetTodos())
        print(f'todos: {len(all.Results)}')

if __name__ == '__main__':
    run()
```

Refer to [/clients/python](https://github.com/NetCoreApps/todo-world/tree/master/clients/python)
for a complete example project.


# gRPC protoc Ruby Client
Source: https://docs.servicestack.net/grpc/ruby

[![](/img/pages/grpc/ruby.png)](https://youtu.be/yvLnqgXKYTI)

::: info YouTube
[youtu.be/yvLnqgXKYTI](https://youtu.be/yvLnqgXKYTI)
:::

## Ruby protoc generated GrpcServicesStub Client TodoWorld Example

Install [x dotnet tool](/dotnet-tool):
    
```bash
$ dotnet tool install --global x 
```

Install required gems:

```bash
$ gem install grpc bundler 
```

Create **todoworld.gemspec**:

```ruby
# -*- ruby -*-
# encoding: utf-8

Gem::Specification.new do |s|
  s.name          = 'todoworld'
  s.version       = '1.0.0'
  s.summary       = 'gRPC Ruby TodoWorld Example'
  s.description   = 'Simple TodoWorld demo of using gRPC from Ruby'

  s.files         = `git ls-files -- *`.split("\n")
  s.executables   = `git ls-files -- client.rb`.split("\n").map do |f|
    File.basename(f)
  end
  s.require_paths = ['lib']
  s.platform      = Gem::Platform::RUBY

  s.add_dependency 'grpc', '~> 1.0'
  s.add_dependency 'multi_json', '~> 1.13.1'
  s.add_development_dependency 'bundler', '~> 2.0'
end
```

Generate `Gemfile` and install dependencies:

```bash
$ bundle init
$ bundle install
```

Add protoc generated TodoWorld DTOs and gRPC Service Client:

```bash
$ mkdir lib
$ x proto-ruby https://todoworld.servicestack.net -out lib
```

### Ruby protoc gRPC insecure Example

Use protoc generated DTOs and `GrpcServicesStub` to call TodoWorld gRPC Service in `main.rb`:

```ruby
#!/usr/bin/env ruby

this_dir = File.expand_path(File.dirname(__FILE__))
lib_dir = File.join(this_dir, 'lib')
$LOAD_PATH.unshift(lib_dir) unless $LOAD_PATH.include?(lib_dir)

require 'grpc'
require 'services_pb'
require 'services_services_pb'

def main
    client = GrpcServices::Stub.new('todoworld.servicestack.net:5054', 
        :this_channel_is_insecure)

    response = client.get_hello(Hello.new(Name:'gRPC Ruby'))
    puts response.Result
end

main
```

Create `main.rb` with the above Ruby Example: 

```bash
$ x mix todoworld-ruby
```

Run example:

```bash
$ main.rb
```

### Ruby protoc gRPC SSL Example

Download TodoWorld SSL Certificate used for its gRPC HTTP/2 Services:

```bash
$ x get https://todoworld.servicestack.net/grpc.crt
```

Use certificate when initializing `GrpcServicesStub`:

```ruby
#!/usr/bin/env ruby

this_dir = File.expand_path(File.dirname(__FILE__))
lib_dir = File.join(this_dir, 'lib')
$LOAD_PATH.unshift(lib_dir) unless $LOAD_PATH.include?(lib_dir)

require 'grpc'
require 'services_pb'
require 'services_services_pb'

def main
    credentials = GRPC::Core::ChannelCredentials.new(File.read('grpc.crt'))
    client = GrpcServices::Stub.new('todoworld.servicestack.net:50051', credentials)

    response = client.get_hello(Hello.new(Name:'gRPC Ruby'))
    puts response.Result
end

main
```

Override `main.rb` with the above Ruby Example: 

```bash
$ x mix todoworld-ruby-ssl
```

Run example:

```bash
$ ruby main.rb
```

### Ruby Local Development gRPC SSL CRUD Example

```ruby
#!/usr/bin/env ruby

this_dir = File.expand_path(File.dirname(__FILE__))
lib_dir = File.join(this_dir, 'lib')
$LOAD_PATH.unshift(lib_dir) unless $LOAD_PATH.include?(lib_dir)

require 'grpc'
require 'services_pb'
require 'services_services_pb'

def main
    credentials = GRPC::Core::ChannelCredentials.new(File.read('dev.crt'))
    client = GrpcServices::Stub.new('localhost:5001', credentials)
    client.post_reset_todos(ResetTodos.new())

    puts "TODO EXAMPLE"

    # POST /todos
    todo = client.post_create_todo(CreateTodo.new(Title:"ServiceStack")).Result
    puts "new todo Id: #{todo.Id}, Title: #{todo.Title}"
    
    # GET /todos
    all = client.call_get_todos(GetTodos.new())
    puts "todos: #{all.Results.length}"
    
    # GET /todos/1
    todo = (client.call_get_todo(GetTodo.new(Id:todo.Id))).Result
    puts "get todo Id: #{todo.Id}, Title: #{todo.Title}"
    
    # PUT /todos/1
    client.put_update_todo(UpdateTodo.new(Id:todo.Id, Title:'gRPC'))
    
    # GET /todos/1
    todo = (client.call_get_todo(GetTodo.new(Id:todo.Id))).Result
    puts "get todo Id: #{todo.Id}, Title: #{todo.Title}"
    
    # DELETE /todos/1
    client.call_delete_todo(DeleteTodo.new(Id:todo.Id))
    
    # GET /todos
    all = client.call_get_todos(GetTodos.new())
    puts "todos: #{all.Results.length}"
    
end

main
```

Refer to [/clients/ruby](https://github.com/NetCoreApps/todo-world/tree/master/clients/ruby)
for a complete example project.


# gRPC protoc PHP Client
Source: https://docs.servicestack.net/grpc/php

[![](/img/pages/grpc/php.png)](https://youtu.be/lRy3qb-x2Yc)

::: info YouTube
[youtu.be/lRy3qb-x2Yc](https://youtu.be/lRy3qb-x2Yc)
:::

## PHP protoc generated GrpcServiceClient TodoWorld Example

### Prerequisites

This requires `php` >= 5.5, `pecl`, `composer`

Install the `grpc` extension:

```bash
$ [sudo] pecl install grpc
```
   
## Setup for Windows

#### gRPC PECL Download for Windows

https://windows.php.net/downloads/pecl/releases/grpc/

The PHP extension filename is in the following format:

```
php_grpc-{GRPC_VERSION}-{PHP_VERSION}-{THREAD_SAFETY}-{VC++_RUNTIME}-{CPU_ARCH}.zip
```

Select appropriate version for your OS and copy to `{PHP_HOME}\ext`, then modify your **php.ini** file to include `extension=grpc`.

### Getting Started

Install [x dotnet tool](/dotnet-tool):
    
```bash
$ dotnet tool install --global x 
```

Add required dependencies to **composer.json**:

```json
{
  "name": "servicestack/grpc-todoworld",
  "description": "Simple TodoWorld demo of using gRPC from PHP",
  "require": {
    "grpc/grpc": "^v1.3.0",
    "google/protobuf": "^v3.3.0"
  },
  "autoload": {
    "psr-4": {
      "": "route_guide/"
    }
  }
}
```

Install dependencies:

```bash
$ composer install
```
    
Add protoc generated TodoWorld DTOs and gRPC GrpcServiceClient:

```bash
$ x proto-php https://todoworld.servicestack.net
```

### PHP protoc gRPC insecure Example

Use protoc generated DTOs and `GrpcServiceClient` to call TodoWorld gRPC Service in `main.php`:

```php
<?php

require dirname(__FILE__).'/vendor/autoload.php';
@include_once dirname(__FILE__).'/GPBMetadata/Services.php';
@include_once dirname(__FILE__).'/TodoWorld/GrpcServicesClient.php';
@include_once dirname(__FILE__).'/TodoWorld/Hello.php';
@include_once dirname(__FILE__).'/TodoWorld/HelloResponse.php';

$client = new TodoWorld\GrpcServicesClient('todoworld.servicestack.net:5054', [
    'credentials' => Grpc\ChannelCredentials::createInsecure(),
]);

$request = new TodoWorld\Hello();
$request->setName("gRPC PHP");
list($reply, $status) = $client->GetHello($request)->wait();
if ($status->code !== Grpc\STATUS_OK) {
    echo "Call did not complete successfully. Status object:\n";
    var_dump($status);
    exit(1);
}
echo $reply->getResult();
```

Override `main.php` with the above PHP Example: 

```bash
$ x mix todoworld-php
```

Run example:

```bash
$ php main.php
```

### PHP protoc gRPC SSL Example

Download TodoWorld SSL Certificate used for its gRPC HTTP/2 Services:

```bash
$ x get https://todoworld.servicestack.net/grpc.crt 
```

Use certificate when initializing `GrpcServicesClient`:

```php
<?php

require dirname(__FILE__).'/vendor/autoload.php';
@include_once dirname(__FILE__).'/GPBMetadata/Services.php';
@include_once dirname(__FILE__).'/TodoWorld/GrpcServicesClient.php';
@include_once dirname(__FILE__).'/TodoWorld/Hello.php';
@include_once dirname(__FILE__).'/TodoWorld/HelloResponse.php';

$client = new TodoWorld\GrpcServicesClient('todoworld.servicestack.net:50051', [
    'credentials' => Grpc\ChannelCredentials::createSsl(file_get_contents('grpc.crt')),
]);

$request = new TodoWorld\Hello();
$request->setName("gRPC PHP");
list($reply, $status) = $client->GetHello($request)->wait();
if ($status->code !== Grpc\STATUS_OK) {
    echo "Call did not complete successfully. Status object:\n";
    var_dump($status);
    exit(1);
}
echo $reply->getResult();
```

Override `main.php` with the above PHP Example: 

```bash
$ x mix todoworld-php-ssl
```

Run example:

```bash
$ php main.php
```

### PHP Local Development gRPC SSL CRUD Example

```php
<?php

require dirname(__FILE__).'/vendor/autoload.php';

@include_once dirname(__FILE__).'/GPBMetadata/Services.php';
@include_once dirname(__FILE__).'/TodoWorld/GrpcServicesClient.php';
@include_once dirname(__FILE__).'/TodoWorld/EmptyResponse.php';

@include_once dirname(__FILE__).'/TodoWorld/Hello.php';
@include_once dirname(__FILE__).'/TodoWorld/HelloResponse.php';

@include_once dirname(__FILE__).'/TodoWorld/Todo.php';
@include_once dirname(__FILE__).'/TodoWorld/ResetTodos.php';
@include_once dirname(__FILE__).'/TodoWorld/CreateTodo.php';
@include_once dirname(__FILE__).'/TodoWorld/CreateTodoResponse.php';
@include_once dirname(__FILE__).'/TodoWorld/GetTodo.php';
@include_once dirname(__FILE__).'/TodoWorld/GetTodoResponse.php';
@include_once dirname(__FILE__).'/TodoWorld/GetTodos.php';
@include_once dirname(__FILE__).'/TodoWorld/GetTodosResponse.php';
@include_once dirname(__FILE__).'/TodoWorld/UpdateTodo.php';
@include_once dirname(__FILE__).'/TodoWorld/UpdateTodoResponse.php';
@include_once dirname(__FILE__).'/TodoWorld/DeleteTodo.php';
@include_once dirname(__FILE__).'/TodoWorld/DeleteTodoResponse.php';

$client = new TodoWorld\GrpcServicesClient('localhost:5001', [
    'credentials' => Grpc\ChannelCredentials::createSsl(file_get_contents(dirname(__FILE__).'dev.crt')),
]);

global $client;
function client() { return $GLOBALS['client']; }

function assertStatus($status)
{
    if ($status->code !== Grpc\STATUS_OK) {
        echo "Call did not complete successfully. Status object:\n";
        var_dump($status);
        exit(1);
    }
}

function hello($name) 
{
    $request = new TodoWorld\Hello();
    $request->setName($name);
    list($reply, $status) = client()->GetHello($request)->wait();
    assertStatus($status);
    return $reply->getResult();
}
// echo hello("World") . "\n";

list($reply, $status) = $client->PostResetTodos(new TodoWorld\ResetTodos())->wait();
assertStatus($status);

//POST /todos
$request = new TodoWorld\CreateTodo();
$request->setTitle("ServiceStack");
list($reply, $status) = $client->PostCreateTodo($request)->wait();
assertStatus($status);
$todo = $reply->getResult();
echo "new todo Id: " . $todo->getId() . ", Title: " . $todo->getTitle() . "\n";

//GET /todos
list($reply, $status) = $client->CallGetTodos(new TodoWorld\GetTodos())->wait();
assertStatus($status);
echo "todos: " . count($reply->getResults())  . "\n";

//GET /todos/1
$request = new TodoWorld\GetTodo();
$request->setId($todo->getId());
list($reply, $status) = $client->CallGetTodo($request)->wait();
assertStatus($status);
$todo = $reply->getResult();
echo "get todo Id: " . $todo->getId() . ", Title: " . $todo->getTitle() . "\n";

//PUT /todos/1
$request = new TodoWorld\UpdateTodo();
$request->setId($todo->getId());
$request->setTitle("gRPC");
list($reply, $status) = $client->PutUpdateTodo($request)->wait();
assertStatus($status);

//GET /todos/1
$request = new TodoWorld\GetTodo();
$request->setId($todo->getId());
list($reply, $status) = $client->CallGetTodo($request)->wait();
assertStatus($status);
$todo = $reply->getResult();
echo "get todo Id: " . $todo->getId() . ", Title: " . $todo->getTitle() . "\n";

//DELETE /todos/1
$request = new TodoWorld\DeleteTodo();
$request->setId($todo->getId());
list($reply, $status) = $client->CallDeleteTodo($request)->wait();
assertStatus($status);

//GET /todos
list($reply, $status) = $client->CallGetTodos(new TodoWorld\GetTodos())->wait();
assertStatus($status);
echo "todos: " . count($reply->getResults())  . "\n";
```

Refer to [/clients/php](https://github.com/NetCoreApps/todo-world/tree/master/clients/php)
for a complete example project.


# Locode - Database-First
Source: https://docs.servicestack.net/locode/database-first

Using [AutoQuery's AutoGen](/autoquery/autogen) enables the quickest way to modernize an existing database by generating Data Models & AutoQuery
CRUD APIs from RDBMS table schemas. From Locode's point of view, the result is indistinguishable to [Code-First](/locode/code-first) where instead of developers defining Data Models & API Contracts in code they're dynamically generated by AutoGen at runtime, on Startup.

The difference is how APIs & Types are customized, with Code-First Types able to naturally access the [Declarative Dev Model](/locode/declarative) 
using C# Attributes, Database-First Models instead need to dynamically add attributes at runtime using AutoGen's Type & Service filters.

Regardless of how they're created & customized, each have access to Locode's instant modern UI around AutoQuery services.

To get started quickly watch this video for a step-by-step walkthrough into creating a **Database-first Locode App**:

<div class="py-8 max-w-7xl mx-auto px-4 sm:px-6">
    <lite-youtube class="w-full mx-4 my-4" width="560" height="315" videoid="NiTp5Z_5U2Y" style="background-image: url('https://img.youtube.com/vi/NiTp5Z_5U2Y/maxresdefault.jpg')"></lite-youtube>
</div>

## Northwind example

We have an example of this in the [Northwind demo](https://northwind.locode.dev) which provides a way to manage 
all the data in the Northwind database with some customizations to improve usability, all in **~120 lines of C#**.

## Create your project

<div class="not-prose flex">
<a href="https://account.servicestack.net/archive/NetCoreTemplates/web?Name=MyLocodeApp" class="text-xl hover:no-underline">
    <div class="bg-white dark:bg-gray-800 px-4 py-4 mr-4 mb-4 rounded-lg shadow-lg text-center items-center justify-center hover:shadow-2xl dark:border-2 dark:border-pink-600 dark:hover:border-blue-600">
        <div class="text-center font-extrabold flex items-center justify-center mb-2">
            <div class="text-4xl text-blue-600 my-3">
                <svg xmlns="http://www.w3.org/2000/svg" class="w-12 h-12" viewBox="0 0 24 24"><path fill="currentColor" d="M4 10.4V4a1 1 0 0 1 1-1h5V1h4v2h5a1 1 0 0 1 1 1v6.4l1.086.326a1 1 0 0 1 .682 1.2l-1.516 6.068A4.992 4.992 0 0 1 16 16a4.992 4.992 0 0 1-4 2a4.992 4.992 0 0 1-4-2a4.992 4.992 0 0 1-4.252 1.994l-1.516-6.068a1 1 0 0 1 .682-1.2L4 10.4zm2-.6L12 8l2.754.826l1.809.543L18 9.8V5H6v4.8zM4 20a5.978 5.978 0 0 0 4-1.528A5.978 5.978 0 0 0 12 20a5.978 5.978 0 0 0 4-1.528A5.978 5.978 0 0 0 20 20h2v2h-2a7.963 7.963 0 0 1-4-1.07A7.963 7.963 0 0 1 12 22a7.963 7.963 0 0 1-4-1.07A7.963 7.963 0 0 1 4 22H2v-2h2z"/></svg>
            </div>
        </div>
        <span class="archive-name px-4 pb-2 text-blue-600 dark:text-indigo-400">MyLocodeApp.zip</span>
        <div class="count mt-1 text-gray-400 text-sm"></div>
    </div>
</a>
</div>

Starting with the basic `web` template for a ServiceStack application will provide the basic solution structure 
with a sample Hello World service. This can be done using the [ServiceStack website](https://servicestack.net) under 
[Get Started](https://servicestack.net/start).

Alternatively, templates can be created using the dotnet CLI tool `x`. The dotnet `x` tool can be installed 
using the following command:

:::sh
dotnet tool install --global x
:::

Once installed, a new `web` template can be created using:

:::sh
x new web MyProjectName
:::

## Configuring database connection

Once you have the new web project open, you will need to configure the following.

- Database type (PostgreSQL, SQL Server, MySQL, or SQLite)
- Database connection string
- AutoQuery Generated Services

We can use the dotnet `x` tool to `mix` in specific database support and AutoQuery quickly using the command run from the project directory.

:::sh
x mix sqlite autoquery
:::

::: tip
Replace `sqlite` with `postgres`, `sqlserver`, or `mysql` or other RDBMS providers
:::

This command will create two files, `Configure.Db.cs` and `Configure.AutoQuery.cs` and install required NuGet dependencies into the AppHost (MyLocodeApp in the link above) project.



### Configure.Db.cs

Below we have an example using `sqlite` of the configuration to add an `IDbConnectionFactory` dependency into IoC created by this command.

```csharp
public class ConfigureDb : IHostingStartup
{
    public void Configure(IWebHostBuilder builder) => builder
        .ConfigureServices((context, services) => {
            services.AddSingleton<IDbConnectionFactory>(new OrmLiteConnectionFactory(
                context.Configuration.GetConnectionString("DefaultConnection")
                ?? ":memory:",
                SqliteDialect.Provider));
        });
}
```

The example above is using an in-`:memory:` SQLite database, but we want to use a pre-existing database the connection string will need to be updated.
To use the Northwind sample database, we can download and copy it into the AppHost project with the `Configure.Db.cs` file and replace the 
`:memory:` connection string with the file name `northwind.sqlite`. Another easy way to download `northwind.sqlite` is by using the `x` tool with the following 
command run from the AppHost directory.

:::sh
x mix northwind.sqlite
:::

Now our application can communicate with the Northwind sample database, we will need to configure AutoQuery to use AutoGen to generate our CRUD services from our database schema.

### Configure.AutoQuery.cs

With the database connection configured, next you will need to configure AutoQuery to scan your database schema and generate the required CRUD services.
This feature is known as `AutoGen` and can be enabled by instantiating the `GenerateCrudServices` option on the `AutoQueryFeature` plugin with the `AutoRegister` flag set to `true`.

```csharp
public class ConfigureAutoQuery : IHostingStartup
{
    public void Configure(IWebHostBuilder builder) => builder
        .ConfigureAppHost(appHost => {
            appHost.Plugins.Add(new AutoQueryFeature {
                MaxLimit = 1000,
                
                // Add this line, Configures Generated CRUD services with defaults
                GenerateCrudServices = new GenerateCrudServices()
                {
                    AutoRegister = true
                }
            });
        });
}
```

The `AutoQueryFeature` plugin will automatically use your registered `IDbConnectionFactory` to communicate with your database and generate services 
for the `public` schema. Running the application after these changes, we will have a `Query`, `Create`, `Update` and `Delete` services ready to use for each table.

![](/img/pages/locode/database-first-northwind-default.png)

### Multiple Schemas

By default, `GenerateCrudServices` with `AutoRegister` will create services for each table in the `public` schema.
If you want to enable services for tables in other schemas, you can use the `CreateServices` option. For example, if
you have a schema by the name of `dbo` and `public`, you would use the following options.

```csharp
appHost.Plugins.Add(new AutoQueryFeature {
    MaxLimit = 1000,
    //IncludeTotal = true,
    GenerateCrudServices = new GenerateCrudServices()
    {
        // Configure which schemas should be used, `public` is the default.
        CreateServices = new List<CreateCrudServices>
        {
            new CreateCrudServices(),
            new CreateCrudServices { Schema = "dbo" }
        }
    }
});
```

### Multiple database connections

If you are using [Named connections](/autoquery/rdbms#named-connection) with [OrmLite](/ormlite/), you can also specify these connections in the `CreateServices` list.
Named connection registration can be done using the `IDbConnectionFactory` and `RegisterConnection` method.

```csharp
// SqlServer with a named "Reporting" PostgreSQL connection as a part of the same `dbFactory`
var dbFactory = new OrmLiteConnectionFactory(connString, SqlServer2012Dialect.Provider);
container.Register<IDbConnectionFactory>(dbFactory);

dbFactory.RegisterConnection("Reporting", pgConnString, PostgreSqlDialect.Provider);
```

The string name provided to `RegisterConnection` must match that provided to the `NamedConnection` property on `CreateCrudServices`.

```csharp
appHost.Plugins.Add(new AutoQueryFeature {
    MaxLimit = 1000,
    //IncludeTotal = true,
    GenerateCrudServices = new GenerateCrudServices()
    {
        // Configure multiple databases, `public` is the default schema.
        CreateServices = new List<CreateCrudServices>
        {
            new CreateCrudServices(),
            new CreateCrudServices { NamedConnection = "Reporting" }
        }
    }
});
```

### Multiple Schemas with Named Connections

These options can be combined so that specific schemas on named connections can also be used.

```csharp
appHost.Plugins.Add(new AutoQueryFeature {
    MaxLimit = 1000,
    //IncludeTotal = true,
    GenerateCrudServices = new GenerateCrudServices()
    {
        // Configure multiple databases, `public` is the default schema.
        CreateServices = new List<CreateCrudServices>
        {
            new CreateCrudServices { NamedConnection = "Reporting" },
            new CreateCrudServices { NamedConnection = "Finance", Schema = "trading" }
        }
    }
});
```

## Customizing Locode App

Locode includes a [declarative dev model](/locode/declarative) where attributes can be used to add additional metadata 
to your services and data model that can be used to enlist additional functionality and enhance the Locode App's UI.

### Dynamically adding attributes

The use of C# attributes to configure your AutoQuery service metadata is optimal for code-first DTOs & Data Models 
but when starting with a Database First dev model, the Types are generated and only exist at runtime which typically 
would prohibit them from being annotated with C# attributes, however
[AutoQuery AutoGen's](/autoquery/autogen) `ServiceFilter` and `TypeFilter` lets you
dynamically apply attributes to its generated types at startup.

### Exporting to code-first Types

In addition to enabling access to the same rich declarative functionality ServiceStack
[makes available via attributes](/locode/declarative), 
it also annotates the code-generated types which are retained when moving from database-first to code-first dev model by
[exporting to code-first types](/autoquery/autogen#export-code-first-dtos) with:

:::sh
`x csharp https://localhost:5001 -path /crud/all/csharp`
:::

### Annotated Example of Northwind's Customizations

To help illustrate some customizations available we've annotated the customizations made to the Northwind Sample SQLite Database
that was used to create the custom [northwind.locode.dev](https://northwind.locode.dev) Locode App:

[![](/img/pages/locode/northwind/screenshot.png)](https://northwind.locode.dev/locode/QueryEmployees)

### Modifying Dynamic Types at Runtime

Annotating the Database First code-gen types can be done via the `ServiceFilter` and `TypeFilter` properties on
`GenerateCrudServices` instructions when registering the `AutoQueryFeature`.

The `ServiceFilter` is called for every Service Operation whilst the `TypesFilter` is called for every code-gen Type
including Request & Response DTOs.

```csharp
Plugins.Add(new AutoQueryFeature {
    MaxLimit = 100,
    GenerateCrudServices = new GenerateCrudServices {
        AutoRegister = true,
        ServiceFilter = (op, req) => {
            // Annotate all Auto generated Request DTOs with [Tag("Northwind")] attribute
            op.Request.AddAttributeIfNotExists(new TagAttribute("Northwind"));
        },
        TypeFilter = (type, req) =>
        {
            // Configure to use Icon for this Type
            if (Icons.TryGetValue(type.Name, out var icon))
                type.AddAttribute(new IconAttribute { Svg = Svg.Create(icon) });

            // Is Employee Data Model or any AutoQuery Employee Request DTO
            if (type.Name == "Employee" || type.IsCrudCreateOrUpdate("Employee"))
            {
                // Remove unused `Photo` column
                type.Properties.RemoveAll(x => x.Name == "Photo");
                
                // Reorder columns from db-schema to the order we want them to appear in the UI
                type.ReorderProperty("PhotoPath", before: "Title")
                    .AddAttribute(new FormatAttribute(FormatMethods.IconRounded));
                type.ReorderProperty("ReportsTo", after: "Title");
                                
                if (type.IsCrud()) // Is AutoQuery Employee Request DTO
                {
                    // Configure to use File Input & upload to 'employees' Managed File Upload location 
                    type.Property("PhotoPath")
                        .AddAttribute(new InputAttribute { Type = Input.Types.File })
                        .AddAttribute(new UploadToAttribute("employees"));
                    
                    // Use TextArea control for larger text inputs
                    type.Property("Notes")
                        .AddAttribute(new InputAttribute { Type = Input.Types.Textarea });
                }
                else if (type.Name == "Employee") // Employee Data Model
                {
                    // Configure Employee FK Relation, utilizing UX-friendly LastName & Employee Lookup   
                    type.Property("ReportsTo").AddAttribute(
                        new RefAttribute { Model = "Employee", RefId = "Id", RefLabel = "LastName" });
                    
                    // Format to use `tel:` link allowing Phone call to be initiated from UI
                    type.Property("HomePhone").AddAttribute(new FormatAttribute(FormatMethods.LinkPhone));
                }
            }
            else if (type.Name == "Order")
            {
                // Customize all Date Columns to use UX-friendly Date Format 
                type.Properties.Where(x => x.Name.EndsWith("Date")).Each(p =>
                    p.AddAttribute(new IntlDateTime(DateStyle.Medium)));
                
                // Format number as USD Currency using JavaScript's Intl.NumberFormat
                type.Property("Freight").AddAttribute(new IntlNumber { Currency = NumberCurrency.USD });
                
                // Configure Shipper FK Relation, utilizing UX-friendly CompanyName & Shipper Lookup   
                type.Property("ShipVia").AddAttribute(
                    new RefAttribute { Model = "Shipper", RefId = "Id", RefLabel = "CompanyName" });
            }
            else if (type.Name == "OrderDetail")
            {
                // Format number as USD Currency using JavaScript's Intl.NumberFormat
                type.Property("UnitPrice").AddAttribute(new IntlNumber { Currency = NumberCurrency.USD });
                // Format as % using JavaScript's Intl.NumberFormat
                type.Property("Discount").AddAttribute(new IntlNumber(NumberStyle.Percent));
            }
            else if (type.Name == "EmployeeTerritory")
            {
                // Configure Territory FK Relation & Lookup, utilizing UX-friendly TerritoryDescription
                type.Property("TerritoryId").AddAttribute(new RefAttribute {
                    Model = "Territory", RefId = "Id", RefLabel = "TerritoryDescription" });
            }
            else if (type.Name is "Customer" or "Supplier" or "Shipper")
            {
                // Format to use `tel:` link allowing Phone call to be initiated from UI
                type.Property("Phone").AddAttribute(new FormatAttribute(FormatMethods.LinkPhone));
                type.Property("Fax")?.AddAttribute(new FormatAttribute(FormatMethods.LinkPhone));
            }
        },
    },
});
```

### Code-gen Customization Helpers

A number of UX-Friendly extension methods are available to reduce effort for applying common customizations to
`MetadataType` and `MetadataPropertyType` blueprints used in code generating .NET Types:

| Type Methods              | Description                                                             |
|---------------------------|-------------------------------------------------------------------------|
| AddAttribute()            | Add Attribute to Type                                                   |
| AddAttributeIfNotExists() | Add Attribute to Type if not already exists                             |
| Property()                | Resolve Property from Type                                              |
| ReorderProperty()         | Reorder where the DB Column appears in Type (changes API & UI ordering) |
| EachProperty()            | Apply custom lambda to each matching property                           |
| RemoveProperty()          | Omit properties from inclusion in code-gen type                         |

| Property Methods          | Description                                                             |
|---------------------------|-------------------------------------------------------------------------|
| AddAttribute()            | Add Attribute to Property                                               |
| AddAttributeIfNotExists() | Add Attribute to Property if not already exists                         |

### Format search results

The [Declarative Attributes docs](/locode/declarative) contains a more complete reference of built-in customizations,
but we'll cover a few the Northwind Locode App uses to illustrate some potential enhancements available.  

An effortless way to add a lot of value to DB Apps is to mark up the raw data stored in RDBMS tables into a UX-friendly
view, an example of this in Northwind is using `FormatMethods.LinkPhone` on the `Phone` and `Fax` properties for 
the `Customer`, `Supplier`, and `Shipper` tables: 

```csharp
if (type.Name is "Customer" or "Supplier" or "Shipper")
{
    type.Property("Phone").AddAttribute(new FormatAttribute(FormatMethods.LinkPhone));
    type.Property("Fax")?.AddAttribute(new FormatAttribute(FormatMethods.LinkPhone));
}
```

To format the phone numbers in `tel:` HTML links enabling 1-click to call, directly from the search results page:

<div class="not-prose">
<a href="https://northwind.locode.dev/locode/QueryCustomers" class="hover:no-underline">
<ul class="my-8 grid gap-4 sm:grid-cols-2">
    <li class="rounded-lg m-0 col-span-1 flex flex-col text-center items-center bg-white shadow divide-y divide-gray-200">
        <div class="flex-1 flex flex-col px-4 mt-4">
            <div class="mt-4 p-0 text-xl font-medium text-gray-500">Default</div>
            <div class="rounded-lg focus-within:ring-2 focus-within:ring-offset-2 focus-within:ring-offset-gray-100 focus-within:ring-indigo-500 overflow-hidden">
                <img src="/img/pages/locode/database-first-northwind-format-1.png" alt="">
            </div>
        </div>
    </li>
    <li class="rounded-lg m-0 col-span-1 flex flex-col text-center items-center bg-white shadow divide-y divide-gray-200">
        <div class="flex-1 flex flex-col px-4 mt-4">
            <div class="mt-4 p-0 text-xl font-medium text-gray-500">FormatMethods.LinkPhone</div>
            <div class="rounded-lg focus-within:ring-2 focus-within:ring-offset-2 focus-within:ring-offset-gray-100 focus-within:ring-indigo-500 overflow-hidden">
                <img src="/img/pages/locode/database-first-northwind-format-2.png" alt="">
            </div>
        </div>
    </li>
</ul>
</a>
</div>

A complete list of built-in functions can be found in the [Format Functions docs](/locode/formatters), another example used in 
Northwind is `FormatMethods.IconRounded` on `PhotoPath`:

```csharp
if (type.Name == "Employee" || type.IsCrudCreateOrUpdate("Employee"))
{
    type.ReorderProperty("PhotoPath", before: "Title")
        .AddAttribute(new FormatAttribute(FormatMethods.IconRounded));
}
```

To apply the `iconRounded` JavaScript function to render a preview of the Employee profile directly in the search results:

<div class="not-prose">
<a href="https://northwind.locode.dev/locode/QueryEmployees" class="hover:no-underline">
<ul class="grid gap-4 sm:grid-cols-2">
    <li class="rounded-lg m-0 col-span-1 flex flex-col text-center items-center bg-white shadow divide-y divide-gray-200">
        <div class="flex-1 flex flex-col px-4 mt-4">
            <div class="mt-4 p-0 text-xl font-medium text-gray-500">Default</div>
            <div class="rounded-lg focus-within:ring-2 focus-within:ring-offset-2 focus-within:ring-offset-gray-100 focus-within:ring-indigo-500 overflow-hidden">
                <img src="/img/pages/locode/database-first-northwind-format-icon-1.png" alt="">
            </div>
        </div>
    </li>
    <li class="rounded-lg m-0 col-span-1 flex flex-col text-center items-center bg-white shadow divide-y divide-gray-200">
        <div class="flex-1 flex flex-col px-4 mt-4">
            <div class="mt-4 p-0 text-xl font-medium text-gray-500">FormatMethods.IconRounded</div>
            <div class="rounded-lg focus-within:ring-2 focus-within:ring-offset-2 focus-within:ring-offset-gray-100 focus-within:ring-indigo-500 overflow-hidden">
                <img src="/img/pages/locode/database-first-northwind-format-icon-2.png" alt="">
            </div>
        </div>
    </li>
</ul>
</a>
</div>

`ReorderProperty` is used to change ordering of Table columns which changes the order they're displayed in APIs and UIs. 

::: tip
The original images in Northwind were migrated to reference external images using the following SQL:

```sql
update Employee set PhotoPath = "/profiles/employees/" || Employee.Id || ".jpg"
```

Where its uploads are now managed by the configured `FilesUploadFeature` and built-in File Input UI controls.
:::

### ECMAScript Internationalization APIs

ECMAScript's rich `Intl.NumberFormat`, `Intl.DateTimeFormat` and `Intl.RelativeTimeFormat` APIs are also available from the 
typed [[Intl*] Attributes](/locode/formatters.html#intl-attributes) which `OrderDetail` makes use of to format `UnitPrice`
in **USD Currency** and `Discount` in a **% percentage** format:

```csharp
if (type.Name == "OrderDetail")
{
    type.Property("UnitPrice").AddAttribute(new IntlNumber { Currency = NumberCurrency.USD });
    type.Property("Discount").AddAttribute(new IntlNumber(NumberStyle.Percent));
}
```

This can give a much more contextual view of the data in the returning from our services.

<div class="not-prose">
<a href="https://northwind.locode.dev/locode/QueryOrderDetails" class="hover:no-underline">
<ul class="grid gap-4 sm:grid-cols-2">
    <li class="rounded-lg m-0 col-span-1 flex flex-col text-center items-center bg-white shadow divide-y divide-gray-200">
        <div class="flex-1 flex flex-col px-4 mt-4">
            <div class="mt-4 p-0 text-xl font-medium text-gray-500">Default</div>
            <div class="rounded-lg focus-within:ring-2 focus-within:ring-offset-2 focus-within:ring-offset-gray-100 focus-within:ring-indigo-500 overflow-hidden">
                <img src="/img/pages/locode/database-first-northwind-intl-1.png" alt="">
            </div>
        </div>
    </li>
    <li class="rounded-lg m-0 col-span-1 flex flex-col text-center items-center bg-white shadow divide-y divide-gray-200">
        <div class="flex-1 flex flex-col px-4 mt-4">
            <div class="mt-4 p-0 text-xl font-medium text-gray-500">IntlNumber</div>
            <div class="rounded-lg focus-within:ring-2 focus-within:ring-offset-2 focus-within:ring-offset-gray-100 focus-within:ring-indigo-500 overflow-hidden">
                <img src="/img/pages/locode/database-first-northwind-intl-2.png" alt="">
            </div>
        </div>
    </li>
</ul>
</a>
</div>

For more customization options, see the [Declarative Attributes docs](/locode/declarative).


# Locode - Code-First
Source: https://docs.servicestack.net/locode/code-first

Code-First is the natural development model of [AutoQuery Services](/autoquery/rdbms) which facilitates the majority of a System and its UI can
be developed from simple, declarative C# POCOs to define the underlying RDBMS Schema Data Models and the precise typed API DTO Contracts 
of their surrounding AutoQuery & CRUD APIs. The Data and Service models can be further enhanced by ServiceStack's vast 
[declarative attributes](/locode/declarative) where a significant amount of behavior, functionality and customization can be defined, ranging from:

- Customizing how [Data Models map to RDBMS tables](/locode/declarative.html#table-data-model-attributes) and enlist RDBMS features
- [Customize Serialization & API behavior](/locode/declarative.html#custom-serialization)
- [Define AutoQuery & CRUD API behavior](/locode/declarative.html#autoquery-attributes)
- Define [Validation Rules](/locode/declarative.html#type-validation-attributes) and [Authorization restrictions](/locode/declarative.html#authentication-restrictions)
- [Annotate & Document APIs](/locode/declarative.html#annotate-apis)
- [Customize UI Behavior & Appearance](/locode/declarative.html#result-formatters)

To get started quickly, we've created a video containing a step-by-step walkthrough of creating a Code-First CRUD App with Locode:

<div class="py-8 max-w-7xl mx-auto px-4 sm:px-6">
    <lite-youtube class="w-full mx-4 my-4" width="560" height="315" videoid="mFyMgg7c3vg" style="background-image: url('https://img.youtube.com/vi/mFyMgg7c3vg/maxresdefault.jpg')"></lite-youtube>
</div>

## Bookings MVP

A simple example of using Locode for a back office bookings system would be a single table that a staff member populates.

### Create your project

To start off, we will create a project from the basic `web` template using the ServiceStack website. The link below will 
create a new project with the name "BookingsLocode".

<div class="not-prose flex">
<a href="https://account.servicestack.net/archive/NetCoreTemplates/web?Name=BookingsLocode" class="text-xl hover:no-underline">
    <div class="bg-white dark:bg-gray-800 px-4 py-4 mr-4 mb-4 rounded-lg shadow-lg text-center items-center justify-center hover:shadow-2xl dark:border-2 dark:border-pink-600 dark:hover:border-blue-600">
        <div class="text-center font-extrabold flex items-center justify-center mb-2">
            <div class="text-4xl text-blue-600 my-3">
                <svg xmlns="http://www.w3.org/2000/svg" class="w-12 h-12" viewBox="0 0 24 24"><path fill="currentColor" d="M4 10.4V4a1 1 0 0 1 1-1h5V1h4v2h5a1 1 0 0 1 1 1v6.4l1.086.326a1 1 0 0 1 .682 1.2l-1.516 6.068A4.992 4.992 0 0 1 16 16a4.992 4.992 0 0 1-4 2a4.992 4.992 0 0 1-4-2a4.992 4.992 0 0 1-4.252 1.994l-1.516-6.068a1 1 0 0 1 .682-1.2L4 10.4zm2-.6L12 8l2.754.826l1.809.543L18 9.8V5H6v4.8zM4 20a5.978 5.978 0 0 0 4-1.528A5.978 5.978 0 0 0 12 20a5.978 5.978 0 0 0 4-1.528A5.978 5.978 0 0 0 20 20h2v2h-2a7.963 7.963 0 0 1-4-1.07A7.963 7.963 0 0 1 12 22a7.963 7.963 0 0 1-4-1.07A7.963 7.963 0 0 1 4 22H2v-2h2z"/></svg>
            </div>
        </div>
        <span class="archive-name px-4 pb-2 text-blue-600 dark:text-indigo-400">BookingsLocode.zip</span>
        <div class="count mt-1 text-gray-400 text-sm"></div>
    </div>
</a>
</div>

The `web` template for a ServiceStack application will provide the basic solution structure
with a sample Hello World service. This can be done using the [ServiceStack website](https://servicestack.net) under
[Get Started](https://servicestack.net/start).

Alternatively, templates can be created using the dotnet CLI tool `x`. The dotnet `x` tool can be installed
using the following command:

:::sh
dotnet tool install --global x
:::

Once installed, a new `web` template can be created using:

:::sh
x new web MyProjectName
:::

### Mix in a database and AutoQuery

We can use the dotnet `x` tool to `mix` in specific database support and AutoQuery quickly using the command run from the project directory.

:::sh
x mix sqlite autoquery
:::

::: tip
Replace `sqlite` with `postgres`, `sqlserver`, or `mysql` or other RDBMS providers
:::

This command will create two files, `Configure.Db.cs` and `Configure.AutoQuery.cs` and install required NuGet dependencies into the AppHost (BookingsLocode in the link above) project.

### Bookings table

With our App now setup to use SQLite & AutoQuery, we'll define our `Booking` table where our data will be stored in:

```csharp
public class Booking
{
    [AutoIncrement]
    public int Id { get; set; }
    public string Name { get; set; }
    public RoomType RoomType { get; set; }
    public int RoomNumber { get; set; }
    public DateTime BookingStartDate { get; set; }
    public DateTime? BookingEndDate { get; set; }
    public decimal Cost { get; set; }
    public string Notes { get; set; }
    public bool? Cancelled { get; set; }
}

public enum RoomType
{
    Single,
    Double,
    Queen,
    Twin,
    Suite,
}
```

With our table schema defined in code, we can use OrmLite to create the table for us if it doesn't already exist,
which we do in the mix generated `Configure.Db.cs` where our SQLite connection is defined, using
`CreateTableIfNotExists()` to create the `Booking` table and populate it with Seed data when it's first created:

```csharp
public class ConfigureDb : IHostingStartup
{
    public void Configure(IWebHostBuilder builder) => builder
        .ConfigureServices((context, services) => {
            services.AddSingleton<IDbConnectionFactory>(new OrmLiteConnectionFactory(
                context.Configuration.GetConnectionString("DefaultConnection")
                ?? ":memory:",
                SqliteDialect.Provider));
        })
        // Create non-existing Table and add Seed Data Example
        .ConfigureAppHost(appHost => {
            using var db = appHost.Resolve<IDbConnectionFactory>().Open();
            if (db.CreateTableIfNotExists<Booking>())
            {
                // Seed data
                db.Insert(new Booking {
                    Name = "Test",
                    Cost = 123,
                    RoomNumber = 321,
                    RoomType = RoomType.Queen,
                    Notes = "Testing more",
                    BookingStartDate = new DateTime(2022, 1, 1),
                    BookingEndDate = new DateTime(2022, 1, 5)
                });
            }
        });
}
```

This configures our App's database ready for use, but we still don't have any AutoQuery APIs using them defined.

## AutoQuery APIs

To create an [AutoQuery API](/autoquery/rdbms) to query our `Booking` RDBMS table, our 
Request DTO just needs to inherit `QueryDb<Table>` with `Booking` table they want the API to query:

```csharp
public class QueryBookings : QueryDb<Booking> {}
```

This empty Request DTO alone is all it takes to create an AutoQuery API that can query each `Booking` column using 
any of the [Implicit Conventions](/autoquery/rdbms#implicit-conventions) registered in the
`AutoQueryFeature` plugin, e.g:

 - https://vue-vite-api.jamstacks.net/api/QueryBookings?Ids=1,2,3

However, to aid in the discovery of popular Booking table queries and make them easily accessible to all of ServiceStack's
[Typed Service Clients](/add-servicestack-reference) or [gRPC Clients](/grpc/)
it's recommended to formalize queries you want to make available by adding typed properties to the Request DTO, e.g: 

```csharp
public class QueryBookings : QueryDb<Booking> 
{
    public int[] Ids { get; set; }
    //...
}
```

Where they can also be consumed by every Service Client with an end-to-end Typed API, e.g: 

```csharp
// C#
var client = new JsonApiClient("https://vue-vite-api.jamstacks.net");
var api = await client.ApiAsync(new QueryBookings { Ids = new[] { 1,2,3 }));
```

TypeScript Example:

```ts
// TypeScript
let client = new JsonServiceClient("https://vue-vite-api.jamstacks.net")
let api = await client.api(new QueryBookings({ Ids: [1,2,3] }))
```

### User-defined Routes

As AutoQuery APIs are themselves normal ServiceStack APIs they benefit from the entire customizability and ecosystem 
available to ServiceStack APIs, like [Routing](/routing) where the API can be made available 
under custom user-defined using the `[Route]` attribute:

```csharp
[Route("/bookings")]
public class QueryBookings : QueryDb<Booking> 
{
    public int[] Ids { get; set; }
}
```

To also make the `QueryBookings` API available from the `/bookings` path, e.g:

- https://vue-vite-api.jamstacks.net/bookings?Ids=1,2,3

### AutoQuery CRUD APIs

To enable Auto CRUD behavior on your Table your Request DTOs can implement any of the following interfaces to create 
APIs with its respective CRUD behavior:

- `ICreateDb<Table>` - Insert a new Table row
- `IUpdateDb<Table>` - Fully Update an existing Table row
- `IPatchDb<Table>` - Partially update an existing Table row
- `IDeleteDb<Table>` - Delete an existing Table row

The Create and Update Request DTOs properties define which columns are updatable from the API: 

```csharp
public class CreateBooking
    : ICreateDb<Booking>, IReturn<IdResponse>
{
    public string Name { get; set; }
    public RoomType RoomType { get; set; }
    public int RoomNumber { get; set; }
    public DateTime BookingStartDate { get; set; }
    public DateTime? BookingEndDate { get; set; }
    public decimal Cost { get; set; }
    public string Notes { get; set; }
}

public class UpdateBooking
    : IPatchDb<Booking>, IReturn<IdResponse>
{
    public int Id { get; set; }
    public string Name { get; set; }
    public RoomType? RoomType { get; set; }
    public int? RoomNumber { get; set; }
    public DateTime? BookingStartDate { get; set; }
    public DateTime? BookingEndDate { get; set; }
    public decimal? Cost { get; set; }
    public bool? Cancelled { get; set; }
    public string Notes { get; set; }
}
```

Only a single Update DTO needs to be implemented to enable Update functionality in Locode. If `IPatchDb<Table>` is
implemented will use it to only update modified fields, whereas if only `IUpdateDb<Table>` is implemented, Locode needs
to send all fields to perform a full update.
If you have [AutoQuery CRUD Events](/autoquery/audit-log) enabled it's recommended to use
`IPatchDb<Table>` for the audit logs to only capture which fields were updated.

To enable delete functionality in Locode create a Request DTO that implements `IDeleteDb<Table>` with the primary key
of the table:

```csharp
public class DeleteBooking : IDeleteDb<Booking>, IReturnVoid
{
    public int Id { get; set; }
}
```

Although not used by Locode, Delete APIs supports the same querying behavior as AutoQuery APIs where you could enable 
create an API that supports multiple and batch deletes with the fields you want to delete by, e.g:

```csharp
public class DeleteBookings : IDeleteDb<Booking>, IReturnVoid
{
    public int[]? Ids { get; set; }
    public bool? Cancelled { get; set; }
}
```

Locode is a capability-based UI that only enables functionality for CRUD APIs that exist and the currently authenticated 
user has access to. As these public APIs don't have any auth restrictions applied to them, they can be used immediately
by non-authenticated users without signing in to query, insert, update and delete from the `Booking` Table:

![](/img/pages/locode/code-first-bookings-mvp.png)

Clicking on our `Booking` services on the left-hand menu utilizes the `QueryBooking` AutoQuery API, we can see the test 
seed data that was populated.

![](/img/pages/locode/code-first-bookings-mvp-2.png)

Using the **New Booking** button gives us a metadata driven Form IO derived from the properties of the `CreateBooking` Request DTO:

![](/img/pages/locode/code-first-bookings-mvp-3.png)

This form also allows editing existing bookings using the Edit button in the first column given its functionality is enabled 
with the application having the `IPatch<Booking>` API defined.

![](/img/pages/locode/code-first-bookings-mvp-4.png)

## POCO References

When it can be inferred Locode automatically detects and linkify [POCO references](/ormlite/reference-support) for easy navigation which is used a lot in https://talent.locode.dev like navigating to a Job's [Job Applications](https://talent.locode.dev/locode/QueryJobApplication):

[![](/img/pages/locode/talent/job-application-references.png)](https://talent.locode.dev/locode/QueryJobApplication)

defined by its [POCO References](https://github.com/NetCoreApps/TalentBlazor/blob/ff6fd961f49141e617fef37b85240af04295359a/TalentBlazor.ServiceModel/Talent.cs#L87):


```csharp
public class JobApplication : AuditBase
{
    [AutoIncrement]
    public int Id { get; set; }

    [References(typeof(Job))]
    public int JobId { get; set; }

    [References(typeof(Contact))]
    public int ContactId { get; set; }

    [Reference]
    public Contact Applicant { get; set; }
    //...
}
```

### Navigating Child References

The references support also allows adding related records by navigating to the child relation then adding the child record where it will preserve and pre-populate the parent id as seen when navigating to a Job's Applications:

```csharp
public class Job : AuditBase
{
    //...
    public List<JobApplication> Applications { get; set; } = new();
}
```

Where it will pre-populate the **Job Id** reference making it easy to add multiple **1:Many** Job Applications:

![](/img/pages/locode/talent/job-job-application-reference.png)


Checkout [Talent.cs](https://github.com/NetCoreApps/TalentBlazor/blob/main/TalentBlazor.ServiceModel/Talent.cs) DTOs for more Reference examples.


## Customizing Locode App

We've walked through a simple example of how to create CRUD APIs for our `Booking` RDBMS table which Locode uses
to power its instant CRUD UI letting your App users start managing its data immediately. 

This touches on some basic functionality to get started in Locode, next we'll explore its declarative dev model
with the different ways you can annotate your services and data model to customize its behavior & appearance and
enhance it with additional functionality using the available composable built-in [declarative C# attributes](/locode/declarative).


# Declarative Dev Model using Attributes
Source: https://docs.servicestack.net/locode/declarative

A significant amount of behavior, functionality and customization of APIs and DTOs can be achieved declaratively
through C# Attributes by annotating C# API Types and Data Models with the extensive functionality available in ServiceStack's Attributes.

This declarative expressiveness also extends to [UI Attributes](#ui-metadata-attributes) that can customize the behavior and appearance of 
Form UIs and formatted tabular resultsets, whose customizations are reused across all ServiceStack Auto UIs and Component libraries, including:

 - [Locode](https://servicestack.net/locode)
 - [API Explorer](/api-explorer)
 - [Vue Tailwind Components](/vue/)
 - [Blazor Tailwind Components](/templates/blazor-components)

A great way to get a quick overview of what annotated DTOs looks like in practice is to browse the DTOs of Locode's
Demos which uses declarative attributes extensively to achieve its customized behavior where you'll be able to 
test the cause & effect of different attributes against their Live Demos or by downloading and running a locally modified copy. 

### Talent Blazor - [talent.locode.dev](https://talent.locode.dev) - [download.zip](https://github.com/NetCoreApps/TalentBlazor/archive/refs/heads/main.zip)

 - [Talent.cs](https://github.com/NetCoreApps/TalentBlazor/blob/main/TalentBlazor.ServiceModel/Talent.cs)

Talent Blazor is a good resource showing how to make use of [Audit CRUD Events](/autoquery/audit-log)
where every change is captured in an Executable Crud Audit Event Log and
[AutoApply Behaviors](/autoquery/crud#apply-generic-crud-behaviors) to change the behavior of
Delete APIs to implement "Soft Deletes".

### Chinook - [chinook.locode.dev](https://chinook.locode.dev) - [download.zip](https://github.com/NetCoreApps/Chinook/archive/refs/heads/main.zip)

 - [Types/Models.cs](https://github.com/NetCoreApps/Chinook/blob/main/Chinook.ServiceModel/Types/Models.cs)
 - [Media.cs](https://github.com/NetCoreApps/Chinook/blob/main/Chinook.ServiceModel/Media.cs)
 - [Store.cs](https://github.com/NetCoreApps/Chinook/blob/main/Chinook.ServiceModel/Store.cs)

Chinook is a good simple Code-First example that's primarily focused on creating a customized UI in Locode. 

### Northwind Auto - [northwind.locode.dev](https://northwind.locode.dev) - [download.zip](https://github.com/NetCoreApps/NorthwindAuto/archive/refs/heads/master.zip)

 - [Configure.AppHost.cs](https://github.com/NetCoreApps/NorthwindAuto/blob/master/Configure.AppHost.cs)

Whilst Northwind is a [Database-First](/locode/database-first) example, it still has access to the same attributes but are 
instead [dynamically added at runtime](/locode/database-first#modifying-dynamic-types-at-runtime).

## Overview

Annotating APIs and Data Models is the primary way of enlisting existing functionality in ServiceStack where most of the
functionality can be broadly grouped into customizing how Data Models map to RDBMS tables and make use of RDBMS features,
customizing API behavior and annotating & documenting APIs to customize their appearance in UIs.

## Data Model Attributes

These Data Model attributes can be used to utilize RDBMS features & customize how Types are mapped to RDBMS Tables.

### Table Data Model Attributes

These OrmLite attributes can be used to customize how C# Types configure & map to RDBMS Tables.

| Attribute             | Description                                              |
|-----------------------|----------------------------------------------------------|
| `[Alias]`             | Map C# Type Name to an alternative RDBMS Table           |
| `[PostCreateTable]`   | Run Custom SQL immediately after RDBMS table is created  |
| `[PostDropTable]`     | Run Custom SQL immediately after RDBMS table is dropped  |
| `[PreCreateTable]`    | Run Custom SQL immediately before RDBMS table is created |
| `[PostDropTable]`     | Run Custom SQL immediately before RDBMS table is dropped |
| `[Schema]`            | Define which RDBMS Schema Data Model belongs to          |
| `[UniqueConstraint]`  | Define a unique multi column RDBMS column constraint     |

### Column Property Attributes

These OrmLite attributes are used to customize how C# Properties configure & map to RDBMS Columns.

| Attribute           | Description                                                                                         |
|---------------------|-----------------------------------------------------------------------------------------------------|
| `[Alias]`           | Map C# Property Name to an alternative RDBMS Column name                                            |
| `[AutoId]`          | Auto populate Property with a unique RDBMS generated UUID if supported otherwise with a new C# GUID |
| `[AutoIncrement]`   | Auto populate Primary Key Property with an RDBMS generated Auto Incrementing Integer                |
| `[BelongTo]`        | Populate property from ambiguous column name in the specified joined table type                     |
| `[CheckConstraint]` | Create an Composite RDBMS Index and optional Unique constraint                                      |
| `[Compute]`         | Define that a Property maps to a computed RDBMS column                                              |
| `[Computed]`        | Ignore calculated C# Property from being persisted in RDBMS Table                                   |
| `[CustomField]`     | Create RDBMS using Custom SQL Data Type                                                             |
| `[CustomSelect]`    | Populate property with Custom SELECT expression                                                     |
| `[CustomInsert]`    | Populate INSERT parameter with Custom SQL expression                                                |
| `[CustomUpdate]`    | Populate UPDATE parameter with Custom SQL expression                                                |
| `[DecimalLength]`   | Create RDBMS Column with specified decimal scale & precision                                        |
| `[Default]`         | Create RDBMS Column definition with specified default value                                         |
| `[EnumAsChar]`      | Save Enum value as single char in RDBMS column                                                      |
| `[EnumAsInt]`       | Save Enum integer value in RDBMS column                                                             |
| `[ForeignKey]`      | Define an RDBMS Foreign Key Relationship                                                            |
| `[Ignore]`          | Ignore property from consideration as an RDBMS column                                               |
| `[IgnoreOnUpdate]`  | Ignore this property in UPDATE statements                                                           |
| `[IgnoreOnInsert]`  | Ignore this property in INSERT statements                                                           |
| `[Index]`           | Create an RDBMS Column Index                                                                        |
| `[PrimaryKey]`      | Treat this property is the Primary Key of the table                                                 |
| `[Reference]`       | Define this property as containing a foreign POCO Complex Type Reference                            |
| `[ReferenceField]`  | Populate with a field from a foreign table in AutoQuery and Load* APIs                              |
| `[References]`      | Document a reference to an external Type, used to create simple Foreign Key references              |
| `[Required]`        | Create NOT NULL Column Definitions in RDBMS Create Table statements                                 |
| `[ReturnOnInsert]`  | Indicate property should be included in returning/output clause of SQL INSERT Statements            |
| `[RowVersion]`      | Treat property as an automatically incremented RDBMS Row Version                                    |
| `[StringLength]`    | Define the RDBMS Column Definition variable character length                                        |
| `[Unique]`          | Define a unique RDBMS column constraint                                                             |

In addition to these generic Data Model attributes that work with any [supported RDBMS](/ormlite/installation),
there are also [PostgreSQL-specific](/ormlite/postgres-features) and 
[SQL Server specific](/ormlite/sql-server-features) attributes to unlock their respective 
RDBMS-specific features. 

## API Attributes

Use the Attributes to customize the functionality, behavior & accessibility of your APIs, and they're available endpoints.

### Custom Serialization

| Attribute            | Description                                                                          |
|----------------------|--------------------------------------------------------------------------------------|
| `[DataContract]`     | Define Type as DTO Type and change serialization to opt-in `[DataMember]` properties |
| `[DataMember]`       | Include property in Serialization and optionally change serializable Name and Order  |
| `[Flags]`            | Serialize an Enum's integer value instead                                            |
| `[IgnoreDataMember]` | Ignore property from serialization                                                   |

### Generic API Behavior

| Attribute    | Description                                                                     |
|--------------|---------------------------------------------------------------------------------|
| `[Exclude]`  | Instruct which APIs should be excluded from metadata & specified endpoints      |
| `[Route]`    | Make this API available on the specified user-defined route                     |
| `[Restrict]` | Restrict the accessibility of a service and its visibility in Metadata services |
| `[UploadTo]` | Specify which File Upload location should be used to manage these file uploads  |

More information on usage of these attributes can be found in 
[Routing ](/routing) Docs, 
[Restricting Services](/auth/restricting-services) and
[Managed File Uploads](/locode/files-overview) Docs.

### AutoQuery Attributes

These attributes can be used to customize the querying behavior of [AutoQuery APIs](/autoquery/rdbms). 

| Attribute        | Description                                                          |
|------------------|----------------------------------------------------------------------|
| `[QueryDb]`      | Change the default querying behaviour of AutoQuery filter properties |
| `[QueryDbField]` | Define field to use a custom AutoQuery filter                        |

### AutoQuery CRUD Attributes

Use these attributes to customize the behavior of [AutoQuery CRUD APIs](/autoquery/crud).

| Attribute        | Description                                                          |
|------------------|----------------------------------------------------------------------|
| `[AutoApply]`    | Apply built-in composite generic behavior                            |
| `[AutoPopulate]` | Populate data models with generic user & system info                 |
| `[AutoFilter]`   | Apply additional pre-configured filters to AutoQuery APIs            |
| `[AutoMap]`      | Map System Input properties to Data Model fields                     |
| `[AutoDefault]`  | Specify to fallback default values when not provided                 |
| `[AutoIgnore]`   | Ignore mapping Request DTO property to Data Model                    |
| `[AutoUpdate]`   | Change the update behavior to only update non-default values         |

### Type Validation Attributes

As AutoQuery APIs typically don't have a Service implementation, the recommended way to protect access to them is 
to use the declarative [Type Validators](/declarative-validation#type-validators) 
below as they're decoupled from any implementation and can be safely annotated on Request DTOs without requiring any 
implementation dependencies.

| Attribute                   | Description                                                            |
|-----------------------------|------------------------------------------------------------------------|
| `[ValidateRequest]`         | Validate Type against a custom Validator expression                    |
| `[ValidateIsAuthenticated]` | Protect access to this API to Authenticated Users only                 |
| `[ValidateIsAdmin]`         | Protect access to this API to Admin Users only                         |
| `[ValidateHasPermission]`   | Protect access to this API to only Users assigned with ALL Permissions |
| `[ValidateHasRole]`         | Protect access to this API to only Users assigned with ALL Roles       |

### Property Validation Attributes

The [Declarative Validation](/declarative-validation#type-validators) attributes enable
an alternative way of defining [Fluent Validation rules](/validation) on properties.

| Attribute                      | Description                                                             |
|--------------------------------|-------------------------------------------------------------------------|
| `[Validate]`                   | Validate property against custom Validator expression                   |
| `[ValidateCreditCard]`         | Validate property against Fluent Validation CreditCardValidator         |
| `[ValidateEmail]`              | Validate property against Fluent's AspNetCoreCompatibleEmailValidator   |
| `[ValidateEmpty]`              | Validate property against Fluent Validation EmptyValidator              |
| `[ValidateEqual]`              | Validate property against Fluent Validation EqualValidator              |
| `[ValidateExactLength]`        | Validate property against Fluent Validation ExactLengthValidator        |
| `[ValidateExclusiveBetween]`   | Validate property against Fluent Validation ExclusiveBetweenValidator   |
| `[ValidateGreaterThan]`        | Validate property against Fluent Validation GreaterThanValidator        |
| `[ValidateGreaterThanOrEqual]` | Validate property against Fluent Validation GreaterThanOrEqualValidator |
| `[ValidateInclusiveBetween]`   | Validate property against Fluent Validation InclusiveBetweenValidator   |
| `[ValidateLength]`             | Validate property against Fluent Validation LengthValidator             |
| `[ValidateLessThan]`           | Validate property against Fluent Validation LessThanValidator           |
| `[ValidateLessThanOrEqual]`    | Validate property against Fluent Validation LessThanOrEqualValidator    |
| `[ValidateMaximumLength]`      | Validate property against Fluent Validation MaximumLengthValidator      |
| `[ValidateMinimumLength]`      | Validate property against Fluent Validation MinimumLengthValidator      |
| `[ValidateNotEmpty]`           | Validate property against Fluent Validation NotEmptyValidator           |
| `[ValidateNotEqual]`           | Validate property against Fluent Validation NotEqualValidator           |
| `[ValidateNotNull]`            | Validate property against Fluent Validation NotNullValidator            |
| `[ValidateNull]`               | Validate property against Fluent Validation NullValidator               |
| `[ValidateRegularExpression]`  | Validate property against Fluent Validation RegularExpressionValidator  |
| `[ValidateScalePrecision]`     | Validate property against Fluent Validation ScalePrecisionValidator     |

### Authentication & Authorization Restrictions

These [Request Filter Attributes](/filter-attributes) applied to Service Implementation classes
apply to all Service method implementations contained within them.

| Attribute                 | Description                                                                          |
|---------------------------|--------------------------------------------------------------------------------------|
| `[Authenticate]`          | Protect access to this API to Authenticated Users only                               |
| `[RequiredClaim]`         | Protect access to this API to only Authenticated Users with specified Claim          |
| `[RequiredPermission]`    | Protect access to this API to only Authenticated Users assigned with ALL Permissions |
| `[RequiredRole]`          | Protect access to this API to only Authenticated Users assigned with ALL Roles       |
| `[RequiresAnyPermission]` | Protect access to this API to Authenticated Users assigned with ANY Permissions      |
| `[RequiresAnyRole]`       | Protect access to this API to Authenticated Users assigned with ANY Roles            |

Refer to [Authentication Attribute docs](/auth/authentication-and-authorization#the-authenticate-attribute) for more info.

## UI & Metadata Attributes

These attributes can be used to document and annotate APIs which will customize how they're documented and appear in
Metadata services, [Add ServiceStack Reference](/add-servicestack-reference)
generated DTOs and metadata driven, capability-based Auto UIs like
[API Explorer](/api-explorer),
[Locode](https://servicestack.net/locode) and
[Swagger UI](/openapi).

### Annotate APIs

Whilst they can change how they appear and are accessed by external clients, it's important to note that they 
do not have any impact on the behavior & functionality of back-end APIs, i.e. your preferred 
[validation method](/validation) is still required in order to enforce validation.

| Attribute              | Description                                                                      |
|------------------------|----------------------------------------------------------------------------------|
| `[Api]`                | Document a short description for an API Type                                     |
| `[ApiMember]`          | Document a short description for an API Property                                 |
| `[ApiResponse]`        | Document potential API Responses this API could return                           |
| `[ApiAllowableValues]` | Document the allowable values for an API Property                                |
| `[Description]`        | Annotate any Type, Property or Enum with a textual description                   |
| `[ExcludeMetadata]`    | Exclude API from all Metadata Services                                           |
| `[Id]`                 | Uniquely identify C# Types and properties with a unique integer in gRPC Services |
| `[Meta]`               | Decorate any type or property with custom metadata                               |
| `[Meta]`               | Decorate any type or property with custom metadata                               |
| `[Range]`              | Document the allowable min and max range for this property                       |
| `[Required]`           | Document that this is a required property                                        |
| `[Notes]`              | Document a longer form description about a Type                                  |

### Customize UI

These UI attributes can be used to customize Auto UI Form fields and how search results are rendered.

### Result Formatters

Refer to the [Formatters docs](/locode/formatters) for more info on how to use formatters to customize search results. 

| Attribute            | Description                                                                  |
|----------------------|------------------------------------------------------------------------------|
| `[Intl]`             | Configure result field to use JavaScript's Intl formatter                    |
| `[IntlNumber]`       | Configure result field to use JavaScript's Intl.NumberFormat formatter       |
| `[IntlDateTime]`     | Configure result field to use JavaScript's Intl.DateTimeFormat formatter     |
| `[IntlRelativeTime]` | Configure result field to use JavaScript's Intl.RelativeTimeFormat formatter |
| `[Ref]`              | Configure Lookup fields to use UI References to external Data Models         |

### Custom Fields and Inputs

These attributes can be used to customize how fields and HTML Input controls in Auto UIs like [Locode](https://servicestack.net/locode)
and [API Explorer](/api-explorer).

| Attribute       | Description                                                               |
|-----------------|---------------------------------------------------------------------------|
| `[Input]`       | Customize the HTML Input control for a Property in Auto Form UIs          |
| `[Field]`       | Customize the HTML Input control and Form Field CSS for a Type's Property |
| `[FieldCss]`    | Customize a Property Form Field CSS                                       |
| `[ExplorerCss]` | Customize the Form and Field CSS in API Explorer                          |
| `[LocodeCss]`   | Customize the Form and Field CSS in Locode                                |

We'll go through some examples to explore how they can be used to customize Locode and API Explorer UIs.

From the `CreateJob` Request DTO we can already see that Locode will use the most appropriate HTML Input for the specific
data type, e.g. a `<input type=number>` for integers, a `<input type=date>` for Date Types and a `<select>` dropdown
for properties with finite values like Enums.

We can also further customize each field with the `[Input]` attribute where we can change to use a `<textarea>` for 
large text fields which we can pair with the `[FieldCss]` attribute to change the width of its encapsulating field
using [TailwindCss Grid classes](https://tailwindcss.com/docs/grid-column#spanning-columns) to change its width
and center its label:

```csharp
public class CreateJob : ICreateDb<Job>, IReturn<Job>
{
    public string Title { get; set; }

    [ValidateGreaterThan(0)]
    public int SalaryRangeLower { get; set; }
    [ValidateGreaterThan(0)]
    public int SalaryRangeUpper { get; set; }
    [Input(Type = "textarea"), FieldCss(Field = "col-span-12 text-center")]
    public string Description { get; set; }

    public EmploymentType EmploymentType { get; set; }
    public string Company { get; set; }
    public string Location { get; set; }

    public DateTime Closing { get; set; }
}
```

Which renders our preferred responsive form layout:

[![](/img/pages/locode/talent/create-job.png)](https://talent.locode.dev/locode/QueryJob?new=true)

### Field

The `[Field]` attribute is an alternative way to define both `[Input]` and `[FieldCss]` attributes on **Types** which
is especially useful when you don't have the property on the Request DTO you want to define because it's in a base class,
in which case you can use `[Field]` on the Request DTO:

```csharp
[Field(nameof(Description), Type = "textarea", FieldCss="col-span-12 text-center")]
public class CreateJob : JobBase, ICreateDb<Job>, IReturn<Job> {}
```

### Hiding Input Fields

Since the UIs only shows properties defined on Create and Update CRUD DTOs, not defining them will prevent them from
being included in the form. However, in the rare cases where you still want them defined on the Typed back-end API but
hidden from the UI, you can use `Ignore=true`:

```csharp
public class UpdateJob : IPatchDb<Job>, IReturn<Job> 
{
    [Input(Ignore = true)]
    public string Description { get; set; }
    //...
}

[Field(nameof(Description), Ignore = true)]
public class UpdateJob : JobBase, IPatchDb<Job>, IReturn<Job> {}
```

This will completely exclude them from the UI, if you instead want them as an `<input type=hidden>` you can use:

```csharp
[Input(Type="hidden")]
public string Description { get; set; }
```

### Custom Form CSS

The high-level `[LocodeCss]` attribute can be used to change the entire Form layout instead where you'll be able to
change the default Form, FieldSet and Field CSS classes, e.g:

```csharp
[LocodeCss(Field="col-span-12 sm:col-span-6", Fieldset = "grid grid-cols-6 gap-8", 
           Form = "border border-indigo-500 overflow-hidden max-w-screen-lg")]
[Field(nameof(BookingEndDate), LabelCss = "text-gray-800", InputCss = "bg-gray-100")]
[Field(nameof(Notes), Type = "textarea", FieldCss="col-span-12 text-center", InputCss = "bg-gray-100")]
public class UpdateBooking : IPatchDb<Booking>, IReturn<IdResponse>
{
    public int Id { get; set; }
    [ValidateNotNull]
    public string? Name { get; set; }
    public RoomType? RoomType { get; set; }
    [ValidateGreaterThan(0)]
    public int? RoomNumber { get; set; }
    [ValidateGreaterThan(0), AllowReset]
    public decimal? Cost { get; set; }
    public DateTime? BookingStartDate { get; set; }
    public DateTime? BookingEndDate { get; set; }
    public string? Notes { get; set; }
    public bool? Cancelled { get; set; }
}
```

Renders our custom Form layout:

![](/img/pages/locode/locode-css.png)

These changes only applies to the Form when viewed in Locode, to change the Form in API Explorer use `[ExplorerCss]`: 

```csharp
[ExplorerCss(Field="col-span-12 sm:col-span-6", Fieldset = "grid grid-cols-6 gap-8", 
             Form = "border border-indigo-500 overflow-hidden max-w-screen-lg")]
```

When more customization is needed checkout how you can replace the entire Form in the [Custom Forms docs](/locode/custom-forms).


# Programmatic Dev Model
Source: https://docs.servicestack.net/locode/programmatic

## Customizing UI 

Much of the configurable parts of the UIs can be customized in code, for a preview of the potential customizations 
available here's are the defaults the UIs are configured with which you can change with `ConfigurePlugin<UiFeature>`: 

```csharp
ConfigurePlugin<UiFeature>(feature => {
    feature.Info.HideTags = new List<string> { TagNames.Auth };
    feature.Info.BrandIcon = Svg.ImageUri(Svg.GetDataUri(Svg.Logos.ServiceStack, "#000000"));
    feature.Info.Theme = new ThemeInfo {
        Form = "shadow overflow-hidden sm:rounded-md bg-white",
        ModelIcon = Svg.ImageSvg(Svg.Create(Svg.Body.Table)),
    };
    feature.Info.Locode = new() {
        Css = new ApiCss {
            Form = "max-w-screen-2xl",
            Fieldset = "grid grid-cols-12 gap-6",
            Field = "col-span-12 lg:col-span-6 xl:col-span-4",
        },
        Tags = new AppTags {
            Default = "Tables",
            Other = "other",
        },
        MaxFieldLength = 150,
        MaxNestedFields = 2,
        MaxNestedFieldLength = 30,
    };
    feature.Info.Explorer = new() {
        Css = new ApiCss {
            Form = "max-w-screen-md",
            Fieldset = "grid grid-cols-12 gap-6",
            Field = "col-span-12 sm:col-span-6",
        },
        Tags = new AppTags {
            Default = "APIs",
            Other = "other",
        },
    };
    feature.Info.DefaultFormats = new ApiFormat {
        AssumeUtc = true,
        Date = new Intl(IntlFormat.DateTime) { Date = DateStyle.Medium }.ToFormat(),
    };
    feature.Info.AdminLinks = new() {
        new LinkInfo { Id = "", Label = "Dashboard", Icon = Svg.ImageSvg(Svg.Create(Svg.Body.Home)) },
    };
});
```

These defaults can also be individually changed by `[LocodeCss]` and `[ExplorerCss]` to [Customize the Form CSS](/locode/declarative.html#custom-form-css)
for specific AutoQuery CRUD Operations.

## Customizing Inputs and Fields in Code

All UI attributes are used to populate the metadata model for your App which is used to power their metadata-driven UIs.
An alternative way to populate this metadata is to use `ConfigureOperation<RequestDto>` to populate the metadata directly,
e.g. here's an example of how we can customize the `<input>` in our custom `Register` **FormLayout**:

```csharp
appHost.ConfigureOperation<Register>(op => op.FormLayout = new()
{
    Input.For<Register>(x => x.DisplayName, x => x.Help = "Your first and last name"),
    Input.For<Register>(x => x.Email, x => x.Type = Input.Types.Email),
    Input.For<Register>(x => x.Password, x => x.Type = Input.Types.Password),
    Input.For<Register>(x => x.ConfirmPassword, x => x.Type = Input.Types.Password),
});
```

Whilst being just a flattened list of inputs we're still able to customize the form layout by using the Typed 
`FieldsPerRow()` helper method:

```csharp
Plugins.Add(new AdminUsersFeature {
    // Add Custom Fields to Create/Edit User Forms
    FormLayout = new() {
        Input.For<UserAuth>(x => x.Email, x => x.Type = Input.Types.Email),
        Input.For<UserAuth>(x => x.UserName),
        Input.For<UserAuth>(x => x.FirstName,    c => c.FieldsPerRow(2)),
        Input.For<UserAuth>(x => x.LastName,     c => c.FieldsPerRow(2)),
        Input.For<UserAuth>(x => x.DisplayName),
        Input.For<UserAuth>(x => x.Company),
        Input.For<UserAuth>(x => x.Address),
        Input.For<UserAuth>(x => x.Address2),
        Input.For<UserAuth>(x => x.City,         c => c.FieldsPerRow(2)),
        Input.For<UserAuth>(x => x.State,        c => c.FieldsPerRow(2)),
        Input.For<UserAuth>(x => x.Country,      c => c.FieldsPerRow(2)),
        Input.For<UserAuth>(x => x.PostalCode,   c => c.FieldsPerRow(2)),
        Input.For<UserAuth>(x => x.PhoneNumber, x => x.Type = Input.Types.Tel),
    }
});
```

Which just simplifies choosing the responsive [TailwindCss grid classes](https://tailwindcss.com/docs/grid-column)
we want, in this case renders **2 fields per row** from the `sm` responsive [Tailwind breakpoint](https://tailwindcss.com/docs/screens) 
by expanding to:

```csharp
Input.For<UserAuth>(x => x.FirstName, c => c.Input.Css.Field = "col-span-12 sm:col-span-6")
```

### Configure Types

In addition to `ConfigureOperation<T>` for customizing the metadata for a single operation, there's also 
`ConfigureType<T>` for customizing the metadata for a single DTO Type and `ConfigureOperations(op => ...)` 
for registering a single lambda to customize the metadata for all Operations and `ConfigureTypes(type => ...)`
to do the same for all DTO Types.

Unlike the AutoGen `TypeFilter` to 
[Modify Dynamic Types at Runtime](/locode/database-first.html#modifying-dynamic-types-at-runtime)
which is only executed for customizing code-gen Types, these metadata APIs can be used for customizing the metadata
of both [Database-First](/locode/database-first) and [Code-First](/locode/code-first) Types.

So if the [Northwind Database-First](https://northwind.locode.dev) and 
[Chinook Code-First](https://chinook.locode.dev) were both configured in the same App, you could use a single lambda
to configure the metadata in both, e.g:

```csharp
var icons = new Dictionary<string, ImageInfo>
{
    [nameof(AppUser)] = Svg.CreateImage(Svg.Body.User),
    [nameof(CrudEvent)] = Svg.CreateImage(Svg.Body.History),
    [nameof(UserAuthDetails)] = Svg.CreateImage(Svg.Body.UserDetails),
    [nameof(UserAuthRole)] = Svg.CreateImage(Svg.Body.UserShield),
  
    // Northwind
    ["Category"] = Svg.CreateImage("<path fill='currentColor' d='M20 5h-9.586L8.707 3.293A.997.997 0 0 0 8 3H4c-1.103 0-2 .897-2 2v14c0 1.103.897 2 2 2h16c1.103 0 2-.897 2-2V7c0-1.103-.897-2-2-2z'/>"),
    //...

    // Chinook
    [nameof(Tracks)] = Svg.CreateImage("<path fill='currentColor' d='M12 3v9.28a4.39 4.39 0 0 0-1.5-.28C8.01 12 6 14.01 6 16.5S8.01 21 10.5 21c2.31 0 4.2-1.75 4.45-4H15V6h4V3h-7z'/>"),
    //...
};

appHost.ConfigureTypes(type => {
    if (icons.TryGetValue(type.Name, out var icon))
        type.Icon = icon;

    if (type.HasNamedConnection("chinook"))
    {
        type.Properties.Each(prop => {
            if (prop.IsPrimaryKey != true && references.TryGetValue(prop.Name, out var refInfo))
                prop.Ref = refInfo;
        });
        
        if (type.Name == nameof(Tracks))
        {
            type.Property(nameof(Tracks.Bytes)).Format = new FormatInfo { Method = FormatMethods.Bytes };
            type.Property(nameof(Tracks.Milliseconds)).Format = new Intl(IntlFormat.DateTime) {
                Minute = DatePart.Digits2,
                Second = DatePart.Digits2,
                FractionalSecondDigits = 3,
            }.ToFormat();
            type.Property(nameof(Tracks.UnitPrice)).Format = new IntlNumber(NumberStyle.Currency) {
                Currency = NumberCurrency.USD
            }.ToFormat();
        }
    }

    switch (type.Name)
    {
        case "Order":
            type.EachProperty(x => x.Name.EndsWith("Date"), x => x.Format = dateFormat);
            type.Property("Freight").Format = currency;
            type.Property("ShipVia").Ref = new() { Model = "Shipper", RefId = "Id", RefLabel = "CompanyName" };
            break;
        case "OrderDetail":
            type.Property("UnitPrice").Format = currency;
            type.Property("Discount").Format = percent;
            break;
        case "Employee":
            type.Property("PhotoPath").Format = new FormatInfo { Method = FormatMethods.IconRounded };
            type.Property("ReportsTo").Ref = new RefInfo { Model = "Employee", RefId = "Id", RefLabel = "LastName" };
            type.ReorderProperty("PhotoPath", before: "Title");
            type.ReorderProperty("ReportsTo", after: "Title");
            break;
        case "EmployeeTerritory":
            type.Property("TerritoryId").Ref = new() { Model = "Territory", RefId = "Id", RefLabel = "TerritoryDescription" };
            break;
        case "Supplier":
        case "Customer":
            type.Property("Phone").Format = new FormatInfo { Method = FormatMethods.LinkPhone };
            type.Property("Fax").Format = new FormatInfo { Method = FormatMethods.LinkPhone };
            break;
    }
});
```

### Typed APIs

One of the benefits of using code to customize inputs is having access to more typed API like `Input.Types.Email`
given they have access to all implementation libraries whereas since 
[ServiceModel DTOs](/physical-project-structure#servicemodel-project) shouldn't reference any 
implementation assemblies they'll need to use the `[Input(Type="email")]` string literal instead, although the Typed API 
can still serve as a reference for the supported input types:

```csharp
public static class Input
{
    public static class Types
    {
        public const string Text = "text";
        public const string Checkbox = "checkbox";
        public const string Color = "color";
        public const string Date = "date";
        public const string DatetimeLocal = "datetime-local";
        public const string Email = "email";
        public const string File = "file";
        public const string Hidden = "hidden";
        public const string Image = "image";
        public const string Month = "month";
        public const string Number = "number";
        public const string Password = "password";
        public const string Radio = "radio";
        public const string Range = "range";
        public const string Reset = "reset";
        public const string Search = "search";
        public const string Submit = "submit";
        public const string Tel = "tel";
        public const string Time = "time";
        public const string Url = "url";
        public const string Week = "week";
        public const string Select = "select";
        public const string Textarea = "textarea";
    }
    //...
}
```

### Input Reference

All Input customizations serializes down to the `InputInfo` Metadata DTO which we can see is able to customize 
most HTML `<input>` attributes to be able to provide a more optimized UX like client-side validation:

```csharp
public class InputInfo : IMeta
{
    public string Id { get; set; }
    public string Name { get; set; }
    public string Type { get; set; }
    public string Value { get; set; }
    public string Placeholder { get; set; }
    public string Help { get; set; }
    public string Label { get; set; }
    public string Title { get; set; }
    public string Size { get; set; }
    public string Pattern { get; set; }
    public bool? ReadOnly { get; set; }
    public bool? Required { get; set; }
    public bool? Disabled { get; set; }
    public string Autocomplete { get; set; }
    public string Autofocus  { get; set; }
    public string Min { get; set; }
    public string Max { get; set; }
    public int? Step { get; set; }
    public int? MinLength { get; set; }
    public int? MaxLength { get; set; }
    public string Accept  { get; set; }
    public string Capture  { get; set; }
    public bool? Multiple { get; set; }
    public string[] AllowableValues { get; set; }
    public KeyValuePair<string,string>[] AllowableEntries { get; set; }
    public string Options  { get; set; }
    public bool? Ignore { get; set; }
    public FieldCss Css { get; set; }
}
```

## Table Relations and Modal Lookups

To provide a great UX-Friendly UI suitable for end users, Locode includes a UI solution for linking related data that
avoids users from having to deal with raw Foreign Key Ids by instead allowing them to select related records using
a rich modal dialog with support for flexible multi column sorting and powerful querying capabilities.

Where possible ServiceStack will populate these **UI references** when their Data Models are defined with OrmLite's [POCO References](/ormlite/reference-support) or follows the `{Model}Id` naming convention for FK Properties, e.g:

```csharp
public class JobApplication : AuditBase
{
    [AutoIncrement]
    public int Id { get; set; }

    // Explicit Reference to Job
    [References(typeof(Job))]
    public int JobId { get; set; }
    
    // Implicit Reference to Contact
    public int ContactId { get; set; } 
    //...
}
```

The effect of which will upgrade the Foreign Key Ids from raw **number** Inputs to use Modal Lookups to search their related tables where
this CRUD API to Create Job Applications:

```csharp
public class CreateJobApplication : ICreateDb<JobApplication>, IReturn<JobApplication>
{
    [ValidateGreaterThan(0)]
    public int JobId { get; set; }
    
    [ValidateGreaterThan(0)]
    public int ContactId { get; set; }
    
    public DateTime AppliedDate { get; set; }
    
    public JobApplicationStatus ApplicationStatus { get; set; }
    
    [Input(Type = "file"), UploadTo("applications")]
    public List<JobApplicationAttachment> Attachments { get; set; }
}
```

Renders this Form that uses Modal Lookups for `JobId` and `ContactId` properties, a **date** control for `AppliedDate` a `<select>` dropdown
for `JobApplicationStatus` Enum and a multiple File Input control for `Attachments`

![](/img/pages/locode/talent/create-job-application-empty.png)

Clicking on the `JobId` field will launch a Modal Lookup searching the `Job` table with multi-column sorting and filtering capabilities:

![](/img/pages/locode/talent/lookup-job.png)

After selecting the related records the lookup fields will be populated with both the first **Text** column of the table and the ForeignKey Id:

![](/img/pages/locode/talent/create-job-application.png)

### Custom UI References

If our FK References doesn't use explicit references, follows the naming reference convention or we just want to override the UI Reference, 
we can explicitly define the UI Reference with the `[Ref]` attribute which in this case will create an Employee Lookup field for the 
`ReportsTo` property:

```csharp
public class Employee
{
    public int Id { get; set; }
    public string FirstName { get; set; }
    public string LastName { get; set; }

    [Ref(Model = nameof(Employee), RefId = nameof(Id), RefLabel = nameof(LastName))]
    public int ReportsTo { get; set; }
    //...
}
```

### Database-First UI References

Implicit UI References are also populated when using a [Database-first](/locode/database-first) approach with Foreign Key columns, table relationships 
and relevant look up tables reflected in the Locode App, as can be seen in in Locode's Northwind example in its
[Product](https://northwind.locode.dev/locode/QueryProducts?edit=1), 
[Order](https://northwind.locode.dev/locode/QueryOrders?edit=10248) and 
[OrderDetails](https://northwind.locode.dev/locode/QueryOrderDetails?edit=10248%2F11) tables.

When the reference can't be inferred we can dynamically add it using AutoQuery's `TypeFilter` by adding the `[Ref]` attribute to the Data Model property:

```csharp
TypeFilter = (type, req) =>
{
    ...
    if (type.Name == "Employee" || type.IsCrudCreateOrUpdate("Employee"))
    {
        ...
        if (type.IsCrud())
        {
            ...
        }
        else if (type.Name == "Employee")
        {
            type.Property("ReportsTo").AddAttribute(
                new RefAttribute { Model = "Employee", RefId = "Id", RefLabel = "LastName" });
        }
    }
}
```

Which has the same behavior as the code-first `[Ref]` attribute in enabling the Employee lookup field for the `ReportsTo` property making it is easy to select the Employee's reporting Manager `Id`:

![](/img/pages/locode/locode-lookup.gif)

When defining UI relationships, `RefModel` determines the Foreign Key Table used in the Model Lookup, `RefId` is the target FK Primary Key whilst 
`RefLabel` specifies which text field to use to better describe the Record.


# Appearance &amp; Branding
Source: https://docs.servicestack.net/locode/branding

The logo at the top left can be changed by configuring the `UiFeature` plugin from your AppHost using `ConfigurePlugin<UiFeature>`.

```csharp
ConfigurePlugin<UiFeature>(feature => 
    feature.Info.BrandIcon = new ImageInfo { Uri = "/logo.svg", Cls = "w-8 h-8 mr-1" });
```

`Uri` is the path of your own logo from the `wwwroot` folder and the `Cls` value is the CSS classes applied to the image.

<div class="not-prose">
<ul class="my-8 grid gap-4 sm:grid-cols-2">
    <li class="rounded-lg m-0 col-span-1 flex flex-col text-center items-center bg-white shadow divide-y divide-gray-200">
        <div class="flex-1 flex flex-col px-4 mt-4">
            <div class="mt-4 p-0 text-xl font-medium text-gray-500">Default</div>
            <div class="rounded-lg focus-within:ring-2 focus-within:ring-offset-2 focus-within:ring-offset-gray-100 focus-within:ring-indigo-500 overflow-hidden">
                <img src="/img/pages/locode/database-first-northwind-branding1.png" alt="">
            </div>
        </div>
    </li>
    <li class="rounded-lg m-0 col-span-1 flex flex-col text-center items-center bg-white shadow divide-y divide-gray-200">
        <div class="flex-1 flex flex-col px-4 mt-4">
            <div class="mt-4 p-0 text-xl font-medium text-gray-500">Custom branding</div>
            <div class="rounded-lg focus-within:ring-2 focus-within:ring-offset-2 focus-within:ring-offset-gray-100 focus-within:ring-indigo-500 overflow-hidden">
                <img src="/img/pages/locode/database-first-northwind-branding2.png" alt="">
            </div>
        </div>
    </li>
</ul>
</div>

### Custom Brand Component

For even greater flexibility you can also replace the entire [Brand.mjs component](/locode/custom-overview#custom-app-example) by
creating a local `Brand` component in 
[/wwwroot/js/components/Brand.mjs](https://github.com/ServiceStack/ServiceStack/blob/main/ServiceStack.Blazor/tests/ServiceStack.Blazor.Bootstrap.Tests/Server/js/components/Brand.mjs) which the Blazor WASM template does with:

```js
const Brand = {
    template:/*html*/`
    <div class="flex items-center flex-shrink-0 max-w-sidebar">
        <a title="My App" v-href="{ $page:'' }"
           class="text-2xl whitespace-nowrap overflow-x-hidden flex items-center">
           <svg xmlns="http://www.w3.org/2000/svg" class="w-8 h-8 ml-1 mr-2" viewBox="0 0 24 24">
               <path d="M23.834 8.101a13.912 13.912 0 0 1-13.643 11.72a10.105 10.105 0 0 1-1.994-.12a6.111 6.111 0 0 1-5.082-5.761a5.934 5.934 0 0 1 
               11.867-.084c.025.983-.401 1.846-1.277 1.871c-.936 0-1.374-.668-1.374-1.567v-2.5a1.531 1.531 0 0 0-1.52-1.533H8.715a3.648 3.648 0 1 0 
               2.695 6.08l.073-.11l.074.121a2.58 2.58 0 0 0 2.2 1.048a2.909 2.909 0 0 0 2.695-3.04a7.912 7.912 0 0 0-.217-1.933a7.404 7.404 0 0 0-14.64 
               1.603a7.497 7.497 0 0 0 7.308 7.405s.549.05 1.167.035a15.803 15.803 0 0 0 8.475-2.528c.036-.025.072.025.048.061a12.44 12.44 0 0 1-9.69 
               3.963a8.744 8.744 0 0 1-8.9-8.972a9.049 9.049 0 0 1 3.635-7.247a8.863 8.863 0 0 1 5.229-1.726h2.813a7.915 7.915 0 0 0 5.839-2.578a.11.11 
               0 0 1 .059-.034a.112.112 0 0 1 .12.053a.113.113 0 0 1 .015.067a7.934 7.934 0 0 1-1.227 3.549a.107.107 0 0 0-.014.06a.11.11 0 0 0 
               .073.095a.109.109 0 0 0 .062.004a8.505 8.505 0 0 0 5.913-4.876a.155.155 0 0 1 .055-.053a.15.15 0 0 1 .147 0a.153.153 0 0 1 .054.053A10.779 
               10.779 0 0 1 23.834 8.1zM8.895 11.628a2.188 2.188 0 1 0 2.188 2.188v-2.042a.158.158 0 0 0-.15-.15z" fill="#5C2D91"/>
            </svg>
           My App
        </a>
    </div>
    `
}
export default Brand
```

To render its [custom App Brand component](https://vue-vite-api.jamstacks.net/ui):

[![](/img/pages/locode/custom-brand.png)](https://vue-vite-api.jamstacks.net/ui)

## Custom Table Icons

Attributes added to your database model can change the visuals in your Locode application. For example, by adding `[Icon]`
top of `Booking` specifying either an `Svg` or `Uri` path we can change the icon for the table in left menu and table relationships.

```csharp
[Icon(Svg = "<svg xmlns=\"http://www.w3.org/2000/svg\" ...")]
public class Booking
{
    ...
}
```

Which will use this Icon whenever referring to `Booking` items:

![](/img/pages/locode/code-first-bookings-custom-1.png)

### Custom Icons for Database-first tables

On database model classes, the `Icon` attribute can be used with a `Uri` or `Svg` to style the table in the left menu and when
lookup data is displayed. For example, if we use the `TypeFilter` to access the data model types, we can apply the `Icon` attribute dynamically
to `Order` it will impact the tables that reference `Order`.

```csharp
TypeFilter = (type, req) =>
{
    if (Icons.TryGetValue(type.Name, out var icon))
        type.AddAttribute(new IconAttribute { Svg = Svg.Create(icon) });
    ...
}

public static Dictionary<string, string> Icons { get; } = new()
{
    ["Order"] = "<path fill='currentColor' ...",
};
```

<div class="not-prose">
<ul class="my-8 grid gap-4 sm:grid-cols-2">
    <li class="rounded-lg m-0 col-span-1 flex flex-col text-center items-center bg-white shadow divide-y divide-gray-200">
        <div class="flex-1 flex flex-col px-4 mt-4">
            <div class="mt-4 p-0 text-xl font-medium text-gray-500">Default Icon</div>
            <div class="rounded-lg focus-within:ring-2 focus-within:ring-offset-2 focus-within:ring-offset-gray-100 focus-within:ring-indigo-500 overflow-hidden">
                <img src="/img/pages/locode/database-first-northwind-icons-default.png" alt="">
            </div>
        </div>
    </li>
    <li class="rounded-lg m-0 col-span-1 flex flex-col text-center items-center bg-white shadow divide-y divide-gray-200">
        <div class="flex-1 flex flex-col px-4 mt-4">
            <div class="mt-4 p-0 text-xl font-medium text-gray-500">Custom Icon</div>
            <div class="rounded-lg focus-within:ring-2 focus-within:ring-offset-2 focus-within:ring-offset-gray-100 focus-within:ring-indigo-500 overflow-hidden">
                <img src="/img/pages/locode/database-first-northwind-icons-custom.png" alt="">
            </div>
        </div>
    </li>
</ul>
</div>

## Grouping services with Tag

To group the Northwind services under the same `Tag` name for the left menu in Locode, we can use the `Tag` attribute.

```csharp
[Tag("Northwind")]
public class Category { ... }

[Tag("Northwind")]
public class Customer { ... }
```

Instead of `Tables` we can now see our `Northwind` tag in the Locode app UI.

<div class="not-prose">
<ul class="my-8 grid gap-4 sm:grid-cols-2">
    <li class="rounded-lg m-0 col-span-1 flex flex-col text-center items-center bg-white shadow divide-y divide-gray-200">
        <div class="flex-1 flex flex-col px-4 mt-4">
            <div class="mt-4 p-0 text-xl font-medium text-gray-500">Default "Tables"</div>
            <div class="rounded-lg focus-within:ring-2 focus-within:ring-offset-2 focus-within:ring-offset-gray-100 focus-within:ring-indigo-500 overflow-hidden">
                <img src="/img/pages/locode/database-first-northwind-branding2.png" alt="">
            </div>
        </div>
    </li>
    <li class="rounded-lg m-0 col-span-1 flex flex-col text-center items-center bg-white shadow divide-y divide-gray-200">
        <div class="flex-1 flex flex-col px-4 mt-4">
            <div class="mt-4 p-0 text-xl font-medium text-gray-500">Custom Tag</div>
            <div class="rounded-lg focus-within:ring-2 focus-within:ring-offset-2 focus-within:ring-offset-gray-100 focus-within:ring-indigo-500 overflow-hidden">
                <img src="/img/pages/locode/database-first-northwind-tags.png" alt="">
            </div>
        </div>
    </li>
</ul>
</div>

As more unique `Tag` names are added, additional drop down menus will be created to group your services together.

### Adding Tags to Database-first tables

We can add the `[Tag]` attribute to all our Database-First Request DTOs using [AutoQuery AutoGen's](/autoquery/autogen) `ServiceFilter`: 

```cs
GenerateCrudServices = new GenerateCrudServices {
    AutoRegister = true,
    ServiceFilter = (op, req) => {
        // Annotate all Auto generated Request DTOs with [Tag("Northwind")] attribute
        op.Request.AddAttributeIfNotExists(new TagAttribute("Northwind"));
    },
}
```


# Format Functions
Source: https://docs.servicestack.net/locode/formatters

Format functions let you customize how fields are displayed in tabular result pages, e.g:

[![](/img/pages/locode/talent/contact-formatters.png)](https://talent.locode.dev/locode/QueryContacts)

Where columns are customized using a built-in formatting function referenced by the `[Format]` attributes:

```csharp
public class Contact : AuditBase
{
    [Format(FormatMethods.IconRounded)]
    public string ProfileUrl { get; set; }

    [Format(FormatMethods.Currency)]
    public int? SalaryExpectation { get; set; }

    [Format(FormatMethods.LinkEmail, Options = 
        @"{target:'_self',subject:'New Job Opportunity',
           body:'We have an exciting new opportunity...', cls:'text-green-600'}")]
    public string Email { get; set; }
 
    [Format(FormatMethods.LinkPhone)]
    public string Phone { get; set; }
    //....
}
```

Whilst the `[Intl*]` attributes provide a typed API to utilize JavaScript's rich 
[Intl](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl) object containing the
namespace for the ECMAScript Internationalization API, which provides number formatting, and date & time formatting, e.g:

[![](/img/pages/locode/chinook/tracks-formatters.png)](https://chinook.locode.dev/locode/QueryTracks)

Which was rendered using the `[Format]` ant `[Intl*]` attributes below:

```csharp
public class Tracks
{
    [Format(Method = "stylize", Options = "{cls:'text-rose-500'}")]
    public string Name { get; set; }
    
    [IntlDateTime(Minute = DatePart.Digits2, Second = DatePart.Digits2, FractionalSecondDigits = 3)]
    public long Milliseconds { get; set; }
    
    [Format(FormatMethods.Bytes)]
    public long? Bytes { get; set; }
    
    [IntlNumber(Currency = NumberCurrency.USD)]
    public decimal UnitPrice { get; set; }
    //....
}
```

## Custom Format Function

The `Name` column shows an example of calling a custom `stylize` JavaScript function defined in
[/modules/locode/custom.js](https://github.com/NetCoreApps/Chinook/blob/main/Chinook/wwwroot/modules/locode/custom.js):

```js
/**: Extend locode App with custom JS **/

/** Custom [Format] method to style text with custom class
 * @param {*} val
 * @param {{cls:string}} [options] */
function stylize(val, options) {
    let cls = options && options.cls || 'text-green-600'
    return `<span class="${cls}">${val}</span>`
}
```

Which makes use of [JSDoc](https://jsdoc.app) and
[TypeScript's JSDoc](https://www.typescriptlang.org/docs/handbook/jsdoc-supported-types.html)
support to [enable rich static analysis](custom).

## Format Attribute

The `[Format]` attribute lets you call any JavaScript function that exists in your Locode App. 
These formatting functions take the **field** value as a first argument and optionally an **options** object as the 2nd argument,
for further customization and can return any **HTML** fragment to render in-place of the field value.

Where the `[Format]` attribute's arguments:

```csharp
[Format(Method,Options)]
```

Calls the JavaScript function of that name, passing any options if specified:

```js
method(field,options)
```

For improved discoverability a typed list of all formatting functions are maintained in 
[FormatMethods.cs](https://github.com/ServiceStack/ServiceStack/blob/main/ServiceStack/src/ServiceStack.Interfaces/FormatMethods.cs)
which map to the built-in JavaScript functions below which are also discoverable in the 
[API Reference Function docs](https://api.locode.dev/modules/shared.html#apiForm-1).

### Number Formatters

Use number formatters to render numbers in a more human-readable formats:

#### `FormatMethods.Currency`

Formats a number into USD currency:

```ts
function currency(val: number): string;
```

This is a shorthand alias for `[IntlNumber(Currency = NumberCurrency.USD)]`.

#### `FormatMethods.Bytes`

Formats bytes into human-readable file size:
```ts
function bytes(val: number): string;
```

### Format as Links

The `link*` functions creates HTML Anchor links linking either URLs, emails or phone numbers.
In addition to configuring common anchor attributes, the `opt` **Options** modifier also lets you configure any of its HTML attributes.  

#### `FormatMethods.Link`

Create formatted HTML A URL links:

```ts
function link(href: string, opt?: { cls?: string; target?: string; rel?: string; }) : string;
```

#### `FormatMethods.LinkEmail`

Create formatted HTML A `mailto:` anchor links:

```ts
function linkMailTo(email: string, opt?: { subject?: string; body?: string;
    cls?: string; target?: string; rel?: string; }) : string;
```

#### `FormatMethods.LinkPhone`

Create formatted HTML A `tel:` anchor links:

```ts
function linkTel(tel: string, opt?: { cls?: string; target?: string; rel?: string; }): string;
```

#### `FormatMethods.Attachment`

Creates HTML Link and preview icon for a file. If the file is an image it will render its icon otherwise will use the
appropriate icon for its file type.

```ts
function attachment(url: string): string;
```

[![](/img/pages/locode/talent/attachment-formatters.png)](https://talent.locode.dev/locode/QueryJobApplicationAttachment)

Rendered with:

```csharp
public class JobApplicationAttachment
{
    [Format(FormatMethods.Attachment)]
    public string FilePath { get; set; }
    
    [Format(FormatMethods.Bytes)]
    public long ContentLength { get; set; }
}
```

### Format Images

For rendering preview icons of an image instead of its relative or absolute URL. 

#### `FormatMethods.Icon`

Create HTML IMG Icon from URL

```ts
function icon(url: string): string;
```

#### `FormatMethods.IconRounded`

Create rounded HTML IMG Icon from URL

```ts
function iconRounded(url: string): string;
```

#### `FormatMethods.Hidden`

For hiding a column from appearing in query results:

```ts
function hidden(o: any): string;
```

::: tip
To hide a field from appearing in Create or Edit UI Forms use `[Input(Ignore=true)]` instead. 
:::

## Intl Attributes

The `[Intl*]` attributes provide a typed API to utilize ECMAScript Internationalization
[Intl](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl) API
providing flexible number formatting, and date & time formatting functions:

 - [Intl.NumberFormat](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat/NumberFormat) ([Examples](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat/NumberFormat#examples))
 - [Intl.DateTimeFormat](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat/DateTimeFormat) ([Examples](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat/DateTimeFormat#examples))
 - [Intl.RelativeTimeFormat](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/RelativeTimeFormat/RelativeTimeFormat) ([Examples](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/RelativeTimeFormat/RelativeTimeFormat#examples))

The above referenced docs contain the available formatting options for each formatting function, we recommend using their 
JavaScript console to find out the formatting options you want, which should map 1:1 with the C# enums and constants in
[IntlAttribute.cs](https://github.com/ServiceStack/ServiceStack/blob/main/ServiceStack/src/ServiceStack.Interfaces/IntlAttribute.cs).

### Intl

`[Intl]` is a generic attribute capable of calling any of the supported
APIs although it's more UX-friendly to use the specific `[Intl*]` attributes instead, e.g:

```csharp
[IntlNumber(Currency = NumberCurrency.USD)]
```

Is a shorter alias that's equivalent to:

```csharp
[Intl(IntlFormat.Number, Number = NumberStyle.Currency, Currency = NumberCurrency.USD)] 
```

### IntlNumber

Makes use of [Intl.NumberFormat](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat/NumberFormat)
to format numbers, checkout [Examples](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat/NumberFormat#examples)
for a quick preview of the common formatting options available.

```csharp
public class IntlNumberExamples
{
    [IntlNumber]
    public int Example1 { get; set; }
    
    [IntlNumber(NumberStyle.Decimal, Locale = "en-AU", 
                RoundingMode = RoundingMode.HalfCeil, SignDisplay = SignDisplay.ExceptZero)]
    public int Example2 { get; set; }
    
    [IntlNumber(Currency = NumberCurrency.USD)]
    public int Example3 { get; set; }
    
    [IntlNumber(Currency = NumberCurrency.USD, CurrencyDisplay = CurrencyDisplay.Code)]
    public int Example4 { get; set; }
    
    [IntlNumber(Unit = NumberUnit.Kilobyte)]
    public int Example5 { get; set; }
}
```

Which translates to the following JavaScript function invocations:

```js
const number = 123456.789;

// Example 1: 123,456.789
new Intl.NumberFormat().format(number)

// Example 2: +123,456.789
new Intl.NumberFormat('en-AU', { style: 'decimal', roundingMode:'halfCeil', signDisplay:'exceptZero' })

// Example 3: $123,456.79
new Intl.NumberFormat(undefined, { style:'currency', currency:'USD' })

// Example 4: USD 123,456.79
new Intl.NumberFormat(undefined, { style:'currency', currency:'USD', currencyDisplay:'code' })

// Example 5: 123,456.789 kB
new Intl.NumberFormat(undefined, { style:'unit', unit:'kilobyte' })
```

### IntlDateTime

Makes use of [Intl.DateTimeFormat](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat/DateTimeFormat)
to format dates and times, checkout [Examples](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/DateTimeFormat/DateTimeFormat#examples)
for available date & time styles.

```csharp
public class IntlDateExamples
{
    [IntlDateTime]
    public DateTime Example1 { get; set; }
    
    [IntlDateTime(DateStyle.Medium, TimeStyle.Short, Locale = "en-AU")]
    public DateTime Example2 { get; set; }
    
    [IntlDateTime(DateStyle.Short)]
    public DateTime Example3 { get; set; }
    
    [IntlDateTime(Year = DatePart.Digits2, Month = DateMonth.Short, Day = DatePart.Numeric)]
    public DateTime Example4 { get; set; }
}
```

Translates to:

```js
const date = new Date(Date.UTC(2020, 11, 20, 3, 23, 16, 738));

// Example 1: 12/20/2020
new Intl.DateTimeFormat().format(date)

// Example 2: 20 Dec 2020, 11:23 am
new Intl.DateTimeFormat('en-AU', { dateStyle:'medium', timeStyle:'short' }).format(date)

// Example 3: 12/20/20
new Intl.DateTimeFormat(undefined, { dateStyle:'short' }).format(date)

// Example 4: Dec 20, 20
new Intl.DateTimeFormat(undefined, { year:'2-digit', month:'short', day:'numeric' }).format(date)
```

### IntlRelativeTime

Makes use of [Intl.RelativeTimeFormat](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/RelativeTimeFormat/RelativeTimeFormat)
to format dates and times, checkout [Examples](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/RelativeTimeFormat/RelativeTimeFormat#examples)
for common usages.

Can be applied to `DateTime` and `TimeSpan` properties to render a time that's relative to now, e.g:

```csharp
public class Booking : AuditBase
{    
    [IntlDateTime(DateStyle.Long)]
    public DateTime BookingStartDate { get; set; }
    
    [IntlRelativeTime]
    public DateTime? BookingEndDate { get; set; }

    [IntlRelativeTime]
    public TimeSpan TimeAgo => DateTime.UtcNow - this.BookingStartDate;
    //....
}
```

Renders the following formatted date & relative times:

![](/img/pages/locode/talent/booking-formatters.png)


# Custom Locode Apps
Source: https://docs.servicestack.net/locode/custom-overview

Locode also lets you create rich custom user experiences by going beyond the [declarative C# dev model](/locode/declarative)
to create custom HTML & JS Components loaded directly in your Locode Apps.

This lets us provide an enhanced UX beyond Locode's default UI to create [Custom Forms](/locode/custom-forms.html) for 
some of our tables or [override Locode's own components](/locode/custom-components) to create a custom home page 
or customize your [App's branding components](/locode/custom.html#custom-app-example) or make use of
[custom format functions](/locode/formatters.html#custom-format-function) to change how results are rendered.

To facilitate custom HTML/JS UI development we've packaged type definitions for all Locode's functionality in the  
`@servicestack/ui` npm package below to enable its productive typed development UX whose changes load instantly without
App restarts when run in development mode:

:::sh
dotnet watch
:::

## Getting Started

When customizing any ServiceStack UI App you can enable static typing and intelli-sense by installing the `@servicestack/ui` npm package
(containing their TypeScript `.d.ts` definitions) in your host project, where you'll be able to use the standard 
[ES6 import syntax](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/import) 
to enable static analysis on any built-in functionality you want to use.

### Install

Add TypeScript definitions for ServiceStack UI's to your Host project with:

:::sh
npm install -D @servicestack/ui
:::

### Update

Update your local Type definitions to the latest version with:

:::sh
npm install @servicestack/ui@latest
:::

## API Reference

Type definitions for functionality available in ServiceStack UI's

[![](/img/pages/locode/shared-api-reference.png)](https://api.locode.dev/modules/shared.html)

### Library Reference

| Namespace                                            | Description                                                                          |
|------------------------------------------------------|--------------------------------------------------------------------------------------|
| [shared](https://api.locode.dev/modules/shared.html) | Type Definitions for all Types and shared functionality used in all UI's             |
| [client](https://api.locode.dev/modules/client.html) | Type Definitions for the [@servicestack/client](https://github.com/ServiceStack/servicestack-client) library |

### UIs

| UI                                                       | Description                                                                      |
|----------------------------------------------------------|----------------------------------------------------------------------------------|
| [locode](https://api.locode.dev/modules/locode.html)     | Global App and Type instances available in [Locode Apps](https://servicestack.net/locode) |
| [explorer](https://api.locode.dev/modules/explorer.html) | Global App and Type instances available in [API Explorer](/api-explorer)         |
| [admin](https://api.locode.dev/modules/admin.html)       | Global App and Type instances available in ServiceStack's [Admin UI](/admin-ui)  |


## Custom UI

Whilst `@servicestack/ui` isn't used at runtime and therefore not strictly required, it contains the type definitions 
for all built-in ServiceStack Apps to enable superior Developer UX by enabling static analysis, rich-intellisense and 
type safety feedback to provide a helpful guide ensuring correct usage of discoverable built-in functionality. 

All built-in ServiceStack Apps can be customized the same way where each of their HTML components can be replaced by 
adding a local file at their same path in your AppHost Project's `/wwwroot/modules` folder: 

## /wwwroot/modules

To make it easy to customize each App, purpose-specific `custom.*` placeholders can be overridden to include additional
CSS, JS and HTML in each App. Whilst any of their existing components can be replaced by adding a local modified copy
in its `/components/*.html` folder. 

We'll go through each App's folder to better visualize their extension placeholders that's available:  

### /locode

Lets you customize [Locode Apps](https://servicestack.net/locode) where [Custom Forms](/locode/custom-forms) can either be registered in 
`custom.html` or added to `/components/*.mjs` where you can also override any of Locode's components by including 
a locally modified copy from
[/components/*.mjs](https://github.com/ServiceStack/ServiceStack/tree/main/ServiceStack/src/ServiceStack/modules/locode/components)

```files
/wwwroot/modules/locode
  /components
    *.mjs
  custom.js
  custom.css
  custom.html
```

### /ui

Is where to customize your Services [API Explorer UI](/api-explorer) where each API can
be documented by adding [Custom API Docs](/api-explorer#api-docs) to `/docs/*.mjs`,
whilst existing components can be overridden in 
[/components/*.mjs](https://github.com/ServiceStack/ServiceStack/tree/main/ServiceStack/src/ServiceStack/modules/ui/components)
and custom UI added to `custom.*`

```files
/wwwroot/modules/ui
  /docs
    *.mjs
  /components
    *.mjs
  custom.js
  custom.css
  custom.html
```

### /admin-ui

Is where to add any customizations to [Admin UI](/admin-ui) by overriding existing components in 
[/components/*.mjs](https://github.com/ServiceStack/ServiceStack/tree/main/ServiceStack/src/ServiceStack/modules/admin-ui/components)
or adding custom UI to `custom.*`

```files
/wwwroot/modules/admin-ui
  /components
    *.mjs
  custom.js
  custom.css
  custom.html
```

### /shared

The shared folder is where you can customize all Apps by overriding generic components in 
[shared/*.html](https://github.com/ServiceStack/ServiceStack/tree/main/ServiceStack/src/ServiceStack/modules/shared)
whilst custom HTML can be added to the `<head/>`, at the start and end of the `<body/>` of each App by including
the `custom-*.html` placeholders below:

```files
/wwwroot/modules/shared
  custom-head.html
  custom-body.html
  custom-end.html        
```

### Custom App Example

The [Blazor WASM](/templates/blazor-bootstrap) template includes example App customizations with
[Custom API Docs](/api-explorer#api-docs) for its 
[CreateBooking](https://vue-vite-api.jamstacks.net/ui/CreateBooking?tab=details) and
[Todos APIs](https://vue-vite-api.jamstacks.net/ui/QueryTodos?tab=details):

<ul class="list-none">
    <li>
        <a href="https://github.com/NetCoreTemplates/blazor-wasm/tree/main/MyApp/wwwroot/modules" class="font-medium">/modules</a>
        <ul class="list-none">
            <li>
                <span class="font-medium">/ui/docs</span>
                <ul class="list-none">
                    <li>
                        <a href="https://github.com/ServiceStack/ServiceStack/blob/main/ServiceStack.Blazor/tests/ServiceStack.Blazor.Bootstrap.Tests/Server/modules/ui/docs/CreateBookingDocs.mjs">
                            CreateBookingDocs.mjs
                        </a>
                    </li>
                    <li>
                        <a href="https://github.com/ServiceStack/ServiceStack/blob/main/ServiceStack.Blazor/tests/ServiceStack.Blazor.Bootstrap.Tests/Server/modules/ui/docs/TodoDocs.mjs">
                            TodoDocs.mjs
                        </a>
                    </li>
                </ul>
            </li>
        </ul>
    </li>
</ul>

Whilst replacing the existing **shared** `Brand` Component changes the top-left App Branding UI in each App:

<ul class="list-none">
    <li>
        <a href="https://github.com/ServiceStack/ServiceStack/tree/main/ServiceStack/src/ServiceStack/js/components" class="font-medium">/js/components</a>
        <ul class="list-none">
            <li>
                <a href="https://github.com/ServiceStack/ServiceStack/blob/main/ServiceStack.Blazor/tests/ServiceStack.Blazor.Bootstrap.Tests/Server/js/components/Brand.mjs">
                    Brand.mjs
                </a>
            </li>
        </ul>
    </li>
</ul>

Next we'll see how we to create [Custom Forms](/locode/custom-forms) to replace the Auto Form UI in Locode Apps.


# Custom AutoQueryGrid
Source: https://docs.servicestack.net/locode/custom-autoquerygrid

Locode lets you easily replace entire Locode Pages with your own, thanks to the reusable [AutoQueryGrid](/vue/autoquerygrid) component in the [Vue Component Library](/vue/) which lets you reuse custom components in your Vue Project templates to replace functionality in Locode, e.g. we can copy the custom 
[Bookings AutoQueryGrid](https://blazor-vue.web-templates.io/secure/bookings) Vue 3 component in the new [blazor-vue](https://blazor-vue.web-templates.io) Project Template
and use it to manage our Bookings in Locode by registering a Vue 3 component with the name:

`{DataModel}Page`

## Example

That we can auto register with Locode by adding it in our **/wwwroot** folder at `/modules/locode/components/*.mjs`.

Which we've added in our Blazor Gallery App, in [/modules/locode/components/BookingPage.mjs](https://github.com/NetCoreApps/BlazorGallery/blob/main/Gallery.Server/wwwroot/modules/locode/components/BookingPage.mjs) containing our custom Bookings AutoQueryGrid component:

```csharp
import { inject, ref } from "vue"
import { QueryCoupons } from "/types/mjs"

export const BookingPage = {
    template:`
    <div>
        <h1 class="py-8 text-center text-3xl text-indigo-700 font-semibold">Custom Bookings AutoQueryGrid</h1>
        <AutoQueryGrid type="Booking" selected-columns="id,name,cost,bookingStartDate,bookingEndDate,discount,notes">
        <template #discount="{ discount }">
            <TextLink v-if="discount" class="flex items-end" @click.stop="showCoupon(discount.id)" :title="discount.id">
                <Icon class="w-5 h-5 mr-1" type="Coupon" />
                <PreviewFormat :value="discount.description" />
            </TextLink>
        </template>
        </AutoQueryGrid>
        <AutoEditForm v-if="coupon" type="UpdateCoupon" v-model="coupon" @done="close" @save="close" />
    </div>
    `,
    props:['type'],
    setup() {
        const client = inject('client')
        const coupon = ref()
        async function showCoupon(id) {
            const api = await client.api(new QueryCoupons({ id }))
            if (api.succeeded) {
                coupon.value = api.response.results[0]
            }
        }
        const close = () => coupon.value = null
        return { coupon, showCoupon, close }
    }
}
```

Where our custom version will open the related **Coupon** entry for the booking allowing both Bookings and their Coupons to be managed from the same page.

Now when **Booking** is selected in Locode it will load our custom version:

<a href="https://blazor-gallery.servicestack.net/locode/QueryBookings" class="not-prose max-w-4xl">
    <div class="block flex justify-center shadow hover:shadow-lg rounded">
        <img class="" src="/img/pages/locode/custom-bookingpage.png">
    </div>
</a>


# Custom Forms
Source: https://docs.servicestack.net/locode/custom-forms

To override Locode's built-in Form UI you can add custom [Vue components](https://vuejs.org/guide/essentials/component-basics.html)
to your Host Project **/wwwroot** folder at `/modules/locode/components/*.mjs` using the naming conventions below:

| Component Name | Description           |
|----------------|-----------------------|
| `New{Table}`   | Custom Create Form UI |
| `Edit{Table}`  | Custom Update Form UI |

The [chinook.locode.dev](https://chinook.locode.dev) demo does this to create a custom Form UI for creating and
editing Albums by registering `NewAlbums` in [NewAlbums.mjs](https://github.com/NetCoreApps/Chinook/blob/main/Chinook/wwwroot/modules/locode/components/NewAlbums.mjs)
and `EditAlbums` component in [EditAlbums.mjs](https://github.com/NetCoreApps/Chinook/blob/main/Chinook/wwwroot/modules/locode/components/EditAlbums.mjs)
which are used to render Chinook's [custom Create Album form](https://chinook.locode.dev/locode/QueryAlbums?create)
to update its `Albums` table.

## Built-in App functionality

### JavaScript Libraries

Your custom components can utilize built in libraries embedded in ServiceStack.dll where they will have access to the latest [Vue 3](https://vuejs.org/guide/introduction.html) reactive fx, [@servicestack/client](/javascript-client) client library and [Vue 3 Tailwind Component library](/vue/) which they can import by package name, e.g:

```js
import { ref } from "vue"
import { useClient } from "@servicestack/vue"
import { humanify } from "@servicestack/client"
```

#### Static Analysis

As all package dependencies are written in TypeScript you can install them as dev dependencies to get static analysis from its TypeScript definitions at dev time:

```bash
npm install -D vue
npm install -D @servicestack/client
npm install -D @servicestack/vue
```

Your components can access your Apps Typed DTOs directly from the [ES6 Module DTO endpoint](/javascript-add-servicestack-reference) at `/types/mjs`, e.g:

```js
import { CreateAlbums } from "/types/mjs"
```

### App functionality

Your components access to most App functionality via the injected dependencies for functionality defined in Locode's [app.mjs](https://github.com/ServiceStack/ServiceStack/blob/main/ServiceStack/tests/NorthwindAuto/locode/lib/app.mjs):

```js
const app = inject('app')                  // App for customizing Vue App, register components, providers, plugins, etc
const client = inject('client')            // JsonServiceClient for API Calls
const server = inject('server')            // AppMetadata (metadata for your Server App and APIs)
const store = inject('store')              // Locode's Reactive object model
const routes = inject('routes')            // usePageRoutes() Reactive store to manage its SPA routing
const breakpoints = inject('breakpoints')  // useBreakpoints() Reactive store to Tailwind responsive breakpoints
```

Most of which creates instance of common library features in [core.mjs](https://github.com/ServiceStack/ServiceStack/blob/main/ServiceStack/tests/NorthwindAuto/wwwroot/js/core.mjs) that are documented at [api.locode.dev/modules/locode.html](https://api.locode.dev/modules/locode.html).

You're also not limited with what's in Locode, with full access to [JavaScript Modules](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules)
you can import external 3rd Party packages the same way you import built-in packages.

### Code walkthrough

Your components will have full control to implement their desired functionality how they want, which can get a lot of integrated functionality for free by leveraging the [Vue Component library](/vue/), e.g. this custom component uses:

 - [ModalDialog](/vue/modals) - to load our custom Create Albums Form component in a Modal Dialog
 - [ErrorSummary](/vue/alerts) - to display any non-contextual summary API errors
 - [TextInput](/vue/form-inputs) - to create a validation bound form for the `CreateAlbums` **Title** property
 - [LookupInput](/vue/form-inputs) - to create a Lookup input to select an Artist for the `CreateAlbums` **ArtistId** property

Whilst `<SubmitAlbumButton>` is an example of using a shared component in 
[SubmitAlbumButton.mjs](https://github.com/NetCoreApps/Chinook/blob/main/Chinook/wwwroot/modules/locode/components/SubmitAlbumButton.mjs).

```js
import { ref } from "vue"
import { useClient, useMetadata } from "@servicestack/vue"
import { CreateAlbums } from "/types/mjs"

export const NewAlbums = {
    template:/*html*/`
    <ModalDialog @done="done" sizeClass="">
      <div class="album-form relative flex flex-col">
        <ErrorSummary except="title,artistId"/>
        <form @submit.prevent="submit" class="m-4 shadow-md rounded-full w-96 h-96 flex justify-center items-center">
          <div class="flex flex-col justify-center items-center text-center">
            <h1 class="text-3xl font-medium text-rose-500 mb-4">New Album</h1>
            <fieldset>
              <TextInput id="title" v-model="request.title" label="" placeholder="Album Title" class="mb-3" />

              <LookupInput id="artistId" v-model="request" label="" placeholder="Select Artist"
                           :input="lookupProp.input" :metadataType="dataModelType" class="mb-3" />

              <SubmitAlbumButton />
            </fieldset>
          </div>
        </form>
      </div>
    </ModalDialog>
    `,
    props: ['type'],
    emits: ['done','save'],
    setup(props, { emit }) {
        const client = useClient()
        const { typeOf } = useMetadata()

        const dataModelType = typeOf("Albums")
        const lookupProp = dataModelType.properties.find(x => x.name === 'ArtistId')
        const request = ref(new CreateAlbums())

        /** @param {Event} e */
        async function submit(e) {
            const form = e.target
            const api = await client.apiForm(new CreateAlbums(), new FormData(form))
            if (api.succeeded) {
                emit('save', api.response)
            }
        }

        function done() {
            emit('done')
        }

        return { request, lookupProp, dataModelType, submit, done }
    }
}
```

The only integration needed to communicate back with Locode's
[AutoQueryGrid component](/vue/autoquerygrid) is to emit `done` when the form is dismissed without changes or emit `save` if changes are made to
refresh the AutoQueryGrid resultset to see the latest changes.

Invoking APIs with `useClient()` APIs will propagate any error information from any [declarative validation attributes](/locode/declarative#type-validation-attributes) into validation-aware components which alleviates us from needing to perform any manual validation ourselves.

When registered this custom component replaces Locode's Auto Form UI with a custom [Create Album Form](https://chinook.locode.dev/locode/QueryAlbums?create):

[![](/img/pages/locode/chinook/custom-createform.png)](https://chinook.locode.dev/locode/QueryAlbums?create)

That when submitting an empty form will trigger the contextual validation errors to appear:

[![](/img/pages/locode/chinook/custom-createform-errors.png)](https://chinook.locode.dev/locode/QueryAlbums?new=true)

As enforced by the [Declarative Validation](/declarative-validation) rules on the `CreateAlbums` AutoQuery CRUD DTO its calling:

```csharp
[Route("/albums", "POST"), Tag(Tags.Media)]
public class CreateAlbums
    : IReturn<IdResponse>, IPost, ICreateDb<Albums>
{
    [ValidateNotEmpty]
    public string Title { get; set; }

    [ValidateGreaterThan(0)]
    public long ArtistId { get; set; }
}
```

## Custom Edit Form

The custom `EditAlbums` form has a very similar implementation the `NewAlbums` implementation above other than populating the Input components with 
the existing Album's values, accessible via the **model** property.

```js
import { useClient, useMetadata } from "@servicestack/vue"
import { ref } from "vue"
import { UpdateAlbums } from "/types/mjs"

export const EditAlbums = {
    template:/*html*/`
      <ModalDialog @done="done" sizeClass="">
        <div class="album-form relative flex flex-col">
          <ErrorSummary except="title,artistId" />
          <form @submit.prevent="submit" class="m-4 shadow-md rounded-full w-96 h-96 max-w-96 flex justify-center items-center">
            <div class="flex flex-col justify-center items-center text-center">
              <h1 class="text-3xl font-medium text-rose-500 mb-4">Edit Album {{ request.albumId }}</h1>
              <fieldset>
                <input type="hidden" name="albumId" :value="request.albumId">
                <TextInput id="title" v-model="request.title" label="" placeholder="Album Title" class="mb-3" />

                <LookupInput id="artistId" v-model="request" label="" placeholder="Select Artist"
                             :input="lookupProp.input" :metadataType="dataModelType" class="mb-3" />

                <SubmitAlbumButton />
              </fieldset>
            </div>
          </form>
        </div>
      </ModalDialog>
    `,
    props: ['model','type','deleteType'],
    emits: ['done','save'],
    setup(props, { emit }) {
        const client = useClient()
        const { typeOf } = useMetadata()

        const dataModelType = typeOf("Albums")
        const lookupProp = dataModelType.properties.find(x => x.name === 'ArtistId')
        const request = ref(new UpdateAlbums(props.model))

        /** @param {Event} e */
        async function submit(e) {
            const form = e.target
            const api = await client.apiForm(new UpdateAlbums(), new FormData(form))
            if (api.succeeded) {
                emit('save', api.response)
            }
        }

        function done() {
            emit('done')
        }

        return { request, lookupProp, dataModelType, submit, done }
    }
} 
```

If applicable **deleteType** will be populated with an API to Delete Albums that the current user has authorization to access, should you wish to implement delete functionality.

Then to perform the updates we just need to call an Update Albums API, which for Chinook is called `PatchAlbums`:

```csharp
[Route("/albums/{AlbumId}", "PATCH"), Tag(Tags.Media)]
public class PatchAlbums
    : IReturn<IdResponse>, IPatch, IPatchDb<Albums>
{
    public long AlbumId { get; set; }
    public string Title { get; set; }
    public long ArtistId { get; set; }
}
```

Which is all that's need to implement our custom Edit Albums Form:

[![](/img/pages/locode/chinook/custom-editform.png)](https://chinook.locode.dev/locode/QueryAlbums?edit=6)

To minimize code duplication both custom forms makes use of a shared
[SubmitAlbumButton.mjs](https://github.com/NetCoreApps/Chinook/blob/main/Chinook/wwwroot/modules/locode/components/SubmitAlbumButton.mjs) component, defined as:

```js
export const SubmitAlbumButton = {
    template:`
    <button type="submit" class="inline-flex items-center p-3 border border-transparent rounded-full shadow-sm text-white bg-rose-600 hover:bg-rose-700 focus:outline-none focus:ring-2 focus:ring-offset-2 focus:ring-rose-500">
        <svg class="h-8 w-8" xmlns="http://www.w3.org/2000/svg" aria-hidden="true" preserveAspectRatio="xMidYMid meet" viewBox="0 0 48 48">
            <g fill="none" stroke="currentColor" stroke-linejoin="round" stroke-width="4">
                <path stroke-linecap="round" d="M24 44C12.954 44 4 35.046 4 24S12.954 4 24 4s20 8.954 20 20"/>
                <path d="M20 24v-6.928l6 3.464L32 24l-6 3.464l-6 3.464V24Z"/><path stroke-linecap="round" d="M37.05 32v10M42 36.95H32"/>
            </g>
        </svg>
    </button>`
}
```

## Custom Locode Home Page

Next we'll look at how we can create a [custom Home page](/locode/custom-components) by overriding Locode's
existing `Welcome.mjs` component.


# Custom HTML Components
Source: https://docs.servicestack.net/locode/custom-components

The Chinook Demo shows an example of overriding its existing
[/modules/locode/components/Welcome.mjs](https://github.com/NetCoreApps/Chinook/blob/main/Chinook/wwwroot/modules/locode/components/Welcome.mjs)
component in order to render its [custom Home page](https://chinook.locode.dev/locode).

## Example

Which in addition to using built-in Locode functionality, also makes use of your Apps Typed DTOs directly from the [ES6 Module DTO endpoint](/javascript-add-servicestack-reference) at `/types/mjs`, e.g:

```js
import { QueryInvoices } from "/types/mjs"
```
This results in providing an end-to-end typed dev UX for creating custom components that call our App's APIs as done in:

```js
import { inject, ref, onMounted, computed } from "vue"
import { QueryInvoices } from "/types/mjs"

export const Welcome = {
    template:/*html*/`
    <div class="pl-4">
        <h1 class="text-3xl">
            Welcome to Chinook Locode
        </h1>
        <div v-if="lastOrders.length" class="mt-8">
            <h3 class="text-xl mb-4">Here are your last {{lastOrders.length}} orders:</h3>
            <DataGrid class="max-w-screen-md" type="Invoices" :items="lastOrders" tableStyle="uppercaseHeadings" />
        </div>
    </div>`,
    setup() {
        const client = inject('client')
        const api = ref()
        const lastOrders = computed(() => api.value?.response?.results || [])
        
        onMounted(async () => {
            api.value = await client.api(new QueryInvoices({ 
                orderBy:'-InvoiceId',
                take:5,
                fields:'InvoiceId,CustomerId,InvoiceDate,Total,BillingCountry,BillingCity'
            }), { jsconfig: 'edv' })
        })
        
        return { lastOrders }
    }
}
```

Which uses the [DataGrid](/vue/datagrid) component to render its [custom Home page](https://chinook.locode.dev/locode):

[![](/img/pages/locode/chinook/welcome.png)](https://chinook.locode.dev/locode)

That makes use of the [Declarative UI Attributes](/locode/declarative#ui-metadata-attributes) in its
[Invoices](https://github.com/NetCoreApps/Chinook/blob/main/Chinook.ServiceModel/Types/Models.cs) data model to render a formatted currency
**Total** and a direct link to the Customer that the invoice was for:

```csharp
[Icon(Svg = Icons.Invoices)]
public class Invoices
{
    [AutoIncrement]
    public long InvoiceId { get; set; }

    [Ref(Model = nameof(Customers), RefId = nameof(CustomerId), RefLabel = nameof(Customers.DisplayName))]
    public long CustomerId { get; set; }
    
    public DateTime InvoiceDate { get; set; }
    [Format(FormatMethods.Currency)]
    
    public decimal Total { get; set; }
    public string BillingAddress { get; set; }
    public string BillingCity { get; set; }
    public string BillingState { get; set; }
    public string BillingCountry { get; set; }
    public string BillingPostalCode { get; set; }
}
```


# Managed Files Uploads
Source: https://docs.servicestack.net/locode/files-overview

The `FileUploadFeature` plugin is a high-level ServiceStack feature that allows you to configure multiple managed
file upload locations within the same App that you can declaratively bind to different APIs to use. 

<div class="py-8 max-w-7xl mx-auto px-4 sm:px-6">
    <lite-youtube class="w-full mx-4 my-4" width="560" height="315" videoid="5sd00MzHpaU" style="background-image: url('https://img.youtube.com/vi/5sd00MzHpaU/maxresdefault.jpg')"></lite-youtube>
</div>

Upload Locations can be configured to use any of the supported 
[Writable Virtual File Systems](/virtual-file-system#writable-virtual-file-system) including:

- `FileSystemVirtualFiles` - Hard-disk or Network Files and Directories from a specified directory
- `S3VirtualFiles` - Files stored on Amazon's S3 Managed File Storage in [ServiceStack.Aws](/aws#s3virtualfiles)
- `R2VirtualFiles` - Files stored on CloudFlare's R2 Managed File Storage in [ServiceStack.Aws](/aws#s3virtualfiles)
- `AzureBlobVirtualFiles` - Files stored on Azure's Managed Blob Storage in [ServiceStack.Azure](https://github.com/ServiceStack/ServiceStack.Azure)
- `GistVirtualFiles` - Files persisted to a GitHub Gist
- `MemoryVirtualFiles` - Temporary Virtual Files and Folders that last for the lifetime of the AppHost

:::tip
Additional support for external file storages can be added by 
[Implementing a new Virtual File System](/virtual-file-system#implementing-a-new-virtual-file-system)
:::

Managed file uploads is a generic feature any ServiceStack HTTP API can use by declaratively annotating it on Request DTOs. 
It's especially useful in [AutoQuery CRUD APIs](/autoquery/crud) as it enables an easy way to populate a file path that can be stored along with 
a table row without the uploaded files embedded in the database itself, taking up valuable RDBMS resources and significantly impacting its performance.

## Basic File Upload Example

To demonstrate how to use the Managed File Uploads feature we'll look at handling the basic example of uploading files
to publicly accessible `/wwwroot` folder location. This is what the [talent.locode.dev](https://talent.locode.dev) Demo
uses to handle profile image uploads for Contacts and Users in different locations in its 
[Configure.AppHost.cs](https://github.com/NetCoreApps/TalentBlazor/blob/main/TalentBlazor/Configure.AppHost.cs):

```csharp
.ConfigureServices((context, services) =>
{
    // Configure ASP.NET Core IOC Dependencies
    var wwwrootVfs = new FileSystemVirtualFiles(context.HostingEnvironment.WebRootPath);
    services.AddPlugin(new FilesUploadFeature(
        new UploadLocation("profiles", wwwrootVfs, allowExtensions:FileExt.WebImages,
            resolvePath: ctx => $"/profiles/{ctx.FileName}"),
        new UploadLocation("users", wwwrootVfs, allowExtensions:FileExt.WebImages,
            resolvePath: ctx => $"/profiles/users/{ctx.UserAuthId}.{ctx.FileExtension}"),
        //...
    ));
});
```

As both locations are uploaded to the App's `/wwwroot` folder they'll be immediately accessible after they're uploaded.
Contact profile images are saved using their uploaded FileName whilst User profiles are saved in a predictable location
against their User Id and uploaded File Extension type.

The only default restriction placed on File Uploads is that they can only be performed by Authenticated Users. 
Each `UploadLocation` is able to use the several configuration options available to further restrict file uploads
by file type, count, size, number of uploads or a custom validation function. In this instance Talent Blazor
is restricting uploads in `allowExtensions` to only Images supported by Browsers, which is a server validation that 
also gets propagated to the client to limit the user to only be able to select from the server-configured file extensions:

![](/img/pages/locode/talent/upload-accept.png)


To simplify configuration 
[we've included](https://github.com/ServiceStack/ServiceStack/blob/main/ServiceStack/src/ServiceStack/FilesUploadFeature.cs) 
a number of pre-configured file extensions for different file types.

```csharp
public static class FileExt
{
    string[] WebImages = { "png", "jpg", "jpeg", "gif", "svg", "webp" };
    string[] BinaryImages = {"png", "jpg", "jpeg", "gif", "bmp", "tif", "tiff", "webp", "ai", "psd","ps"};
    string[] Images = WebImages.CombineDistinct(BinaryImages);
    string[] WebVideos = { "avi", "m4v", "mov", "mp4", "mpg", "mpeg", "wmv", "webm" };
    string[] WebAudios = { "mp3", "mpa", "ogg", "wav", "wma", "mid", "webm" };
    string[] BinaryDocuments = { "doc", "docx", "pdf", "rtf" };
    string[] TextDocuments = { "tex", "txt", "md", "rst" };
    string[] Spreadsheets = { "xls", "xlsm", "xlsx", "ods", "csv", "txv" };
    string[] Presentations = { "key", "odp", "pps", "ppt", "pptx" };
    string[] AllDocuments = BinaryDocuments.CombineDistinct(TextDocuments, Presentations, Spreadsheets);
    string[] WebFormats = WebImages.CombineDistinct(WebVideos, WebAudios);
}
```

### Using File Upload Locations in APIs

With just the above configuration we can now use them in our APIs, which Talent Blazor does in its `CreateContact`
and `UpdateContact` [CRUD APIs](/autoquery/crud) to handle uploading a contact profiles image 
when they're Created and Updated:

```csharp
public class CreateContact : ICreateDb<Contact>, IReturn<Contact>
{
    [ValidateNotEmpty]
    public string FirstName { get; set; } = string.Empty;
    [ValidateNotEmpty]
    public string LastName { get; set; } = string.Empty;
    
    [Input(Type = "file"), UploadTo("profiles")]
    public string? ProfileUrl { get; set; }

    public int? SalaryExpectation { get; set; }
    [ValidateNotEmpty]
    public string JobType { get; set; } = string.Empty;
    public int AvailabilityWeeks { get; set; }
    public EmploymentType PreferredWorkType { get; set; }
    [ValidateNotEmpty]
    public string PreferredLocation { get; set; } = string.Empty;
    [ValidateNotEmpty]
    public string Email { get; set; } = string.Empty;
    public string? Phone { get; set; }
}

public class UpdateContact : IPatchDb<Contact>, IReturn<Contact>
{
    public int Id { get; set; }
    [ValidateNotEmpty]
    public string? FirstName { get; set; }
    [ValidateNotEmpty]
    public string? LastName { get; set; }

    [Input(Type = "file"), UploadTo("profiles")]
    public string? ProfileUrl { get; set; }
    
    public int? SalaryExpectation { get; set; }
    [ValidateNotEmpty]
    public string? JobType { get; set; }
    public int? AvailabilityWeeks { get; set; }
    public EmploymentType? PreferredWorkType { get; set; }
    public string? PreferredLocation { get; set; }
    [ValidateNotEmpty]
    public string? Email { get; set; }
    public string? Phone { get; set; }
    [Input(Type = "textarea"), FieldCss(Field = "col-span-12 text-center")]
    public string? About { get; set; }
}
```

Only the `[UploadTo(location)]` attribute is required to instruct the API to use the specified Upload Location to 
handle the File Upload. For successful uploads the Uploaded HTTP File will be saved to the configured file path which
it populates on the `ProfileUrl` property which from that point is treated as a normal `string` property that is 
validated and stored along with the rest of the DTO properties in the `Contact` Table.

### Auto Form UIs

In API Explorer & Locode Apps you'll want to pair this together with `[Input(Type="file")]` to instruct the Auto Form UI
to use its File Upload control to handle updating this property, which looks like:

[![](/img/pages/locode/talent/update-contact.png)](https://talent.locode.dev/locode/QueryContacts?edit=1)

## Managed Multi File Upload example

In addition to managing image profiles for its Users and Contacts, Talent Blazor also uses Managed File Uploads to
handle accepting an Applicant's Job Application attachments. A more 
[advanced configuration](https://github.com/NetCoreApps/FileBlazor/blob/main/FileBlazor/Configure.AppHost.cs) 
is needed for this use-case, that:

 - Saves uploaded Applications to the non-servable **~/App_Data** folder
 - Limits Job Applications to a maximum of **3 attachments**
 - Limits Max Upload size to **10mb**
 - Allows **non-authenticated Users** to upload & download their attachments

```csharp
.ConfigureServices((context, services) =>
{
    // Configure ASP.NET Core IOC Dependencies
    var appDataVfs = new FileSystemVirtualFiles(context.HostingEnvironment.ContentRootPath.CombineWith("App_Data").AssertDir());
    services.AddPlugin(new FilesUploadFeature(
        //...
        new UploadLocation("applications", appDataVfs, maxFileCount: 3, maxFileBytes: 10_000_000,
            resolvePath: ctx => ctx.GetLocationPath((ctx.Dto is CreateJobApplication create
                    ? $"jobapp/{create.JobId}/{create.ContactId}/{ctx.FileName}"
                    : $"app/{ctx.Dto.GetId()}") + $"/{ctx.DateSegment}/{ctx.FileName}"),
            readAccessRole: RoleNames.AllowAnon, writeAccessRole: RoleNames.AllowAnon)
    ));
});
```

In this case instead of resolving a relative path from `/wwwroot` it uses `ctx.GetLocationPath()` to resolve to a managed 
file location whose access is managed by  `FilesUploadFeature` File Management APIs:

| API                 | Route                               | Description                                       |
|---------------------|-------------------------------------|---------------------------------------------------|
| `StoreFileUpload`   | **POST** `/uploads/{Name}`          | Upload files to the specified managed location    |
| `GetFileUpload`     | **GET** `/uploads/{Name}/{Path}`    | Download file from the specified managed location |
| `ReplaceFileUpload` | **PUT** `/uploads/{Name}/{Path}`    | Overwrite file at the specified managed location  |
| `DeleteFileUpload`  | **DELETE** `/uploads/{Name}/{Path}` | Delete file at the specified managed location     |

:::tip
`/uploads` is the default overridable `BasePath` for `FilesUploadFeature` managed File APIs
:::

We can now start accepting attachments with our Job Applications by adding `[Input(Type="file"), UploadTo("applications")]` 
to the property where we want the Uploaded File metadata populated, when submitting and updating Job Applications:

```csharp
public class CreateJobApplication : ICreateDb<JobApplication>, IReturn<JobApplication>
{
    [ValidateGreaterThan(0)]
    public int JobId { get; set; }
    [ValidateGreaterThan(0)]
    public int ContactId { get; set; }
    public DateTime AppliedDate { get; set; }
    public JobApplicationStatus ApplicationStatus { get; set; }
    [Input(Type="file"), UploadTo("applications")]
    public List<JobApplicationAttachment> Attachments { get; set; }
}

public class UpdateJobApplication : IPatchDb<JobApplication>, IReturn<JobApplication>
{
    public int Id { get; set; }
    public int? JobId { get; set; }
    public int? ContactId { get; set; }
    public DateTime? AppliedDate { get; set; }
    public JobApplicationStatus ApplicationStatus { get; set; }
    [Input(Type="file"), UploadTo("applications")]
    public List<JobApplicationAttachment>? Attachments { get; set; }
}
```

This is all that's needed to configure our CRUD Services to handle multiple file uploads in Locode & API Explorer:

![](/img/pages/locode/talent/create-job-application.png)

Where the File Input behaves as just another Input control with contextual validation errors displayed when it exceeds
any of the configured file restrictions on its Upload Location, e.g:

![](/img/pages/locode/talent/create-job-application-failed.png)

After a successful submission the attachments are uploaded to the configured managed location path which is then used to 
access the file in the Update Job Application Form UI:

![](/img/pages/locode/talent/update-job-application.png)

### Integrates with AutoQuery CRUD

This is another example of how well this generic feature works with the rest of ServiceStack, where without any 
implementation logic the AutoQuery CRUD API is able to populate a **1 to Many** table relationship to capture the metadata 
of each uploaded file because the `Attachments` Request DTO property maps to a `[Reference]` 
[POCO Reference](/ormlite/reference-support) property which automatically populates 
Foreign Key Reference properties in CRUD APIs.

```csharp
public class JobApplication : AuditBase
{
    [Reference]
    public List<JobApplicationAttachment> Attachments { get; set; }
    //...
}

public class JobApplicationAttachment
{
    [AutoIncrement]
    public int Id { get; set; }

    [References(typeof(JobApplication))]
    public int JobApplicationId { get; set; }

    public string FileName { get; set; }
    [Format(FormatMethods.Attachment)]
    public string FilePath { get; set; }
    public string ContentType { get; set; }
    [Format(FormatMethods.Bytes)]
    public long ContentLength { get; set; }
}
```

### Uploaded File Metadata populated in Complex Type properties

This also shows that `[UploadTo]` can either be applied to a `string` property where it's just populated with the
path the file is uploaded to, or it could contain a **complex type** where any matching properties are populated with
metadata of the uploaded file:

| Property      | Description                                             |
|---------------|---------------------------------------------------------|
| FilePath      | The UploadLocation path where the file is uploaded to   |
| Name          | The form field name from the Content-Disposition header |
| FileName      | The file name of the uploaded file                      |
| ContentLength | The size in bytes of the uploaded file                  |
| ContentType   | The Content-Type of the uploaded file                   |

In addition, it also supports `List<string>` or `List<T>` complex types for handling **multiple file uploads**, as done in this case.

All these features work together to achieve our desired result of populating submitted applications in the 
`JobApplicationAttachment` joined table, so their metadata can be browsed, queried and navigated like any other
related data without file system access and without their contents consuming RDBMS resources:

![](/img/pages/locode/talent/job-application-attachments.png)

## Uploading Files from C#

We can see how Locode gives us instant utility and lets us start submitting file attachments with any AutoQuery CRUD DTO, 
but as the feature just uses the standard [HTTP multipart/form-data](https://www.ietf.org/rfc/rfc2388.txt) Content-Type, we can use the 
existing [Service Client APIs](/csharp-client) for uploading files as demonstrated in Talent Blazor's
[FileUploadTests.cs](https://github.com/NetCoreApps/TalentBlazor/blob/main/TalentBlazor.Tests/FileUploadTests.cs)
which uploads a single attachment when creating a Contact with a Profile Image and multiple file attachments when
submitting a Job Application:

```csharp
var profileImg = await ProfileImageUrl.GetStreamFromUrlAsync();
var contact = await client.PostFileWithRequestAsync<Contact>(profileImg, "cody-fisher.png", 
    new CreateContact
    {
        FirstName = "Cody",
        LastName = "Fisher",
        Email = "cody.fisher@gmail.com",
        JobType = "Security",
        PreferredLocation = "Remote",
        PreferredWorkType = EmploymentType.FullTime,
        AvailabilityWeeks = 1,
        SalaryExpectation = 100_000,
        About = "Lead Security Associate",
    }, fieldName:nameof(CreateContact.ProfileUrl));

// contact.ProfileUrl = /profiles/cody-fisher.png

var uploadedImage = await client.BaseUri.CombineWith(contact.ProfileUrl).GetStreamFromUrlAsync();
var coverLetter = new FileInfo($"{AppData}/sample_coverletter.pdf");
var resume = new FileInfo($"{AppData}/sample_resume.pdf");

var attachmentsField = nameof(CreateJobApplication.Attachments);
var uploadAttachments = new UploadFile[] {
    new(coverLetter.Name, coverLetter.OpenRead(), attachmentsField),
    new(resume.Name, coverLetter.OpenRead(), attachmentsField),
    new(contact.ProfileUrl.LastRightPart('/'), uploadedImage, attachmentsField),
};

var jobApp = await client.PostFilesWithRequestAsync<JobApplication>(new CreateJobApplication {
        JobId = 1,
        AppliedDate = DateTime.UtcNow,
        ContactId = contact.Id,
    }, uploadAttachments);

uploadAttachments.Each(x => x.Stream.Dispose());
```

This example also shows APIs are able to submit files from any `Stream` that can be sourced from anywhere,
including the HTTP Response stream of a Remote URI or files from a local hard drive. 

### Using HttpClient MultipartFormDataContent

The introduction of [.NET 6+ JsonApiClient](/csharp-client#jsonapiclient) lets us provide an even more flexible approach by utilizing 
`MultipartFormDataContent()` which we've enhanced with high-level extension methods to enable a Fluent API for constructing 
custom API Requests populated from multiple sources, which can be sent using its `ApiForm*` methods:

```csharp
var profileImg = await ProfileImageUrl.GetStreamFromUrlAsync();
using var createContact = new MultipartFormDataContent()
    .AddParams(new CreateContact
    {
        FirstName = "Cody",
        LastName = "Fisher",
        Email = "cody.fisher@gmail.com",
        JobType = "Security",
        PreferredLocation = "Remote",
        PreferredWorkType = EmploymentType.FullTime,
        AvailabilityWeeks = 1,
        SalaryExpectation = 100_000,
        About = "Lead Security Associate",
    })
    .AddFile(nameof(CreateContact.ProfileUrl), "cody-fisher.png", profileImg);

var contactApi = await client.ApiFormAsync<Contact>(typeof(CreateContact).ToApiUrl(), createContact);
// contactApi.Succeeded = true
var contact = contactApi.Response!;
// contact.ProfileUrl   = /profiles/cody-fisher.png

using var uploadedImage = await client.BaseUri.CombineWith(contact.ProfileUrl).GetStreamFromUrlAsync();
var coverLetter = new FileInfo($"{AppData}/sample_coverletter.pdf");
var resume = new FileInfo($"{AppData}/sample_resume.pdf");

var attachmentsField = nameof(CreateJobApplication.Attachments);
var createJobApp = new MultipartFormDataContent()
    .AddParams(new CreateJobApplication {
        JobId = 1,
        AppliedDate = DateTime.UtcNow,
        ContactId = contact.Id,
    })
    .AddFile(attachmentsField, coverLetter)
    .AddFile(attachmentsField, resume)
    .AddFile(attachmentsField, contact.ProfileUrl.LastRightPart('/'), uploadedImage);

var jobAppApi = await client.ApiFormAsync<JobApplication>(
    typeof(CreateJobApplication).ToApiUrl(), createJobApp);
// jobAppApi.Succeeded = true
var jobApp = jobAppApi.Response!;
```

::: tip
All `JsonApiClient` Async APIs also have 
[safe sync equivalents](/csharp-client#safe-sync-httpclient-apis) when access outside an async method is needed 
:::

### Versatile Multi Part Content Type APIs

[AutoQueryCrudTests.References.cs](https://github.com/ServiceStack/ServiceStack/blob/main/ServiceStack/tests/ServiceStack.WebHost.Endpoints.Tests/AutoQueryCrudTests.References.cs)
also showcases how we can take advantage of `MultipartFormDataContent` to construct custom requests using a combination
of different Content Type sources, including single and multiple file attachments within a single request:

```csharp
public class MultipartRequest : IPost, IReturn<MultipartRequest>
{
    public int Id { get; set; }
    public string String { get; set; }
    
    // Complex types sent as JSV by default
    public Contact Contact { get; set; }
    
    [MultiPartField(MimeTypes.Json)]
    public PhoneScreen PhoneScreen { get; set; }
    
    [MultiPartField(MimeTypes.Csv)]
    public List<Contact> Contacts { get; set; }
    
    [UploadTo("profiles")]
    public string ProfileUrl { get; set; }
    
    [UploadTo("applications")]
    public List<UploadedFile> UploadedFiles { get; set; } 
}
```

[Complex types are sent using JSV](/serialization-deserialization) by default which is a
more human & wrist-friendly and more efficient format than JSON, however we could also take advantage of the flexibility
in HTTP **multipart/form-data** requests to construct an HTTP API Request utilizing multiple Content-Type's optimized
for the data we're sending, e.g:

- JSON/JSV more optimal for hierarchical graph data 
- CSV more optimal for sending tabular data
- File Uploads are more optimal for sending large files

To facilitate this in our Server APIs we can use `[MultiPartField]` attribute to instruct ServiceStack which registered
serializer it should use to deserialize the form-data payload, whilst we can continue using the generic `[UploadTo]`
attribute in normal APIs to handle our File Uploads and populate the Request DTO with the uploaded file metadata.

Our `MultipartFormDataContent` extension methods simplifies our client logic by allowing us to easily populate this 
custom request in a single Fluent construction expression:

```csharp
using var content = new MultipartFormDataContent()
    .AddParam(nameof(MultipartRequest.Id), 1)
    .AddParam(nameof(MultipartRequest.String), "foo")
    .AddParam(nameof(MultipartRequest.Contact), 
        new Contact { Id = 1, FirstName = "First", LastName = "Last" })
    .AddJsonParam(nameof(MultipartRequest.PhoneScreen), 
        new PhoneScreen { Id = 3, JobApplicationId = 1, Notes = "The Notes"})
    .AddCsvParam(nameof(MultipartRequest.Contacts), new[] {
        new Contact { Id = 2, FirstName = "First2", LastName = "Last2" },
        new Contact { Id = 3, FirstName = "First3", LastName = "Last3" },
    })
    .AddFile(nameof(MultipartRequest.ProfileUrl), "profile.txt", file1Stream)
    .AddFile(nameof(MultipartRequest.UploadedFiles), "uploadedFiles1.txt", file2Stream)
    .AddFile(nameof(MultipartRequest.UploadedFiles), "uploadedFiles2.txt", file3Stream));

var api = await client.ApiFormAsync<MultipartRequest>(typeof(MultipartRequest).ToApiUrl(), content);
if (!api.Succeeded) api.Error.PrintDump();
```

## Uploading Files from JS/TypeScript

Similarly, we can populate custom requests by either programmatically constructing the 
[FormData](https://developer.mozilla.org/en-US/docs/Web/API/FormData) object, which also benefits from native integration
in browsers where it can be populated directly from an HTML Form:

```ts
let client = new JsonServiceClient(BaseUrl)
let formData = new FormData(document.forms[0])
let api = await client.apiForm(new MultipartRequest(), formData)
```

Where `apiForm` can be used to submit `FormData` requests for normal API Requests, or `apiFormVoid` for `IReturnVoid` API requests.

## API Keys protected managed File Uploads

Managed file uploads can also be protected with [Identity Auth API Keys](/auth/apikeys) by setting `requireApiKey:`, e.g:

```csharp
var fileFs = new FileSystemVirtualFiles(context.HostingEnvironment.ContentRootPath);
services.AddPlugin(new FilesUploadFeature(
    new UploadLocation("pub", 
        fileFs,
        readAccessRole: RoleNames.AllowAnon,
        requireApiKey: new(),
        maxFileBytes: 10 * 1024 * 1024,
        resolvePath:ctx => "pub".CombineWith(ctx.Request.GetApiKey().Key, ctx.FileName)),
    new UploadLocation("secure", 
        fileFs,
        requireApiKey: new("manager"),
        maxFileBytes: 10 * 1024 * 1024,
        resolvePath:ctx => "secure".CombineWith(ctx.Request.GetApiKey().Key, ctx.FileName))
));
```

This configuration shows a **pub** upload location allowing for anonymous reads but all writes requiring an API Key. 

The **secure** upload location requires an API key with a **manager** [Scope](/auth/apikeys#scopes) which is required for both read and write access.

In both cases the upload locations will store the files in a sub-directory named after API Key used to upload it.

## Substitutable Virtual File Providers

We've also created the [File Blazor Demo](https://github.com/NetCoreApps/FileBlazor) to further demonstrate the versatility of the 
`FilesUploadFeature` to seamlessly manage uploading files to multiple different locations using different
Virtual Files providers that's still able to utilize the same custom configuration and validation in its
[Configure.AppHost.cs](https://github.com/NetCoreApps/FileBlazor/blob/main/FileBlazor/Configure.AppHost.cs):

```csharp
.ConfigureServices((context, services) =>
{
    // Configure ASP.NET Core IOC Dependencies
    //...
    var awsAccessKeyId = Environment.GetEnvironmentVariable("AWS_ACCESS_KEY_ID") ??
                         Environment.GetEnvironmentVariable("LOCAL_AWS_ACCESS_KEY_ID");
    var awsSecretAccessKey = Environment.GetEnvironmentVariable("AWS_SECRET_ACCESS_KEY") ??
                             Environment.GetEnvironmentVariable("LOCAL_AWS_SECRET_ACCESS_KEY");
    var azureBlobConnString = Environment.GetEnvironmentVariable("AZURE_BLOB_CONNECTION_STRING") ??
                              Environment.GetEnvironmentVariable("LOCAL_AZURE_BLOB_CONNECTION_STRING");

    var appFs = new FileSystemVirtualFiles(context.HostingEnvironment.ContentRootPath.CombineWith("App_Data").AssertDir());
    var s3Client = new AmazonS3Client(awsAccessKeyId, awsSecretAccessKey, RegionEndpoint.USEast1);
    var s3DataVfs = new S3VirtualFiles(s3Client, "file-blazor-demo");

    if(string.IsNullOrEmpty(azureBlobConnString))
        Log.Warn("Started without Azure Blob Storage configured.");
    
    var uploadLocations = new[] {
        new UploadLocation("s3", s3DataVfs,
            readAccessRole: RoleNames.AllowAnon, resolvePath: ResolveUploadPath,
            validateUpload: ValidateUpload, validateDownload: ValidateDownload,
            maxFileBytes: 10 * 1024 * 1024),
        new UploadLocation("fs", appFs,
            readAccessRole: RoleNames.AllowAnon, resolvePath: ResolveUploadPath,
            validateUpload: ValidateUpload, validateDownload: ValidateDownload,
            maxFileBytes: 10 * 1024 * 1024),
        // User profiles
        new UploadLocation("users", appFs, allowExtensions: FileExt.WebImages,
            resolvePath: ctx => $"/profiles/users/{ctx.UserAuthId}.{ctx.FileExtension}",
            maxFileBytes: 10 * 1024 * 1024)
    };

    if (!string.IsNullOrEmpty(azureBlobConnString))
    {
        var azureBlobVfs = new AzureBlobVirtualFiles(azureBlobConnString, "fileblazordemo");
        uploadLocations = uploadLocations.Prepend(new UploadLocation("azure", azureBlobVfs,
            readAccessRole: RoleNames.AllowAnon, resolvePath: ResolveUploadPath,
            validateUpload: ValidateUpload, validateDownload: ValidateDownload,
            maxFileBytes: 10 * 1024 * 1024)).ToArray();
    }
    
    var uploadPlugin = new FilesUploadFeature(uploadLocations);
    services.AddPlugin(uploadPlugin);
});
//...
private static string ResolveUploadPath(FilesUploadContext ctx)
{
    if (ctx.Dto is IFileItemRequest { FileAccessType: { } } createFile)
    {
        return createFile.FileAccessType != FileAccessType.Private
            ? ctx.GetLocationPath($"/{createFile.FileAccessType}/{ctx.FileName}")
            : ctx.GetLocationPath($"/{createFile.FileAccessType}/{ctx.UserAuthId}/{ctx.FileName}");
    }
    throw HttpError.BadRequest("Invalid file creation request.");
}

private static void ValidateUpload(IRequest request, IHttpFile file)
{
    if (request.Dto is IFileItemRequest createFile)
    {
        var accessType = createFile.FileAccessType;
        var ext = file.FileName.LastRightPart('.');
        if (accessType == FileAccessType.Team && ext != null && FileExt.WebImages.Contains(ext) == false)
            throw new ArgumentException("Supported file extensions: {0}".LocalizeFmt(request,
                string.Join(", ", FileExt.WebImages.Map(x => '.' + x).OrderBy(x => x))), file.FileName);
    }
    else
        throw new HttpError("Invalid request.");
}
//...
```

### Memory Virtual File Sources

ServiceStack AppHost's are configured with an empty Memory VFS which can be used to transiently prepopulate App files from external sources on Startup or maintain temporary working files with the same lifetime of the App without needing to persist to disk.

They're also a great solution for Integration Testing managed file access without creating any persistent artifacts as done in
[AutoQueryCrudTests.References.cs](https://github.com/ServiceStack/ServiceStack/blob/main/ServiceStack/tests/ServiceStack.WebHost.Endpoints.Tests/AutoQueryCrudTests.References.cs)

```csharp
var memFs = new MemoryVirtualFiles();
services.AddPlugin(new FilesUploadFeature(
    new UploadLocation("profiles", memFs),
    new UploadLocation("applications", memFs, maxFileCount: 3, maxFileBytes: 10_000_000,
        resolvePath: ctx => ctx.GetLocationPath((ctx.Dto is CreateJobApplication create
            ? $"job/{create.JobId}"
            : $"app/{ctx.Dto.GetId()}") + $"/{ctx.DateSegment}/{ctx.FileName}"),
        readAccessRole:RoleNames.AllowAnon, writeAccessRole:RoleNames.AllowAnon)
));
```

## Configuring Database-First Apps

As [Database-First Types](/locode/database-first) are only generated & exist at runtime they can't be explicitly annotated
with `[UploadTo]` attributes, instead they can be added dynamically at runtime by using AutoQuery's  `TypeFilter` which 
is invoked for all Types including Request and Response DTO types. 

An [example of this](https://github.com/NetCoreApps/NorthwindAuto/blob/master/Configure.AppHost.cs) can be found in the 
`Northwind` Locode Database-First demo which uses `type.Name == "Employee"` to match on the `Employee` Data Model and 
`IsCrudCreateOrUpdate("Employee")` Metadata Type extension method to target its `CreateEmployee` and `UpdateEmployee` CRUD APIs: 

```csharp
TypeFilter = (type, req) =>
{
    if (type.Name == "Employee")
    {
        // Remove embedded Blob column from Data Model Type 
        type.Properties.RemoveAll(x => x.Name == "Photo");
    }
    if (type.IsCrudCreateOrUpdate("Employee"))
    {
        // Add `[Input]` and `[UploadTo]` attributes to `PhotoPath` managed file upload property
        type.Property("PhotoPath")
            .AddAttribute(new InputAttribute { Type = Input.Types.File })
            .AddAttribute(new UploadToAttribute("employees"));
    }
    //...
}
```

The result of this is converting the Northwind Database from using the `Photo` blob column to persist image bit maps
and instead uses the `PhotoPath` column to maintain an external file reference to their Profile Photo which is
managed by the `FilesUploadFeature` to persist images to its configured `FileSystemVirtualFiles` virtual file source.

## Files Upload Transformer

[Blazor Diffusion](/blazor-diffusion) uses the Managed Files Upload Feature configured in [Configure.AppHost.cs](https://github.com/NetCoreApps/BlazorDiffusion/blob/main/BlazorDiffusion/Configure.AppHost.cs) for all its website File Uploads:

```csharp
var r2Client = new AmazonS3Client(appConfig.R2AccessId, appConfig.R2AccessKey, new AmazonS3Config
{
    ServiceURL = $"https://{appConfig.R2Account}.r2.cloudflarestorage.com"
});
services.AddSingleton(r2Client);
var localFs = new FileSystemVirtualFiles(context.HostingEnvironment.ContentRootPath.CombineWith("App_Files").AssertDir());
var appFs = VirtualFiles = hasR2 ? new R2VirtualFiles(r2Client, appConfig.ArtifactBucket) : localFs;
services.AddPlugin(new FilesUploadFeature(
    new UploadLocation("artifacts", appFs,
        readAccessRole: RoleNames.AllowAnon,
        maxFileBytes: AppData.MaxArtifactSize),
    new UploadLocation("avatars", appFs, allowExtensions: FileExt.WebImages,
        // Use unique URL to invalidate CDN caches
        resolvePath: ctx => X.Map((CustomUserSession)ctx.Session,
            x => $"/avatars/{x.RefIdStr[..2]}/{x.RefIdStr}/{ctx.FileName}")!,
        maxFileBytes: AppData.MaxAvatarSize,
        transformFile: ImageUtils.TransformAvatarAsync)
));
```

It utilizes the new **transformFile:** option to transform an uploaded file and save a reference to the transformed file instead. This is used to only save a reference to the **128x128** resized avatar used by the App, whilst still persisting the original uploaded image in a [Background MQ](/background-mq) task in case a higher resolution of their avatar is needed later.

```csharp
public class ImageDetails
{
    public static async Task<IHttpFile?> TransformAvatarAsync(FilesUploadContext ctx)
    {
        var originalMs = await ctx.File.InputStream.CopyToNewMemoryStreamAsync();

        // Offload persistance of original image to background task
        using var mqClient = HostContext.AppHost.GetMessageProducer(ctx.Request);
        mqClient.Publish(new DiskTasks {
            SaveFile = new() {
                FilePath = ctx.Location.ResolvePath(ctx),
                Stream = originalMs,
            }
        });

        var resizedMs = await CropAndResizeAsync(originalMs, 128, 128, PngFormat.Instance);

        return new HttpFile(ctx.File)
        {
            FileName = $"{ctx.FileName.LastLeftPart('.')}_128.{ctx.File.FileName.LastRightPart('.')}",
            ContentLength = resizedMs.Length,
            InputStream = resizedMs,
        };
    }

    public static async Task<MemoryStream> CropAndResizeAsync(Stream inStream, int width, int height, IImageFormat format)
    {
        var outStream = new MemoryStream();
        var image = await Image.LoadAsync(inStream);
        using (image)
        {
            var clone = image.Clone(context => context
                .Resize(new ResizeOptions {
                    Mode = ResizeMode.Crop,
                    Size = new Size(width, height),
                }));
            await clone.SaveAsync(outStream, format);
        }
        outStream.Position = 0;
        return outStream;
    }
}
```


# Files Blazor
Source: https://docs.servicestack.net/locode/files-blazor

<main class="not-prose hide-title mt-8 mx-auto max-w-7xl px-4 sm:mt-12">
    <div class="text-center">
        <h1 class="text-4xl tracking-tight font-extrabold text-gray-900 sm:text-5xl md:text-6xl">
            <span class="block xl:inline">File Blazor </span>
            <span class="block text-indigo-600 xl:inline">Managed File Upload Example</span>
        </h1>
        <p class="mt-3 max-w-md mx-auto text-base text-gray-500 sm:text-lg md:mt-5 md:text-xl md:max-w-3xl">ServiceStack's 
            <code class="bg-blue-50 text-blue-500 py-1 px-2 rounded">FileUploadFeature</code>
            provides an easy and flexible way to create API services backed by either popular cloud solutions like AWS S3, Azure Blob Storage, or your own file system.
        </p>
    </div>
</main>
<div class="not-prose relative py-8 bg-white overflow-hidden">
    <div class="relative px-4 sm:px-6 lg:px-8">
        <div class="text-lg max-w-prose mx-auto">
            <h1>
                <span class="block text-base text-center text-indigo-600 font-semibold tracking-wide uppercase">Introducing</span>
                <span class="mt-2 block text-3xl text-center leading-8 font-extrabold tracking-tight text-gray-900 sm:text-4xl">
                    <a href="https://github.com/NetCoreApps/FileBlazor">NetCoreApps/FileBlazor</a>                    
                </span>
            </h1>
            <p class="mt-8 text-xl text-gray-500 leading-8">
                <a href="https://github.com/NetCoreApps/FileBlazor">NetCoreApps/FileBlazor</a> is a Blazor Demo utilizing the 
                <code class="bg-blue-50 text-blue-500 py-1 px-2 rounded">FileUploadFeature</code>
                plugin to provide an easy and flexible solution for quickly creating APIs services for uploading/downloading files to a variety of storage types.
            </p>
        </div>
    </div>
</div>

<figure class="m-2">
    <img src="/img/pages/locode/files/fileupload-config-plugin.png" alt="">
    <figcaption>Configuration of IVirtualFiles and FileUploadPlugin</figcaption>
</figure>

By utilizing **AutoQuery** and **Locode** features, you also get a generated UI to use for back office staff or to use for prototyping. In this demo we configure three different storage types which integrate directly with your own database tables.

- AWS S3 Bucket
- Azure Blob Storage Container
- Local Application File System

<figure class="m-2">
    <img src="/img/pages/locode/files/fileupload-datamodel.png" alt="">
    <figcaption>Define your database tables to store file metadata.</figcaption>
</figure>

The FileUploadFeature plugin uses the ServiceStack IVirtualFiles abstraction where multiple named providers can be used and referenced against your database model. Your own database stores metadata about each file including a reference to HTTP file path where the file where it can be downloaded.

## Driven by your request DTOs

Your table data for the files in this demo are then shared using **AutoQuery** services. AutoQuery provides the overridable service implementation to manage this data, this is where you can link your FileUploadFeature to specific table data using the `UploadTo` attribute.

<figure class="m-2">
    <img src="/img/pages/locode/files/fileupload-create-dto.png" alt="">
    <figcaption>Define your request Data Transfer Objects (DTOs) and use `UploadTo` with the related named UploadLocation.</figcaption>
</figure>

## Upload Files Using Locode

ServiceStack Locode App integrates with the FileUploadFeature plugin to enable a way to manage your files straight away.

<figure>
    <img src="/img/pages/locode/files/locode-app-create-s3.png" alt="">
    <figcaption>Instant upload form using Locode App.</figcaption>
</figure>

## Overridable filters in the plugin

The UploadFeaturePlugin provides overridable options to better control upload/download rules. In this demo, `Public`, `Team` and `Private` files are stored in single table for each upload location.

Access rules are configured for each of the upload locations independently using the following plugin options.

- **readAccessRole** - Can limit read access to specific user roles
- **resolvePath** - Control how the upload path is created
- **validateUpload** - Filter upload requests
- **validateDownload** - Filter download requests

## Integrate API services with a custom UI

Since AutoQuery services are ServiceStack services, they benefit from being highly interoperable. This FileBlazor demo uses native Blazor components to upload to the generated API services providing a user friendly drag and drop interface.

Navigate to the public [S3](/aws/public), [Azure](/azure/public) or [File System](/filesystem/public)
file galleries on the left to preview files without authenticating, or login to see the different file access types and upload files yourself.

<div class="not-prose my-8 flex justify-center">
    <a href="https://github.com/NetCoreApps/FileBlazor" 
        class="hover:text-black inline-flex no-underline hover:no-underline items-center px-6 py-3 border border-gray-300 shadow text-base font-medium rounded-md text-gray-700 bg-white hover:bg-gray-50 focus:outline-none focus:ring-2 focus:ring-offset-2 focus:ring-indigo-500">
        <svg class="w-6 h-6" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24">
            <g fill="none">
                <path fill-rule="evenodd" clip-rule="evenodd" d="M12 0C5.37 0 0 5.37 0 12c0 5.31 3.435 9.795 8.205 11.385c.6.105.825-.255.825-.57c0-.285-.015-1.23-.015-2.235c-3.015.555-3.795-.735-4.035-1.41c-.135-.345-.72-1.41-1.23-1.695c-.42-.225-1.02-.78-.015-.795c.945-.015 1.62.87 1.845 1.23c1.08 1.815 2.805 1.305 3.495.99c.105-.78.42-1.305.765-1.605c-2.67-.3-5.46-1.335-5.46-5.925c0-1.305.465-2.385 1.23-3.225c-.12-.3-.54-1.53.12-3.18c0 0 1.005-.315 3.3 1.23c.96-.27 1.98-.405 3-.405s2.04.135 3 .405c2.295-1.56 3.3-1.23 3.3-1.23c.66 1.65.24 2.88.12 3.18c.765.84 1.23 1.905 1.23 3.225c0 4.605-2.805 5.625-5.475 5.925c.435.375.81 1.095.81 2.22c0 1.605-.015 2.895-.015 3.3c0 .315.225.69.825.57A12.02 12.02 0 0 0 24 12c0-6.63-5.37-12-12-12z" fill="currentColor"></path>
            </g>
        </svg><span class="mx-2">FileBlazor on GitHub</span>
    </a>
</div>


# File System Managed File Uploads
Source: https://docs.servicestack.net/locode/files-upload-filesystem

The `FileUploadFeature` plugin supports having multiple `UploadLocations` configured at once, and each UploadLocation can use a different implementation of the `IVirtualFiles` interface.

This can be added in your AppHost Configure method or IHostingStartup ConfigureAppHost method. Each UploadLocation requires a Name string and an instance of an IVirtualFiles provider.

```csharp
var appFs = new FileSystemVirtualFiles(
    ContentRootDirectory.RealPath.CombineWith("App_Data").AssertDir()
);

Plugins.Add(new FilesUploadFeature(
  new UploadLocation("fs", appFs,
      readAccessRole: RoleNames.AllowAnon,
      resolvePath: ResolveUploadPath,
      validateUpload: ValidateUpload,
      validateDownload: ValidateDownload)
));
```

In this example of integrating local file system, we initialize the IVirtualFiles of `FileSystemVirtualFiles`, passing the local file path where you want the uploaded files to be stored.


## Using File Upload Locations in APIs

With just the above configured, we can now use them in our APIs. The `[UploadTo("name")]` attribute is used with an AutoQuery Request DTO and related database model class. For example, the `FileSystemFileItem` table contains metadata about file access and is referenced by `FileSystemFile` table which contains our file metadata.

In the `FileBlazor` demo, we store the file metadata in one table which is related back to another to store additional metadata we use to limit file access.

```csharp
public class FileSystemFile
{
    [AutoIncrement]
    public int Id { get; set; }
    public string FileName { get; set; }
    
    public string FilePath { get; set; }
    public string ContentType { get; set; }
    
    public long ContentLength { get; set; }
    
    [Reference(typeof(FileSystemFileItem))]
    public int SharedFileId { get; set; }
}

public class FileSystemFileItem
{
    [AutoIncrement]
    public int Id { get; set; }
    public FileAccessType? FileAccessType { get; set; }
    
    [Reference]
    public FileSystemFile AppFile { get; set; }
    [References(typeof(AppUser))]
    public int AppUserId { get; set; }
    
    [Reference]
    public AppUser AppUser { get; set; }
    
    public string RoleName { get; set; }
}
```

The `FileSystemFile` data is populated automatically when a file is uploaded while creating an `FileSystemFileItem`. We apply to `[UploadTo("azure")]` attribute to the `ICreateDb` DTO to the matching type and name for the `FileSystemFile`. The "fs" name matches the UploadLocation we previously configured in the FilesUploadFeature. This is what determines where the upload file is stored.

```csharp
public class CreateFileSystemFileItem : ICreateDb<FileSystemFileItem>, IReturn<FileSystemFileItem>
{
    public FileAccessType? FileAccessType { get; set; }
    public string? RoleName { get; set; }
    
    [Input(Type = "file", UploadTo("fs")]
    public FileSystemFileItem AppFile { get; set; }
{
```

We also apply the `[Input(Type="file")]` attribute to enhance the Locode App so we can upload files directly from the Locode generated user interface.

![](../img/pages/locode/files/locode-app-create-fs.png)

## Blazor Custom Client Upload

If you need to provide a custom UI, these services accessible from multiple languages since they are HTTP services.

For example, the `FileBlazor` demo provides the ability to drag & drop files to upload. It does this using the ServiceStack JsonApiClient to MultipartFormDataContent which includes the request and the file to upload.

```csharp
async Task UploadFile(InputFileChangeEventArgs e)
{
    var request = new CreateFileSystemFileItem
    {
        FileAccessType = FileAccessType.Private
    };
    
    using var content = new MultipartFormDataContent()
        .AddParams(request);
    
    var file = e.File;
    using var stream = file.OpenReadStream(maxFileSize);
    using var ms = new MemoryStream();
    await stream.CopyToAsync(ms);
    ms.Position = 0;
    content.AddFile("AppFile", file.Name, ms, file.ContentType);
    
    var ap = await jsonApiClient.ApiFormAsync<CreateFileSystemFileItem>(typeof(CreateFileSystemFileItem).ToApiUrl(), content);
    
    if(!api.Succeeded)
        errorStatus = api.Error;
}
```


# AWS S3 Managed File Uploads
Source: https://docs.servicestack.net/locode/files-upload-aws

The `FileUploadFeature` plugin supports having multiple `UploadLocations` configured at once, and each UploadLocation can use a different implementation of the `IVirtualFiles` interface.

This can be added in your AppHost Configure method or IHostingStartup ConfigureAppHost method. Each UploadLocation requires a Name string and an instance of an IVirtualFiles provider.

```csharp
var s3Client = new AmazonS3Client();
var s3Vfs = new S3VirtualFiles(s3Client,"bucket-name");

Plugins.Add(new FilesUploadFeature(
  new UploadLocation("s3", s3Vfs,
      readAccessRole: RoleNames.AllowAnon,
      resolvePath: ResolveUploadPath,
      validateUpload: ValidateUpload,
      validateDownload: ValidateDownload)
));
```

In this example of integrating AWS S3, we initialize the AWS SDK AmazonS3Client, pass it to our IVirtualFiles implementation, in this case S3VirtualFiles and specify a bucket name.

To use the `S3VirtualFiles` you will need the `ServiceStack.Aws` NuGet package:

:::copy
`<PackageReference Include="ServiceStack.Aws" Version="8.*" />`
:::

## Using File Upload Locations in APIs

With just the above configured, we can now use them in our APIs. The `[UploadTo("name")]` attribute is used with an AutoQuery Request DTO and related database model class. For example, the S3FileItem table contains metadata about file access and is referenced by S3File table which contains our file metadata.

In the `FileBlazor` demo, we store the file metadata in one table which is related back to another to store additional metadata we use to limit file access.

```csharp
public class S3File
{
    [AutoIncrement]
    public int Id { get; set; }
    public string FileName { get; set; }
    
    public string FilePath { get; set; }
    public string ContentType { get; set; }
    
    public long ContentLength { get; set; }
    
    [Reference(typeof(S3FileItem))]
    public int SharedFileId { get; set; }
}

public class S3FileItem
{
    [AutoIncrement]
    public int Id { get; set; }
    public FileAccessType? FileAccessType { get; set; }
    
    [Reference]
    public S3File AppFile { get; set; }
    [References(typeof(AppUser))]
    public int AppUserId { get; set; }
    
    [Reference]
    public AppUser AppUser { get; set; }
    
    public string RoleName { get; set; }
}
```

The `S3File` data is populated automatically when a file is uploaded while creating an `S3FileItem`. We apply to `[UploadTo("s3")]` attribute to the `ICreateDb` DTO to the matching type and name for the `S3File`. The "s3" name matches the UploadLocation we previously configured in the FilesUploadFeature. This is what determines where the upload file is stored.

```csharp
public class CreateS3FileItem : ICreateDb<S3FileItem>, IReturn<S3FileItem>
{
    public FileAccessType? FileAccessType { get; set; }
    public string? RoleName { get; set; }
    
    [Input(Type = "file", UploadTo("s3")]
    public S3File AppFile { get; set; }
{
```

We also apply the `[Input(Type="file")]` attribute to enhance the Locode App so we can upload files directly from the Locode generated user interface.

![](../img/pages/locode/files/locode-app-create-s3.png)

## Blazor Custom Client Upload

If you need to provide a custom UI, these services accessible from multiple languages since they are HTTP services.

For example, the `FileBlazor` demo provides the ability to drag & drop files to upload. It does this using the ServiceStack JsonApiClient to MultipartFormDataContent which includes the request and the file to upload.

```csharp
async Task UploadFile(InputFileChangeEventArgs e)
{
    var request = new CreateS3FileItem
    {
        FileAccessType = FileAccessType.Private
    };
    
    using var content = new MultipartFormDataContent()
        .AddParams(request);
    
    var file = e.File;
    using var stream = file.OpenReadStream(maxFileSize);
    using var ms = new MemoryStream();
    await stream.CopyToAsync(ms);
    ms.Position = 0;
    content.AddFile("AppFile", file.Name, ms, file.ContentType);
    
    var ap = await jsonApiClient.ApiFormAsync<CreateS3FileItem>(typeof(CreateS3FileItem).ToApiUrl(), content);
    
    if(!api.Succeeded)
        errorStatus = api.Error;
}
```


# Azure Blob Storage Managed File Uploads
Source: https://docs.servicestack.net/locode/files-upload-azure

The `FileUploadFeature` plugin supports having multiple `UploadLocations` configured at once, and each UploadLocation can use a different implementation of the `IVirtualFiles` interface.

This can be added in your AppHost Configure method or IHostingStartup ConfigureAppHost method. Each UploadLocation requires a Name string and an instance of an IVirtualFiles provider.

```csharp
var azureBlobConnString = ... // Fetch from config/environment variables.
var azureBlobVfs = new AzureBlobVirtualFiles(azureBlobConnString, "my-container-name");

Plugins.Add(new FilesUploadFeature(
  new UploadLocation("azure", azureBlobVfs,
      readAccessRole: RoleNames.AllowAnon,
      resolvePath: ResolveUploadPath,
      validateUpload: ValidateUpload,
      validateDownload: ValidateDownload)
));
```

In this example of integrating Azure Blob Storage, we initialize the `AzureBlobVirtualFiles`, pass it to our IVirtualFiles implementation, and specify a container name.

To use the `AzureBlobVirtualFiles` you will need the `ServiceStack.Azure` NuGet package:

:::copy
`<PackageReference Include="ServiceStack.Azure" Version="8.*" />`
:::

## Using File Upload Locations in APIs

With just the above configured, we can now use them in our APIs. The `[UploadTo("name")]` attribute is used with an AutoQuery Request DTO and related database model class. For example, the AzureFileItem table contains metadata about file access and is referenced by AzureFile table which contains our file metadata.

In the `FileBlazor` demo, we store the file metadata in one table which is related back to another to store additional metadata we use to limit file access.

```csharp
public class AzureFile
{
    [AutoIncrement]
    public int Id { get; set; }
    public string FileName { get; set; }
    
    public string FilePath { get; set; }
    public string ContentType { get; set; }
    
    public long ContentLength { get; set; }
    
    [Reference(typeof(AzureFileItem))]
    public int SharedFileId { get; set; }
}

public class AzureFileItem
{
    [AutoIncrement]
    public int Id { get; set; }
    public FileAccessType? FileAccessType { get; set; }
    
    [Reference]
    public AzureFile AppFile { get; set; }
    [References(typeof(AppUser))]
    public int AppUserId { get; set; }
    
    [Reference]
    public AppUser AppUser { get; set; }
    
    public string RoleName { get; set; }
}
```

The `AzureFile` data is populated automatically when a file is uploaded while creating an `AzureFileItem`. We apply to `[UploadTo("azure")]` attribute to the `ICreateDb` DTO to the matching type and name for the `AzureFile`. The "azure" name matches the UploadLocation we previously configured in the FilesUploadFeature. This is what determines where the upload file is stored.

```csharp
public class CreateAzureFileItem : ICreateDb<AzureFileItem>, IReturn<AzureFileItem>
{
    public FileAccessType? FileAccessType { get; set; }
    public string? RoleName { get; set; }
    
    [Input(Type = "file", UploadTo("azure")]
    public AzureFileItem AppFile { get; set; }
{
```

We also apply the `[Input(Type="file")]` attribute to enhance the Locode App so we can upload files directly from the Locode generated user interface.

![](../img/pages/locode/files/locode-app-create-azure.png)

## Blazor Custom Client Upload

If you need to provide a custom UI, these services accessible from multiple languages since they are HTTP services.

For example, the `FileBlazor` demo provides the ability to drag & drop files to upload. It does this using the ServiceStack JsonApiClient to MultipartFormDataContent which includes the request and the file to upload.

```csharp
async Task UploadFile(InputFileChangeEventArgs e)
{
    var request = new CreateAzureFileItem
    {
        FileAccessType = FileAccessType.Private
    };
    
    using var content = new MultipartFormDataContent()
        .AddParams(request);
    
    var file = e.File;
    using var stream = file.OpenReadStream(maxFileSize);
    using var ms = new MemoryStream();
    await stream.CopyToAsync(ms);
    ms.Position = 0;
    content.AddFile("AppFile", file.Name, ms, file.ContentType);
    
    var ap = await jsonApiClient.ApiFormAsync<CreateAzureFileItem>(typeof(CreateAzureFileItem).ToApiUrl(), content);
    
    if(!api.Succeeded)
        errorStatus = api.Error;
}
```


# Auditing
Source: https://docs.servicestack.net/locode/auditing

A benefit to AutoQuery's structured declarative approach to its CRUD APIs is that it's better able to enable high-level 
generic functionality that can benefit all CRUD APIs. AutoQuery CRUD's 
[Executable Audit Log](/autoquery/audit-log) is an example of this which makes use of
[AutoQuery CRUD Attributes](/autoquery/crud#autoquery-crud-attributes)
to capture every CRUD operation responsible for any modifications to its underlying RDBMS tables.

We'll explore an overview of this feature by applying it to our simple Bookings table from the
[AutoQuery CRUD Bookings Demo](/autoquery/crud-bookings) included in all
[jamstacks.net](https://jamstacks.net/) project templates there by adding the ability to track all CRUD API operations 
and with it all modifications made to our `Booking` RDBMS table.

## Enabling Crud Events

First thing we need to do is register the `ICrudEvents` dependency in our App's IOC, in this case uses `OrmLiteCrudEvents`
to store all Audit Information in the `CrudEvent` table of our configured database:

```csharp
public class ConfigureAutoQuery : IHostingStartup
{
    public void Configure(IWebHostBuilder builder) => builder
        .ConfigureServices(services => {
            // Enable Audit History
            services.AddSingleton<ICrudEvents>(c =>
                new OrmLiteCrudEvents(c.Resolve<IDbConnectionFactory>()));
        })
        .ConfigureAppHost(appHost => {
            appHost.Plugins.Add(new AutoQueryFeature {
                MaxLimit = 1000,
                //IncludeTotal = true,
            });
            
            // Create CrudEvent if it doesn't exist
            appHost.Resolve<ICrudEvents>().InitSchema();
        });
}
```

As `ICrudEvents` stores all events in a separate table, we also need to use `InitSchema` above to create the `CrudEvent`
table if it doesn't already exist.

## Enabling Audit History Tracking on Data Models and APIs

With `ICrudEvents` registered, we can now choose which Data Models we want to enable Audit Tracking on by having them
inherit from the built-in `AuditBase` class:

```csharp
public class Booking : AuditBase
{
    [AutoIncrement]
    public int Id { get; set; }
    public string Name { get; set; }
    public RoomType RoomType { get; set; }
    public int RoomNumber { get; set; }
    public DateTime BookingStartDate { get; set; }
    public DateTime? BookingEndDate { get; set; }
    public decimal Cost { get; set; }
    public string Notes { get; set; }
    public bool? Cancelled { get; set; }
}
```

This will extend our RDBMS tables with additional Audit Info to capture who and when bookings were **Created**, 
**Last Modified** and **Deleted** (when using Soft Deletes):

```csharp
public abstract class AuditBase
{
    public DateTime CreatedDate { get; set; }
    public string CreatedBy { get; set; }
    public DateTime ModifiedDate { get; set; }
    public string ModifiedBy { get; set; }
    public DateTime? DeletedDate { get; set; }
    public string DeletedBy { get; set; }
}
```

Even without needing to inspect the audit history table, capturing this info on its own provides valuable insight into 
the provenance of each booking.

### Configuring CRUD APIs

But to be able to maintain a complete executable audit log we need to capture every CRUD API and modification done on
our `Booking` table which we can do by annotating our Booking CRUD APIs with 
[AutoApply](/autoquery/crud#apply-generic-crud-behaviors) attribute which annotates our
APIs with the behavior we want to apply to them.

For the Audit feature, this behavior is implemented in the pre-registered 
[AuditAutoCrudMetadataFilter](/autoquery/crud#auditautocrudmetadatafilter) which dynamically
adds attributes to annotated APIs to achieve it's desired behavior. By primarily using the
[[AutoPopulate]](/autoquery/crud#autopopulate) attribute to populate the Audit Info and
[[AutoFilter]](/autoquery/crud#autofilter) attribute to ensure our Query APIs don't
return any **Soft Deleted** records.

Essentially `[AutoApply]` enables us to define a single attribute as a substitute for defining the multiple compound attributes 
to populate the Audit Info and Filter queries.

The appropriate `[AutoApply]` behavior needs to be added on all the CRUD APIs for the data models we want Audit History
tracking enabled on, e.g:

```csharp
[AutoApply(Behavior.AuditQuery)]
public class QueryBookings : QueryDb<Booking>
{
    //...
}

[AutoApply(Behavior.AuditCreate)]
public class CreateBooking
    : ICreateDb<Booking>, IReturn<IdResponse>
{
    //...
}

[AutoApply(Behavior.AuditModify)]
public class UpdateBooking
    : IPatchDb<Booking>, IReturn<IdResponse>
{
    //...
}

[AutoApply(Behavior.AuditSoftDelete)]
public class DeleteBooking : IDeleteDb<Booking>, IReturnVoid
{
    //...
}
```

::: tip
Use `Behavior.AuditDelete` instead if you prefer your delete operations resulted in permanent hard deletes 
:::

## Audit Info in Locode

The `AutoQueryFeature.AccessRole` determines the accessibility of the CRUD Event APIs that Locode uses to display the
Audit History logs for each entity, which by default is restricted to **Admin** users who will be able to view the
Audit History of each record at the bottom of its **Edit** Form.

With our Bookings CRUD APIs now configured with Audit behavior we can see an example of what this looks like in Locode
after the Employee User account records a Booking from **John Smith** for a **Single** room: 

![](/img/pages/locode/audit-history-create.png)

With the left section displaying audit information about the CRUD operation and the User making it including their 
UserName, Id and IP. The right section contains the info sent in the Request DTO, in this case the `CreateBooking` API. 

If **John Smith** later contacts the manager to upgrade his booking to a **Suite**, the Audit information will be updated
with the `UpdateBooking` Audit entry which as it is a `IPatchDb<Table>` operation, only contains information that's **changed**:

![](/img/pages/locode/audit-history-update.png)

This is typically why the behavior of `IPatchDb<Table>` is preferable over `IUpdateDb<Table>` APIs when Audit Tracking 
is enabled as otherwise each Update operation would instead contain the entire entry on each update.

## Full Executable Audit History

As each Audit Entry contains the CRUD Request DTO, they can be used to recreate the state of the database by replaying
each event & executing them against a blank database:

```csharp
var eventsPlayer = new CrudEventsExecutor(appHost);
foreach (var crudEvent in dbEvents.GetEvents(db))
{
    await eventsPlayer.ExecuteAsync(crudEvent);
}
```

This can provide similar benefits to [Event Sourcing](https://martinfowler.com/eaaDev/EventSourcing.html) without its
additional development & maintenance burden where they can be used to reconstruct the state of the database at a specific 
point in time or used to populate external data stores like search indexes or analytical reporting databases to enable
greater insight than what an RDBMS snapshot can provide.

You could replay all events to reconstruct the entire state of the database, or choose just the tables you want to 
rebuild where you can fetch all Audit Events for just the `Booking` table with:

```csharp
var bookingAuditEvents = dbEvents.GetEvents(Db, nameof(Booking));
```

Alternatively you can fetch all the audit events for a single row which is what Locode uses to display its Audit Events: 

```csharp
var rowAuditEvents = dbEvents.GetEvents(Db, nameof(Booking), id);
```

## Complete Bookings CRUD Implementation

The [Bookings CRUD Demo](/autoquery/crud-bookings) is a good representative example of the
effort it takes to implement a traditional CRUD API with AutoQuery:

<lite-youtube class="w-full mx-4 my-4" width="560" height="315" videoid="rSFiikDjGos" style="background-image: url('https://img.youtube.com/vi/rSFiikDjGos/maxresdefault.jpg')"></lite-youtube>

Which reduces the development to effort of creating Full Stack Apps down to declaring your Data Models and APIs with
simple POCOs to define the precise schema of the underlying RDBMS tables and API contract, that can then benefit from: 

 - Productive end-to-end [typed Development Model in 11 languages](https://servicestack.net/service-reference)
 - [Declarative Dev Model](/locode/declarative) for defining Authentication, Validation, Documentation & UI Customizations
 - Beautiful, UX-Friendly, capability-based Customizable UI in [Locode](https://servicestack.net/locode)
 - Rich analysis, API discoverability & [simplified client integrations](/api-explorer#code-tab) in [API Explorer](/api-explorer)
 - Powerful querying capabilities in [AutoQuery](/autoquery/)
 - Full executable [Audit History Tracking](/autoquery/audit-log)
 - Access to ServiceStack's rich ecosystem of [typed clients, versatile formats & endpoints](/why-servicestack#multiple-clients)
 - Seamless integrations with [Open API](/openapi), interactive [Jupyter Notebooks](/jupyter-notebooks) & [Instant Client Apps](https://apps.servicestack.net/)

And access to ServiceStack's rich ecosystem of features, most of which are centered around your typed API contracts
making them easy to enhance & apply to your existing Services.

All without needing to write a single line of implementation logic thanks to the default implementation in AutoQuery
Services & Auto UIs in Locode, API Explorer & Swagger UI. At the same time when needed the default behavior
can be overridden at multiple levels, from custom AutoQuery implementations on the server to custom UIs on the client.

For completeness, the entire source code used to implement the Bookings CRUD implementation is below: 

```csharp
public class Booking : AuditBase
{
    [AutoIncrement]
    public int Id { get; set; }
    public string Name { get; set; }
    public RoomType RoomType { get; set; }
    public int RoomNumber { get; set; }
    public DateTime BookingStartDate { get; set; }
    public DateTime? BookingEndDate { get; set; }
    public decimal Cost { get; set; }
    public string Notes { get; set; }
    public bool? Cancelled { get; set; }
}

public enum RoomType
{
    Single,
    Double,
    Queen,
    Twin,
    Suite,
}

[AutoApply(Behavior.AuditQuery)]
public class QueryBookings : QueryDb<Booking>
{
    public int[] Ids { get; set; }
}

[ValidateHasRole("Employee")]
[AutoApply(Behavior.AuditCreate)]
public class CreateBooking
    : ICreateDb<Booking>, IReturn<IdResponse>
{
    public string Name { get; set; }
    public RoomType RoomType { get; set; }
    [ValidateGreaterThan(0)]
    public int RoomNumber { get; set; }
    public DateTime BookingStartDate { get; set; }
    public DateTime? BookingEndDate { get; set; }
    [ValidateGreaterThan(0)]
    public decimal Cost { get; set; }
    public string Notes { get; set; }
}

[ValidateHasRole("Employee")]
[AutoApply(Behavior.AuditModify)]
public class UpdateBooking
    : IPatchDb<Booking>, IReturn<IdResponse>
{
    public int Id { get; set; }
    public string Name { get; set; }
    public RoomType? RoomType { get; set; }
    [ValidateGreaterThan(0)]
    public int? RoomNumber { get; set; }
    public DateTime? BookingStartDate { get; set; }
    public DateTime? BookingEndDate { get; set; }
    [ValidateGreaterThan(0)]
    public decimal? Cost { get; set; }
    public bool? Cancelled { get; set; }
    public string Notes { get; set; }
}

[ValidateHasRole("Manager")]
[AutoApply(Behavior.AuditSoftDelete)]
public class DeleteBooking : IDeleteDb<Booking>, IReturnVoid
{
    public int Id { get; set; }
}
```


# Advanced Locode Features
Source: https://docs.servicestack.net/locode/advanced

## Pre-populated Reference Data

As we look for ways to improve productivity in Locode now pre-populates referential data from navigated references, e.g. when creating a new Job Application after navigating to a [Job's Applications in Talent Blazor](https://talent.locode.dev/locode/QueryJob) it uses this context to pre-populate the Job it's filtered by:

![](/img/pages/locode/prepopulated-related-data.png)

## Support for Large Apps

The built-in capability-based UI's are powered from your APIs metadata, as more of our Customers start to make use of these new UIs in their workflow we've had reports from some customers with [Large Apps (550+ APIs)](https://forums.servicestack.net/t/api-explorer-hangs-on-large-service-layer/10743) that the UIs started to hang their browsers when it tried to process the **9.5MB** of generated metadata.

To support Larger Apps we've added the ability to restrict the metadata and UIs to only related APIs in [user-defined Tag Groups](/api-design#group-services-by-tag) by adding `?IncludeTypes` to the URL, e.g:

- `/ui/?IncludeTypes={tag}`

This follows the Include Types pattern where you can view multiple tag groups with:

- `/ui/?IncludeTypes={tag1},{tag2}`

This feature is supported in all built-in UIs and is now integrated on the **/metadata** page where if you select a tag the API Explorer link will be updated with **?IncludeTypes={tag}**:

![](/img/pages/locode/locode-tags-filter.png)

Where you'll now be able to open API Explorer restricted to APIs with that tag without needing to manually craft the URL.

## Localize Metadata

To assist with with creating Localized Locode UIs, all user-defined descriptive text is now routed through to your AppHost's `ResolveLocalizedString()` method which you can use to return a localized string for the current request, e.g:

```csharp
public override string ResolveLocalizedString(string text, IRequest request = null)
{
    return request != null 
        ? MyResolveLocalizedString(text, request.Headers[HttpHeaders.AcceptLanguage])
        : text;
}
```


# OrmLite Installation
Source: https://docs.servicestack.net/ormlite/installation

OrmLite packages are available on NuGet and can be installed using your IDE or by adding a `PackageReference` in your `.csproj`

## PostgreSQL

Supports **.NET 6+**, .NET Framework **v4.7.2+** and **.NET Standard 2.0** (.NET 5 and lower)

:::copy
`<PackageReference Include="ServiceStack.OrmLite.PostgreSQL" Version="8.*" />`
:::

## SQL Server

Uses **[Microsoft.Data.SqlClient](https://devblogs.microsoft.com/dotnet/introducing-the-new-microsoftdatasqlclient/)** ADO .NET provider. Supports **.NET 6+**, .NET Framework **v4.7.2+** and **.NET Standard 2.0** (supports Apple Silicon/ARM)

:::copy
`<PackageReference Include="ServiceStack.OrmLite.SqlServer.Data" Version="8.*" />`
:::

Uses **System.Data.SqlClient**. Supports **.NET 6+**, .NET Framework **v4.7.2+** and **.NET Standard 2.0** (.NET 5 and lower)

:::copy
`<PackageReference Include="ServiceStack.OrmLite.SqlServer" Version="8.*" />`
:::

## MySql

Uses **Mysql.Data**. Supports **.NET 6+**, .NET Framework **v4.7.2+** and **.NET Standard 2.0** (.NET 5 and lower)

:::copy
`<PackageReference Include="ServiceStack.OrmLite.MySql" Version="8.*" />`
:::

Uses [MySqlConnector](https://mysqlconnector.net). Supports **.NET 6+**, .NET Framework **v4.7.2+** and **.NET Standard 2.0** (.NET 5 and lower)

:::copy
`<PackageReference Include="ServiceStack.OrmLite.MySqlConnector" Version="8.*" />`
:::

## SQLite

Uses **[Microsoft.Data.Sqlite](https://docs.microsoft.com/en-us/dotnet/standard/data/sqlite/)**. Supports **.NET 6+**, .NET Framework **v4.7.2+** and **.NET Standard 2.0** (supports Apple Silicon/ARM)

:::copy
`<PackageReference Include="ServiceStack.OrmLite.Sqlite.Data" Version="8.*" />`
:::

Uses **[System.Data.SQLite](https://system.data.sqlite.org)**. Supports **.NET 6+**, .NET Framework **v4.7.2+** and **.NET Standard 2.0** (.NET 5 and lower)


:::copy
`<PackageReference Include="ServiceStack.OrmLite.Sqlite" Version="8.*" />`
:::


 Uses [SQLitePCLRaw.bundle_cil](https://ericsink.com/entries/sqlite_llama_preview.html) for a managed implementation free of native binaries. **Still in Preview** but passes 100% test suite.

:::copy
`<PackageReference Include="ServiceStack.OrmLite.Sqlite.Cil" Version="8.*" />`
:::


## .NET 6 & .NET Standard 2.0 only packages

The `.Core` packages contains only **.NET 6** and **.NET Standard 2.0** versions which can be used in [ASP.NET Core Apps on .NET Framework](/templates/corefx):

:::copy
`<PackageReference Include="ServiceStack.OrmLite.SqlServer.Core" Version="8.*" />`
:::

:::copy
`<PackageReference Include="ServiceStack.OrmLite.PostgreSQL.Core" Version="8.*" />`
:::

:::copy
`<PackageReference Include="ServiceStack.OrmLite.MySql.Core" Version="8.*" />`
:::

:::copy
`<PackageReference Include="ServiceStack.OrmLite.Sqlite.Core" Version="8.*" />`
:::

## Community Providers

Unofficial providers contributed and supported by ServiceStack Community users:

:::copy
`<PackageReference Include="ServiceStack.OrmLite.Oracle" Version="8.*" />`
:::

:::copy
`<PackageReference Include="ServiceStack.OrmLite.Firebird" Version="8.*" />`
:::

Please raise support questions on [StackOverflow](https://stackoverflow.com/questions/ask?tags=servicestack,ormlite-servicestack) or [ServiceStack/Discuss](https://github.com/ServiceStack/Discuss/discussions/categories/q-a) for best chance to reach community users.

## Quick install in ASP .NET Core with mix

The quickest way to install OrmLite in existing ASP .NET Core projects is to [mix in](/mix-tool) the desired RDBMS provider which both installs the required NuGet package and creates a [Modular Startup](/modular-startup) configuration all setup to read your App's configured RDBMS connection string for instant utility:

::: sh
x mix postgres
:::

::: sh
x mix sqlserver
:::

::: sh
x mix mysql
:::

::: sh
x mix sqlite
:::

::: sh
x mix oracle
:::

::: sh
x mix firebird
:::

If you don't have the dotnet `x` tool installed, it can be installed with: 

::: sh
dotnet tool install -g x
:::


# Getting started with OrmLite
Source: https://docs.servicestack.net/ormlite/getting-started

<div class="py-8 max-w-7xl mx-auto">
    <lite-youtube class="w-full mx-4 my-4" width="560" height="315" videoid="vUbpwjfEYzg" style="background-image: url('https://img.youtube.com/vi/vUbpwjfEYzg/maxresdefault.jpg')"></lite-youtube>
</div>

After [installing OrmLite](installation) we now need to configure OrmLite's DB Connection Factory containing the RDBMS Dialect you want to use and the primary DB connection string you wish to connect to. Most NuGet OrmLite packages only contain a single provider listed below:

```csharp
SqlServerDialect.Provider      // SQL Server Version 2012+
SqliteDialect.Provider         // Sqlite
PostgreSqlDialect.Provider     // PostgreSQL 
MySqlDialect.Provider          // MySql
OracleDialect.Provider         // Oracle
FirebirdDialect.Provider       // Firebird
```

### SQL Server Dialects

Except for SQL Server which has a number of different dialects to take advantage of features available in each version, please use the best matching version closest to your SQL Server version:

```csharp
SqlServer2008Dialect.Provider  // SQL Server <= 2008
SqlServer2012Dialect.Provider  // SQL Server 2012
SqlServer2014Dialect.Provider  // SQL Server 2014
SqlServer2016Dialect.Provider  // SQL Server 2016
SqlServer2017Dialect.Provider  // SQL Server 2017+
```

## OrmLite Connection Factory

To configure OrmLite you'll need your App's DB Connection string along the above RDBMS Dialect Provider, e.g:

```csharp
var dbFactory = new OrmLiteConnectionFactory(
    connectionString,  
    SqlServerDialect.Provider);
```

If you're using an IOC register `OrmLiteConnectionFactory` as a **singleton**:

```csharp
services.AddSingleton<IDbConnectionFactory>(
    new OrmLiteConnectionFactory(":memory:", SqliteDialect.Provider)); //InMemory Sqlite DB
```

Which can then be used to open DB Connections to your RDBMS.

### Creating Table and Seed Data Example

If connecting to an empty database you can use OrmLite's Create Table APIs to create any missing tables you need, which OrmLite creates
based solely on the Schema definition of your POCO data models.

`CreateTableIfNotExists` returns **true** if the table didn't exist and OrmLite created it, where it can be further populated with any initial seed data it should have, e.g:

```csharp
using var db = dbFactory.Open();

if (db.CreateTableIfNotExists<Poco>())
{
    db.Insert(new Poco { Id = 1, Name = "Seed Data"});
}

var result = db.SingleById<Poco>(1);
result.PrintDump(); //= {Id: 1, Name:Seed Data}
```

### Multiple database connections

Any number of named RDBMS connections can be registered OrmLite's DbFactory `RegisterConnection`, e.g:

```csharp
// SqlServer with a named "Reporting" PostgreSQL connection as a part of the same `dbFactory`
var dbFactory = new OrmLiteConnectionFactory(connString, SqlServer2012Dialect.Provider);
container.Register<IDbConnectionFactory>(dbFactory);

dbFactory.RegisterConnection("Reporting", pgConnString, PostgreSqlDialect.Provider);
```

Named connections can be opened by its name:

```csharp
using var db = dbFactory.Open("Reporting");
```

If using ServiceStack the `[NamedConnection]` attribute can be used to configure Services `base.Db` connection with the 
named connection RDBMS, e.g:

```csharp
[NamedConnection("Reporting")]
public class QueryReports {}

public class ReportServices : Service
{
    public object Any(QueryReports request) => Db.Select<Reports>();
}
```

Or if using [AutoQuery](/autoquery/) it can be used to associate Data Models with the named connection:

```csharp
[NamedConnection("Reporting")]
public class Reports { ... }

public class QueryReports : QueryDb<Reports> {}
```

Otherwise for other Services the `[ConnectionInfo]` attribute can be used to change the `base.Db` to use the registered
named connection for all APIs in a Service class, e.g:

```csharp
[ConnectionInfo(NamedConnection = "Reporting")]
public class ReportingServices : Service
{
    public object Any(Sales request)
    {
        return new SalesResponse { Results = Db.Select<Sales>() };
    }
}
```

More examples available in [Multitenancy](/multitenancy) docs.


## Detailed Walkthrough

OrmLite is a lightweight, convention-based Object-Relational Mapper (ORM) offered within the ServiceStack suite of libraries. This tutorial aims to guide you through the basic functionality of OrmLite, covering its usage both as a standalone library and as an integrated part of a ServiceStack service. You will learn how to set up OrmLite, create data models, perform standard CRUD operations, and utilize the library's unique query functionalities. This tutorial provides a comprehensive starting point for developers looking to understand and effectively use OrmLite in their .NET projects.

### Setup and Installation

To begin using OrmLite, you'll need to install it in your project. For a basic Console application, you'll want to add the OrmLite NuGet package for the database you're planning to use. This tutorial will use SQLite as an example. So, within your Package Manager Console, input `Install-Package ServiceStack.OrmLite.Sqlite` or use `dotnet .

```bash
dotnet add package ServiceStack.OrmLite.SqlServer   // SQLServer 2012+
dotnet add package ServiceStack.OrmLite.Sqlite      // Sqlite
dotnet add package ServiceStack.OrmLite.PostgreSQL  // PostgreSQL 
dotnet add package ServiceStack.OrmLite.MySql       // MySql
```

Or you can add the following to your `csproj` file.

:::copy
`<PackageReference Include="ServiceStack.OrmLite.SqlServer" Version="8.*" />`
:::

:::copy
`<PackageReference Include="ServiceStack.OrmLite.Sqlite" Version="8.*" />`
:::

:::copy
`<PackageReference Include="ServiceStack.OrmLite.PostgreSQL" Version="8.*" />`
:::

:::copy
`<PackageReference Include="ServiceStack.OrmLite.MySql" Version="8.*" />`
:::

The next step is creating a connection to your database. Here's how you do it for SQLite:

```csharp
var dbFactory = new OrmLiteConnectionFactory(":memory:", SqliteDialect.Provider);
```

This snippet establishes an in-memory SQLite database connection. In a real-world application, you'd replace `":memory:"` with your SQLite database's connection string.

OrmLite supports multiple database types, including MS SQL Server, MySQL, and PostgreSQL. To use these, simply install the corresponding NuGet package and replace `SqliteDialect.Provider` with the appropriate provider (i.e., `SqlServerDialect.Provider`, `MySqlDialect.Provider`, or `PostgreSqlDialect.Provider`).

If you're planning on using OrmLite within a ServiceStack project, you can streamline the setup process with the ServiceStack .NET tool `x` and the command `x mix <database technology>`. For SQLite, use `x mix sqlite`.

```bash
# Create new project
x new web MyApp
# Navigate into new project
cd MyApp
# Mix in OrmLite SQLite support
x mix sqlite
```

After setup, you're now ready to establish a database connection and execute queries from your project.

## Basic Usage (Standalone)

OrmLite is designed for simplicity and efficiency, enabling you to perform CRUD operations directly from your .NET classes. Here's an example of how you can utilize OrmLite in a standalone context.

![basic-usage.PNG](/img/pages/ormlite/getting-started/basic-usage.PNG)

### Creating a Connection

Creating a connection with your database is as simple as calling `OpenDbConnection` on your `IDbConnectionFactory` instance.

```csharp
using var db = dbFactory.OpenDbConnection();
```

This line establishes a connection to your database and ensures it is correctly disposed of once you're finished.

## Creating a Model

OrmLite maps C# classes to database tables. Here's an example model class `Order`:

```csharp
public class Order
{
    [AutoIncrement]
    public int Id { get; set; }
    public string Customer { get; set; }
    public DateTime OrderDate { get; set; }
}
```

In this class, the `Id` property is annotated with `[AutoIncrement]`, telling OrmLite to auto-increment this field for new records.

![table-mapping.PNG](/img/pages/ormlite/getting-started/table-mapping.PNG)

### Creating a Table

Once your model is defined, you can use it to create a new table:

```csharp
db.CreateTableIfNotExists<Order>();
```

This method creates a new `Order` table if it doesn't already exist in your database.

### Inserting Data

To insert data, use the `Insert` method:

```csharp
var order = new Order
{
    Customer = "John Doe",
    OrderDate = DateTime.UtcNow
};

db.Insert(order);
```

The `Insert` method adds a new record to the `Order` table. If you want to retrieve the auto-incremented Id after the insert, use `Insert` and `selectIdentity` together:

```csharp
var orderId = db.Insert(order, selectIdentity: true);
```

### Updating Data

Updating records is just as easy. Make sure your instance includes the primary key value:

```csharp
order.Customer = "Jane Doe";
db.Update(order);
```

This updates the `Order` record that has the same `Id` as `order`.

### Deleting Data

Finally, deleting a record is a simple call to `Delete`:

```csharp
db.Delete(order);
```

This deletes the `Order` record with the same `Id` as `order`. To delete a records based on a condition, use `Delete<T>(predicate)`:

```csharp
db.Delete<Order>(x => x.Customer == "Jane Doe");
```


## Usage from a ServiceStack Service

Utilizing OrmLite from a ServiceStack service is straightforward, due to ServiceStack's built-in integration with OrmLite. ServiceStack services can access a `Db` property from the base `Service` class, which provides access to an OrmLite database connection.

### Registering the Database Connection Factory

Before you can use the `Db` property, you need to register an `IDbConnectionFactory` instance with ServiceStack's IoC container. This is usually done in your `ConfigureDb.cs` file:

```csharp
public class ConfigureDb : IHostingStartup
{
    public void Configure(IWebHostBuilder builder) => builder
        .ConfigureServices((context, services) => {
            services.AddSingleton<IDbConnectionFactory>(new OrmLiteConnectionFactory(
                context.Configuration.GetConnectionString("DefaultConnection")
                ?? ":memory:",
                SqliteDialect.Provider));
        });
}
```

In this code, an `OrmLiteConnectionFactory` is created and registered as a singleton service. This factory will create database connections when needed, using the provided connection string and dialect provider.

### Creating a ServiceStack Service

Here's an example of a ServiceStack service that performs basic CRUD operations on an `Order`:

```csharp
public class OrderService : Service
{
    public object Any(GetOrder request)
    {
        return Db.SingleById<Order>(request.Id);
    }

    public object Any(CreateOrder request)
    {
        var order = new Order
        {
            Customer = request.Customer,
            OrderDate = DateTime.UtcNow
        };

        var orderId = Db.Insert(order, selectIdentity: true);
        return new CreateOrderResponse { Id = orderId };
    }

    public void Any(UpdateOrder request)
    {
        var order = Db.SingleById<Order>(request.Id);
        order.Customer = request.Customer;
        Db.Update(order);
    }

    public void Any(DeleteOrder request)
    {
        Db.DeleteById<Order>(request.Id);
    }
}
```

In this service, we're utilizing the `Db` property, which gives us a handle to the database connection. We can then use this handle to perform CRUD operations in the same way we did in a standalone context.

The service methods match HTTP verbs based on their prefix: `Any` methods can respond to any HTTP verb, `Get` methods respond to GET requests, `Post` methods respond to POST requests, and so on.

## Code-First Models

OrmLite uses a code-first approach to data modeling, which means you define your data model using C# classes, and OrmLite will take care of creating the corresponding database schema. This includes creating tables, defining columns and their types, and setting up relationships between tables.

In OrmLite, you can add various attributes to your class and property definitions that control how they're treated by OrmLite when generating schema or performing database operations. Here's an example `Order` class with some of these attributes:

```csharp
[Alias("Orders")]
public class Order
{
    [AutoIncrement]
    [PrimaryKey]
    public int Id { get; set; }
    
    [Required]
    [Index(Unique = true)]
    public string OrderNumber { get; set; }

    [Reference]
    public List<OrderLine> OrderLines { get; set; }
}
```

In this class definition:

- The `[Alias]` attribute changes the name of the generated table to `Orders`, can be used on properties as well for columns.
- The `[AutoIncrement]` attribute specifies that the `Id` column should automatically increment its value.
- The `[PrimaryKey]` attribute designates `Id` as the primary key for the `Order` table.
- The `[Required]` attribute indicates that the `OrderNumber` property must have a value before an order can be inserted or updated in the database.
- The `[Index]` attribute creates an index on the `OrderNumber` column and the `Unique = true` property ensures that the `OrderNumber` value is unique across all orders.
- The `[Reference]` attribute enables us to use features like `LoadSelect<T>` to pull data from related tables.

The corresponding `OrderLine` class may look something like this:

```csharp
public class OrderLine
{
    [AutoIncrement]
    [PrimaryKey]
    public int Id { get; set; }

    [ForeignKey(typeof(Order))]
    public int OrderId { get; set; }

    public string Product { get; set; }

    public int Quantity { get; set; }
}
```

In this `OrderLine` class definition:

- The `[ForeignKey]` attribute defines a foreign key relationship from `OrderLine` to `Order`. The `OrderId` property in `OrderLine` corresponds to the `Id` property in `Order`.

## Different ways to Query

OrmLite offers several ways to query your database, catering to different levels of complexity and customization needs. Here, we will explore three methods: lambda expressions, the `From<T>` method, and plain SQL queries.

Let's use our `Order` and `OrderLine` models and assume we already have some data in our database.

### Lambda Expressions

Lambda expressions are the simplest way to query your database using OrmLite. You can use them directly within OrmLite's `Select<T>` method:

```csharp
var orders = db.Select<Order>(x => x.OrderNumber == "1234");
```

This line will fetch all orders where `OrderNumber` equals "1234".

### `From<T>` Method

The `From<T>` method provides more flexibility than simple lambda expressions. It enables you to build more complex queries involving multiple tables and conditions:

```csharp
var q = db.From<Order>()
          .Join<Order, OrderLine>()
          .Where<Order>(x => x.OrderNumber == "1234");
var orders = db.Select<Order>(q);
```

This query fetches all orders, and joins their corresponding `OrderLine` entries, where `OrderNumber` equals "1234".

### Plain SQL

While OrmLite's query API is robust and handles a wide variety of query scenarios, there are times when you might need to drop down to raw SQL for the utmost control:

```csharp
var orders = db.Select<Order>("SELECT * FROM Orders WHERE OrderNumber = @orderNumber", new { orderNumber = "1234" });
```

This is a basic query but demonstrates that you can write and execute raw SQL queries in OrmLite, and map back to your model classes.

## Inserting data

Inserting data into your database using OrmLite is as straightforward as querying. Let's dive into some examples using our `Order` and `OrderLine` models.

### Basic Insert

The simplest way to insert a new record into your database is by using the `Insert` method. You just need to create an instance of your model and pass it to the `Insert` method:

```csharp
var newOrder = new Order
{
    OrderNumber = "5678",
    OrderDate = DateTime.UtcNow
};

db.Insert(newOrder);
```

### Inserting with SelectIdentity

If your model has an `[AutoIncrement]` attribute on its primary key, you can retrieve the generated id during the insertion:

```csharp
var newOrder = new Order
{
    OrderNumber = "5678",
    OrderDate = DateTime.UtcNow
};

var newId = db.Insert(newOrder, selectIdentity: true);
```

### Inserting Multiple Records

OrmLite also allows you to insert multiple records at once when passing a `List<T>` to `InsertAll`:

```csharp
var orderLines = new List<OrderLine>
{
    new OrderLine { OrderId = newId, ProductName = "Product 1", Quantity = 2 },
    new OrderLine { OrderId = newId, ProductName = "Product 2", Quantity = 3 }
};

db.InsertAll(orderLines);
```

## Updating data

Let's use our `Order` and `OrderLine` models for demonstration of updating.

### Basic Update

The most straightforward way to update a record in your database is by using the `Update` method. You need to create an instance of your model with the desired changes and pass it to the `Update` method:

```csharp
var orderToUpdate = db.Single<Order>(x => x.OrderNumber == "5678");
orderToUpdate.OrderDate = DateTime.UtcNow;

db.Update(orderToUpdate);
```

In this example, the `Update` method uses the `Id` property (which is treated as the primary key by default) to identify the record to update.

### Conditional Update

In case you need to update multiple records based on a condition, you can use the `UpdateOnly` method. This method is powerful as it allows you to specify which properties to update and the condition for the records to be updated:

```csharp
db.UpdateOnly(() => new Order { OrderDate = DateTime.UtcNow },
    where: x => x.OrderNumber == "5678");
```

In this example, only the `OrderDate` property is updated for all `Order` records that have `"5678"` as their `OrderNumber`.

### Updating Related Records

Let's say you want to update the `ProductName` for a specific `OrderLine` associated with an `Order`. Here's how you can do it:

```csharp
var orderLineToUpdate = db.Single<OrderLine>(x => x.OrderId == 1 && x.ProductName == "Product 1");
orderLineToUpdate.ProductName = "Updated Product Name";

db.Update(orderLineToUpdate);
```

## Deleting data

Once again, we'll use our `Order` and `OrderLine` models for demonstration of Delete.

### Basic Deletion

The simplest way to delete a record is by using the `Delete` method. You just need to pass an instance of your model with the `Id` of the record you want to delete:

```csharp
var orderToDelete = db.Single<Order>(x => x.OrderNumber == "5678");
db.Delete(orderToDelete);
```

In this example, the `Delete` method uses the `Id` property (which is treated as the primary key by default) to identify the record to delete.

### Conditional Deletion

If you need to delete multiple records based on a condition, you can also use the `Delete` method, but with a predicate:

```csharp
db.Delete<Order>(x => x.OrderNumber == "5678");
```

In this example, all `Order` records that have `"5678"` as their `OrderNumber` will be deleted.

## Using LoadSelect and Related Model Code Attributes

In real-world applications, it's quite common to deal with relationships between tables, like one-to-many relationships. OrmLite provides a set of `Load` prefixed methods to make loading related data with relationships easier. These methods return the primary entity and populate its related entities.

For instance, to load an `Order` with its related `OrderLine`s, you can use the `LoadSelect` method:

```csharp
var orderWithLines = db.LoadSelect<Order>(x => x.Id == 1);
```

In this case, `LoadSelect` returns an `Order` object that also contains all the `OrderLine`s related to it. The relationship between `Order` and `OrderLine` is defined by the `ForeignKey` attribute:

```csharp
public class OrderLine
{
    [AutoIncrement]
    public int Id { get; set; }

    [ForeignKey(typeof(Order))]
    public int OrderId { get; set; }

    public string ProductName { get; set; }
    public decimal Price { get; set; }
}
```

And the `Order` class has a `List<OrderLine>` applied with a `[Reference]` attribute:

```csharp
public class Order
{
    [AutoIncrement]
    public int Id { get; set; }
    public string OrderNumber { get; set; }

    [Reference]
    public List<OrderLine> OrderLines { get; set; }
}
```

The `ForeignKey` attribute in the `OrderLine` class establishes that the `OrderId` property is a foreign key that relates to the `Order` table. The `[Reference]` attribute is used by `LoadSelect` to populate the related data on the `Order` class.

## High-Level Features When Integrated with ServiceStack

While ServiceStack.OrmLite works effectively as a standalone micro ORM, it offers even more when integrated within the ServiceStack ecosystem. In this context, OrmLite can be leveraged to facilitate high-level features of ServiceStack such as AutoQuery, Locode, and code-first model generation.

### AutoQuery and Code First Models

In a typical ServiceStack application, OrmLite is commonly used to create code-first models that form the basis for database operations. One key advantage of this is the seamless integration with AutoQuery, a ServiceStack feature that enables automated generation of optimized, queryable services for defined models.

![code-first.PNG](/img/pages/ormlite/getting-started/code-first.PNG)

Here's an example of defining a model and an AutoQuery request DTO:

```csharp
public class Order
{
    [AutoIncrement]
    public int Id { get; set; }
    
    public string Customer { get; set; }
}

[Route("/orders")]
public class QueryOrders : QueryDb<Order>
{
}
```

### AutoQuery and Database First Approach

ServiceStack also supports a database-first approach, especially useful when working with an existing database. In this scenario, you can leverage AutoQuery's `GeneratedServices` feature. It allows you to create ready-to-use services based on your database schema.

```csharp
appHost.Plugins.Add(new AutoQueryFeature {
    MaxLimit = 1000,
    GenerateCrudServices = new GenerateCrudServices
    {
        AutoRegister = true
    }
}
```

### Locode

Locode is a built-in ServiceStack UI that provides an easy way to visualize, interact with your database and manage your data. When using OrmLite with AutoQuery, Locode can generate interfaces for your tables, enabling you to browse and manage your data.

![database-first-workflow.PNG](/img/pages/ormlite/getting-started/database-first-workflow.PNG)

### Code Generation with ServiceStack 'x' Tool

If you start with a database-first approach using `GeneratedServices`, ServiceStack provides a smooth transition to a code-first approach when you're ready. Using the `x` dotnet tool, you can generate all POCO model classes, as well as AutoQuery CRUD Request DTOs, all from an existing database schema. The command for this is:

```bash
x csharp https://localhost:5001 -path /crud/all/csharp
```

![database-first.PNG](/img/pages/ormlite/getting-started/database-first.PNG)

This will create a C# file that contain classes representing each table in your database, as well as the CRUD Request DTOs. From there, you can start to manipulate these models in a code-first manner while still leveraging all the powerful features of ServiceStack and OrmLite.

## Conclusion

We've journeyed through an introduction to ServiceStack.OrmLite, discussing its setup, basic usage, and how it can be used within a ServiceStack service. We've explored the power of code-first models, various ways of querying, inserting, updating, and deleting data using OrmLite, and how to leverage LoadSelect to handle related model data.

We also touched on some high-level features provided by OrmLite when integrated with ServiceStack, including AutoQuery, Locode, and transitioning from a database-first to a code-first approach using the 'x' dotnet tool.

The aim of this tutorial was to give you an understanding of the core concepts and capabilities of OrmLite and to demonstrate its potential as a reliable and efficient Micro ORM for your .NET projects. Whether used in a standalone context or as part of a wider ServiceStack application, OrmLite provides a lightweight, intuitive, and feature-rich data access solution.

## Feedback welcome

Think we are missing something in OrmLite to make it better? Let us know in [servicestack.net/ideas](https://servicestack.net/ideas)!


# OrmLite API Overview
Source: https://docs.servicestack.net/ormlite/ormlite-apis

OrmLite's APIs are minimal, providing basic shortcuts for the primitive SQL statements:

[![OrmLite API](https://raw.githubusercontent.com/ServiceStack/Assets/master/img/ormlite/OrmLiteApi.png)](https://raw.githubusercontent.com/ServiceStack/Assets/master/img/ormlite/OrmLiteApi.png)

OrmLite makes available most of its functionality via extension methods to add enhancements over ADO.NET's `IDbConnection`, providing
a Typed RDBMS-agnostic API that transparently handles differences in each supported RDBMS provider.

## Create Tables Schemas

OrmLite is able to **CREATE**, **DROP** and **ALTER** RDBMS Tables from your code-first Data Models with rich annotations for
controlling how the underlying RDBMS Tables are constructed.

The Example below utilizes several annotations to customize the definition and behavior of RDBMS tables based on a POCOs
**public properties**:

```csharp
public class Player
{
    public int Id { get; set; }                     // 'Id' is PrimaryKey by convention

    [Required]
    public string FirstName { get; set; }           // Creates NOT NULL Column

    [Alias("Surname")]                              // Maps to [Surname] RDBMS column
    public string LastName { get; set; }

    [Index(Unique = true)]                          // Creates Unique Index
    public string Email { get; set; }

    public List<Phone> PhoneNumbers { get; set; }   // Complex Types blobbed by default

    [Reference]
    public List<GameItem> GameItems { get; set; }   // 1:M Reference Type saved separately

    [Reference]
    public Profile Profile { get; set; }            // 1:1 Reference Type saved separately
    public int ProfileId { get; set; }              // 1:1 Self Ref Id on Parent Table

    [ForeignKey(typeof(Level), OnDelete="CASCADE")] // Creates ON DELETE CASCADE Constraint
    public Guid SavedLevelId { get; set; }          // Creates Foreign Key Reference

    public ulong RowVersion { get; set; }           // Optimistic Concurrency Updates
}

public class Phone                                  // Blobbed Type only
{
    public PhoneKind Kind { get; set; }
    public string Number { get; set; }
    public string Ext { get; set; }
}

public enum PhoneKind
{
    Home,
    Mobile,
    Work,
}

[Alias("PlayerProfile")]                            // Maps to [PlayerProfile] RDBMS Table
[CompositeIndex(nameof(Username), nameof(Region))]  // Creates Composite Index
public class Profile
{
    [AutoIncrement]                                 // Auto Insert Id assigned by RDBMS
    public int Id { get; set; }

    public PlayerRole Role { get; set; }            // Native support for Enums
    public Region Region { get; set; }
    public string Username { get; set; }
    public long HighScore { get; set; }

    [Default(1)]                                    // Created in RDBMS with DEFAULT (1)
    public long GamesPlayed { get; set; }

    [CheckConstraint("Energy BETWEEN 0 AND 100")]   // Creates RDBMS Check Constraint
    public short Energy { get; set; }

    public string ProfileUrl { get; set; }
    public Dictionary<string, string> Meta { get; set; }
}

public enum PlayerRole                              // Enums saved as strings by default
{
    Leader,
    Player,
    NonPlayer,
}

[EnumAsInt]                                         // Enum Saved as int
public enum Region
{
    Africa = 1,
    Americas = 2,
    Asia = 3,
    Australasia = 4,
    Europe = 5,
}

public class GameItem
{
    [PrimaryKey]                                    // Specify field to use as Primary Key
    [StringLength(50)]                              // Creates VARCHAR COLUMN
    public string Name { get; set; }

    public int PlayerId { get; set; }               // Foreign Table Reference Id

    [StringLength(StringLengthAttribute.MaxText)]   // Creates "TEXT" RDBMS Column 
    public string Description { get; set; }

    [Default(OrmLiteVariables.SystemUtc)]           // Populated with UTC Date by RDBMS
    public DateTime DateAdded { get; set; }
}

public class Level
{
    public Guid Id { get; set; }                    // Unique Identifier/GUID Primary Key
    public byte[] Data { get; set; }                // Saved as BLOB/Binary where possible
}
```

We can drop the existing tables and re-create the above table definitions with:

```csharp
using var db = dbFactory.Open();

if (db.TableExists<Level>())
    db.DeleteAll<Level>();                      // Delete ForeignKey data if exists

//DROP and CREATE ForeignKey Tables in dependent order
db.DropTable<Player>();
db.DropTable<Level>();
db.CreateTable<Level>();
db.CreateTable<Player>();

//DROP and CREATE tables without Foreign Keys in any order
db.DropAndCreateTable<Profile>();
db.DropAndCreateTable<GameItem>();

var savedLevel = new Level
{
    Id = Guid.NewGuid(),
    Data = new byte[]{ 1, 2, 3, 4, 5 },
};
db.Insert(savedLevel);

var player = new Player
{
    Id = 1,
    FirstName = "North",
    LastName = "West",
    Email = "north@west.com",
    PhoneNumbers = new List<Phone>
    {
        new Phone { Kind = PhoneKind.Mobile, Number = "123-555-5555"},
        new Phone { Kind = PhoneKind.Home,   Number = "555-555-5555", Ext = "123"},
    },
    GameItems = new List<GameItem>
    {
        new GameItem { Name = "WAND", Description = "Golden Wand of Odyssey"},
        new GameItem { Name = "STAFF", Description = "Staff of the Magi"},
    },
    Profile = new Profile
    {
        Username = "north",
        Role = PlayerRole.Leader,
        Region = Region.Australasia,
        HighScore = 100,
        GamesPlayed = 10,
        ProfileUrl = "https://www.gravatar.com/avatar/205e460b479e2e5b48aec07710c08d50.jpg",
        Meta = new Dictionary<string, string>
        {
            {"Quote", "I am gamer"}
        },
    },
    SavedLevelId = savedLevel.Id,
};
db.Save(player, references: true);
```

This will add a record in all the above tables with all the Reference data properties automatically populated which we can quickly see
by selecting the inserted `Player` record and all its referenced data by using [OrmLite's Load APIs](reference-support.md#querying-pocos-with-references), e.g:

```csharp
var dbPlayer = db.LoadSingleById<Player>(player.Id);

dbPlayer.PrintDump();
```

Which uses the [Dump Utils](/dump-utils) to quickly display the populated data to the console:

```
{
    Id: 1,
    FirstName: North,
    LastName: West,
    Email: north@west.com,
    PhoneNumbers: 
    [
        {
            Kind: Mobile,
            Number: 123-555-5555
        },
        {
            Kind: Home,
            Number: 555-555-5555,
            Ext: 123
        }
    ],
    GameItems: 
    [
        {
            Name: WAND,
            PlayerId: 1,
            Description: Golden Wand of Odyssey,
            DateAdded: 2018-01-17T07:53:45-05:00
        },
        {
            Name: STAFF,
            PlayerId: 1,
            Description: Staff of the Magi,
            DateAdded: 2018-01-17T07:53:45-05:00
        }
    ],
    Profile: 
    {
        Id: 1,
        Role: Leader,
        Region: Australasia,
        Username: north,
        HighScore: 100,
        GamesPlayed: 10,
        Energy: 0,
        ProfileUrl: "https://www.gravatar.com/avatar/205e460b479e2e5b48aec07710c08d50.jpg",
        Meta: 
        {
            Quote: I am gamer
        }
    },
    ProfileId: 1,
    SavedLevelId: 7690dfa4d31949ab9bce628c34d1c549,
    RowVersion: 2
}
```

Feel free to continue experimenting with [this Example Live on Gistlyn](https://gistlyn.com/?gist=840bc7f09292ad5753d07cef6063893e&collection=991db51e44674ad01d3d318b24cf0934).

## Query Examples

If your SQL doesn't start with a **SELECT** statement, it is assumed a `WHERE` clause is being provided, e.g:

```csharp
var tracks = db.Select<Track>("Artist = @artist AND Album = @album",
    new { artist = "Nirvana", album = "Heart Shaped Box" });
```

Which is equivalent to:

```csharp
var tracks = db.Select<Track>("SELECT * FROM track WHERE Artist = @artist AND Album = @album", 
    new { artist = "Nirvana", album = "Heart Shaped Box" });
```

Use `Sql*` APIs for when you want to query custom SQL that is not a SELECT statement, e.g:

```csharp
var tracks = db.SqlList<Track>("EXEC GetArtistTracks @artist, @album",
    new { artist = "Nirvana", album = "Heart Shaped Box" });
```

**Select** returns multiple records:

```csharp
List<Track> tracks = db.Select<Track>()
```

**Single** returns a single record:

```csharp
Track track = db.Single<Track>(x => x.RefId == refId)
```

**Dictionary** returns a Dictionary made from the first two columns:

```csharp
Dictionary<int, string> trackIdNamesMap = db.Dictionary<int, string>(
    db.From<Track>().Select(x => new { x.Id, x.Name }))

Dictionary<int, string> trackIdNamesMap = db.Dictionary<int, string>(
    "select Id, Name from Track")
```

**Lookup** returns an `Dictionary<K, List<V>>` made from the first two columns:

```csharp
Dictionary<int, List<string>> albumTrackNames = db.Lookup<int, string>(
    db.From<Track>().Select(x => new { x.AlbumId, x.Name }))

Dictionary<int, List<string>> albumTrackNames = db.Lookup<int, string>(
    "select AlbumId, Name from Track")
```

**Column** returns a List of first column values:

```csharp
List<string> trackNames = db.Column<string>(db.From<Track>().Select(x => x.Name))

List<string> trackNames = db.Column<string>("select Name from Track")
```

**HashSet** returns a HashSet of distinct first column values:

```csharp    
HashSet<string> uniqueTrackNames = db.ColumnDistinct<string>(
    db.From<Track>().Select(x => x.Name))

HashSet<string> uniqueTrackNames = db.ColumnDistinct<string>("select Name from Track")
```

**Scalar** returns a single scalar value:

```csharp
var trackCount = db.Scalar<int>(db.From<Track>().Select(Sql.Count("*")))

var trackCount = db.Scalar<int>("select count(*) from Track")
```

Anonymous types passed into **Where** are treated like an **AND** filter:

```csharp
var track3 = db.Where<Track>(new { AlbumName = "Throwing Copper", TrackNo = 3 })
```

SingleById(s), SelectById(s), etc provide strong-typed convenience methods to fetch by a Table's **Id** primary key field.

```csharp
var track = db.SingleById<Track>(1);
var tracks = db.SelectByIds<Track>(new[]{ 1,2,3 });
```


# OrmLite Async API
Source: https://docs.servicestack.net/ormlite/async-apis

A quick overview of Async API's can be seen in the class diagram below:

![OrmLite Async APIs](https://raw.githubusercontent.com/ServiceStack/Assets/master/img/ormlite/OrmLiteApiAsync.png)

Essentially most of OrmLite public API's now have async equivalents of the same name and an additional conventional `*Async` suffix.
The Async API's also take an optional `CancellationToken` making converting sync code trivial, where you just need to
add the `Async` suffix and **await** keyword, as can be seen in the
[Customer Orders UseCase upgrade to Async diff](https://github.com/ServiceStack/ServiceStack.OrmLite/commit/c1ce6f0eac99133fc232b263c26c42379d4c5f48)
, e.g:

Sync:

```csharp
db.Insert(new Employee { Id = 1, Name = "Employee 1" });
db.Save(product1, product2);
var customer = db.Single<Customer>(new { customer.Email }); 
```

Async:

```csharp
await db.InsertAsync(new Employee { Id = 1, Name = "Employee 1" });
await db.SaveAsync(product1, product2);
var customer = await db.SingleAsync<Customer>(new { customer.Email });
```

::: info
Effectively the only Data Access API's that doesn't have async equivalents are `*Lazy` APIs yielding a lazy
sequence (incompatible with async) as well as **Schema** DDL API's which are typically not used at runtime.
:::

For a quick preview of many of the new Async API's in action, checkout
[ApiSqlServerTestsAsync.cs](https://github.com/ServiceStack/ServiceStack/blob/main/ServiceStack.OrmLite/tests/ServiceStack.OrmLite.Tests/Async/ApiSqlServerTestsAsync.cs).

## Async RDBMS Providers

Currently, only a limited number of RDBMS providers offer async API's, which at this time are only:

- [SQL Server .NET 4.7.2+](https://www.nuget.org/packages/ServiceStack.OrmLite.SqlServer)
- [PostgreSQL .NET 4.7.2+](https://www.nuget.org/packages/ServiceStack.OrmLite.PostgreSQL)
- [MySQL .NET 4.7.2+](https://www.nuget.org/packages/ServiceStack.OrmLite.MySql)

We've also added a
[.NET 4.7.2 build for Sqlite](https://www.nuget.org/packages/ServiceStack.OrmLite.Sqlite)
as it's a common use-case to swapout to use Sqlite's in-memory provider for faster tests.
But as Sqlite doesn't provide async API's under-the-hood we fallback to *pseudo async* support where we just wrap its synchronous responses in `Task` results.


# Code-First DB Migrations
Source: https://docs.servicestack.net/ormlite/db-migrations

OrmLite DB Migrations advances OrmLite's light-weight code-first development approach with a simple [change based migration](https://www.prisma.io/dataguide/types/relational/what-are-database-migrations#change-based-migrations) solution that facilitates the code-first development workflow of OrmLite.

<div class="my-8 flex justify-center">
    <lite-youtube class="w-full mx-4 my-4" width="560" height="315" videoid="NIVFqute7JQ" style="background-image: url('https://img.youtube.com/vi/NIVFqute7JQ/maxresdefault.jpg')"></lite-youtube>
</div>

## Introduction

In contrast to [state-based migration](https://www.prisma.io/dataguide/types/relational/what-are-database-migrations#state-based-migrations) solutions which relies on tooling to generate state changes from a snapshot of a DB at a point-in-time with schema changes made out-of-band, OrmLite's DB migrations are instead designed to capture and execute the schema changes developers want to make, so when the Migrations are checked-in with the feature that needs them, the same exact changes are run by CI integration servers and other developers syncing their code-base with the new feature.

Instead of relying on generation by an opaque tool, this code-first approach treats DB Migrations like any other maintainable & logically structured code written by developers where it maintains a connected audit history in source control together with the feature that needs the schema changes.

## Getting Started

We'll start by looking at the minimum amount of code required for a Migration:

```csharp
class Migration1000 : MigrationBase
{
    public override void Up() {}
}
```

Which doesn't do anything but shows that the migration class name should adopt a numerical naming convention given class names are what determines the order in which migrations run. It also shows that a compensatory `Down()` implementation isn't required if you intend to adopt a **"Roll-Forward"** approach where any issues are resolved in subsequent migrations instead of reverting to a previous state so existing migrations can be refactored and re-run.

### Class names used to determine order of Migrations

We've decided upon using class names for determining the order migrations are run as it's important for their sequence to be clearly visible and easily navigable, a trait made possible with files being listed in alphabetical order making it easy to determine the order migrations were run and what the name of the next migration should be, it also gains assistance by the compiler in enforcing duplicates are not possible and source control ensures conflicting migration files are identified before they're checked in and run by CI.

## Basic Example

The `[Description]` or `[Notes]` attributes can instead be used to provide human-friendly descriptions of each migration where they'll be included in logs and included in the `Migration` table that's used to capture the execution of each migration.

With the basics covered lets look at using DB Migrations to create our first table:

```csharp
[Description("Create initial database tables")]
class Migration1000 : MigrationBase
{
    class MyTable
    {
        [AutoIncrement]
        public int Id { get; set; }
        public string Name { get; set; }
        public double ToDelete { get; set; }
    }

    public override void Up() => Db.CreateTable<MyTable>();
    public override void Down() => Db.DropTable<MyTable>();
}
```

First thing to notice is that the migrations do not reference our App's Data Models because migrations only contains the initial state and the deltas performed in each Migration, the result of which should match our App's Data Models which represent the current Data Models for the latest DB Schema.

::: tip
Initially these will match so you can just copy over all your Data Models as inner classes for your App's **1st Migration**
:::

## Declarative Code-First Migrations

To improve the typical development workflow your implementations can take advantage of declarative migration support which allows you to copy over new properties in your Data Models you want to **Add**, **Remove** or **Rename** as an alternative for writing procedural statements to perform the same changes with the [Modify Schema APIs](/ormlite/apis/schema.html#modify-custom-schema).

We'll use this feature in our 2nd migration for its Data Model changes where we want to:
 
 - **Add** a new `Code` VARCHAR column with **Index**
 - **Rename** the existing `Name` column to `FullName`
 - **Delete** the existing `ToDelete` column

For these common use-cases we can use `Migrate<Table>` to apply schema changes from a declarative class definition or use `Revert<Table>` to revert them, e.g:

```csharp
[Description("Update MyTable")]
class Migration1001 : MigrationBase
{    
    class MyTable
    {        
        [Index] //[AddColumn] (Optional default)
        public string Code { get; set; } //new field

        [RenameColumn("Name")]
        public string? FullName { get; set; }

        [RemoveColumn]
        public double ToDelete { get; set; }
    }
    
    public override void Up() => Db.Migrate<MyTable>();
    public override void Down() => Db.Revert<MyTable>();
}
```

## Imperative Migrations

In addition to being more productive and readable, it also benefits from being able to infer both schema migration and revert changes from the same declarative definition which is an alternative to using the [Modify Schema APIs](/ormlite/apis/schema.html#modify-custom-schema) to perform the same operations:

```csharp
[Description("Update MyTable")]
class Migration1001 : MigrationBase
{    
    class MyTable
    {        
        [Index]
        public string Code { get; set; }
        public double ToDelete { get; set; }
    }
    
    public override void Up()
    {
        Db.AddColumn<MyTable>(x => x.Code);
        Db.RenameColumn<MyTable>("Name", "FullName");
        Db.DropColumn<MyTable>("ToDelete");
    }

    public override void Down()
    {
        Db.DropColumn<MyTable>(x => x.Code);
        Db.RenameColumn<MyTable>("FullName", "Name");
        Db.AddColumn<MyTable>(x => x.ToDelete);
    }
}
```

Or for a more dynamic and Type-free approach it can also be rewritten as:

```csharp
[Description("Update MyTable")]
class Migration1001 : MigrationBase
{    
    public override void Up()
    {
        Db.AddColumn(table:"MyTable", new FieldDefinition { 
            Name = "Code", 
            FieldType = typeof(string), 
            IsIndexed = true 
        });
        Db.RenameColumn(table:"MyTable", oldColumn:"Name", newColumn:"FullName");
        Db.DropColumn(table:"MyTable", column:"ToDelete");
    }

    public override void Down()
    {
        Db.DropColumn(table:"MyTable", column:"Code");
        Db.RenameColumn(table:"MyTable", oldColumn:"FullName", newColumn:"Name");
        Db.AddColumn(table:"MyTable", new FieldDefinition { Name = "ToDelete", FieldType = typeof(string) });
    }
}
```

But our preference is to adopt the declarative approach when possible since it's a better match for code-first development where new or modified columns can be copied over from your App's Data Models to maintain and perform the schema changes. But ultimately you could use anything to implement your migration, from [Custom SQL](/ormlite/apis/schema.html#custom-sql) or as `Db` is just an ADO .NET Connection you could also use other Micro ORM's like [Dapper](https://github.com/DapperLib/Dapper) that's also [built-into OrmLite](https://github.com/ServiceStack/ServiceStack/tree/main/ServiceStack.OrmLite/src/ServiceStack.OrmLite/Dapper).

### Code-First approach

To get the most out of DB migrations it's recommended that all schema changes are done through migrations to ensure they end up capturing all schema changes and saves duplicated efforts from having to create Migrations from out-of-band schema changes. It's a more explicit approach than relying on a tool to generate migrations from state diffs, but you'll have more control over how changes are applied and organized together with any populated data required by new features which are tracked together in source control. They're also easier to debug, re-run and refactor during the development cycle of new features.

### Complex Example

For a more complex example we'll look at creating an isolated feature that utilizes many of OrmLite's declarative attributes to define a wide class of RDBMS features, that combines both schema creation and seed data within the same migration:

```csharp
[Description("Add Player Feature")]
public class Migration1002 : MigrationBase
{
    public class Player : AuditBase
    {
        public int Id { get; set; }                     // 'Id' is PrimaryKey by convention

        [Required]
        public string FirstName { get; set; }           // Creates NOT NULL Column

        [Alias("Surname")]                              // Maps to [Surname] RDBMS column
        public string LastName { get; set; }

        [Index(Unique = true)]                          // Creates Unique Index
        public string Email { get; set; }

        public List<Phone> PhoneNumbers { get; set; }   // Complex Types blobbed by default

        [Reference]
        public List<GameItem> GameItems { get; set; }   // 1:M Reference Type saved separately

        [Reference]
        public Profile Profile { get; set; }            // 1:1 Reference Type saved separately
        public int ProfileId { get; set; }              // 1:1 Self Ref Id on Parent Table

        [ForeignKey(typeof(Level), OnDelete="CASCADE")] // Creates ON DELETE CASCADE Constraint
        public Guid SavedLevelId { get; set; }          // Creates Foreign Key Reference

        public ulong RowVersion { get; set; }           // Optimistic Concurrency Updates
    }

    public class Phone                                  // Blobbed Type only
    {
        public PhoneKind Kind { get; set; }
        public string Number { get; set; }
        public string Ext { get; set; }
    }

    public enum PhoneKind { Home, Mobile, Work }

    [Alias("PlayerProfile")]                            // Maps to [PlayerProfile] RDBMS Table
    [CompositeIndex(nameof(Username), nameof(Region))]  // Creates Composite Index
    public class Profile : AuditBase
    {
        [AutoIncrement]                                 // Auto Insert Id assigned by RDBMS
        public int Id { get; set; }

        public PlayerRole Role { get; set; }            // Native support for Enums
        public Region Region { get; set; }
        public string Username { get; set; }
        public long HighScore { get; set; }

        [Default(1)]                                    // Created in RDBMS with DEFAULT (1)
        public long GamesPlayed { get; set; }

        [CheckConstraint("Energy BETWEEN 0 AND 100")]   // Creates RDBMS Check Constraint
        public short Energy { get; set; }

        public string ProfileUrl { get; set; }
        public Dictionary<string, string> Meta { get; set; }
    }
    
                                                        // Enums saved as strings by default
    public enum PlayerRole { Leader, Player, NonPlayer }

    [EnumAsInt]                                         // Enum Saved as int
    public enum Region { Africa = 1, Americas = 2, Asia = 3, Australasia = 4, Europe = 5 }

    public class GameItem
    {
        [PrimaryKey]                                    // Specify field to use as Primary Key
        [StringLength(50)]                              // Creates VARCHAR COLUMN
        public string Name { get; set; }

        public int PlayerId { get; set; }               // Foreign Table Reference Id

        [StringLength(StringLengthAttribute.MaxText)]   // Creates "TEXT" RDBMS Column 
        public string Description { get; set; }

        [Default(OrmLiteVariables.SystemUtc)]           // Populated with UTC Date by RDBMS
        public DateTime DateAdded { get; set; }
    }

    public class Level
    {
        public Guid Id { get; set; }                    // Unique Identifier/GUID Primary Key
        public byte[] Data { get; set; }                // Saved as BLOB/Binary where possible
    }
    private string by = "admin@email.com";

    public override void Up()
    {
        //CREATE ForeignKey Tables in dependent order
        Db.CreateTable<Level>();
        Db.CreateTable<Player>();

        //CREATE tables without Foreign Keys in any order
        Db.CreateTable<Profile>();
        Db.CreateTable<GameItem>();

        var savedLevel = new Level {
            Id = Guid.NewGuid(),
            Data = new byte[]{ 1, 2, 3, 4, 5 },
        };
        Db.Insert(savedLevel);

        var player = new Player
        {
            Id = 1,
            FirstName = "North",
            LastName = "West",
            Email = "north@west.com",
            PhoneNumbers = new List<Phone> {
                new() { Kind = PhoneKind.Mobile, Number = "123-555-5555" },
                new() { Kind = PhoneKind.Home,   Number = "555-555-5555", Ext = "123" },
            },
            GameItems = new List<GameItem> {
                new() { Name = "WAND", Description = "Golden Wand of Odyssey"},
                new() { Name = "STAFF", Description = "Staff of the Magi"},
            },
            Profile = new Profile {
                Username = "north",
                Role = PlayerRole.Leader,
                Region = Region.Australasia,
                HighScore = 100,
                GamesPlayed = 10,
                ProfileUrl = "https://images.unsplash.com/photo-1463453091185-61582044d556?w=1024&h=1024",
                Meta = new() {
                    { "Quote", "I am gamer" }
                },
            }.WithAudit(by),
            SavedLevelId = savedLevel.Id,
        }.WithAudit(by);
        Db.Save(player, references: true);
    }
    
    public override void Down()
    {
        // Clear FK Data
        Db.DeleteAll<Level>();

        // DROP ForeignKey Tables in dependent order
        Db.DropTable<Level>();
        Db.DropTable<Player>();

        // DROP tables without Foreign Keys in any order
        Db.DropTable<Profile>();
        Db.DropTable<GameItem>();
    }
}
```

Essentially showing the App Data Models for the initial version of a feature can be copied into a Migration class to perform the required database changes.

### Reverting Migrations

Implementing `Down()` is optional but required if you ever intend to revert, refactor then reapply migrations. Alternatively this can be avoided by adopting a **"roll-forward"** approach where any issues with a migration would be resolved in the next one. Whilst this can save some dev effort it would prevent you from reverting, refactoring then reapplying migrations during development and before checking-in a finalized feature.

Migrations are executed within a transaction that's rolled back if it fails, however you should be aware of the limitations of your RDBMS, e.g. [newer MySQL versions has caveats on DDL Statements](https://dev.mysql.com/doc/refman/8.0/en/atomic-ddl.html#atomic-ddl-supported-statements) which can be rolled back, but otherwise it's fairly well supported on PostgreSQL, SQL Server & SQLite.

In most cases you'll be able to revert & rerun migrations however you should be mindful that some operations aren't completely reversible, e.g. if you remove a column then revert to add it again, the data in the column will be lost. 

## Running Migrations

To support multiple use-cases, Migrations can easily be run from the command-line or from code which you can use to run or debug migrations from Unit tests.

### Run or Debug Migrations from your IDE

A benefit of DB Migrations being implemented in a library is that it's better integrated and more versatile in supporting more executable options like being able to run from code which many project templates benefit from with new `MigrationTasks` Explicit TestFixture enabling DB Migrations to be run or debugged directly from within your IDE, implemented as:

 ```csharp
[TestFixture, Explicit, Category(nameof(MigrationTasks))]
public class MigrationTasks
{
    IDbConnectionFactory ResolveDbFactory() => new ConfigureDb().ConfigureAndResolve<IDbConnectionFactory>();
    Migrator CreateMigrator() => new(ResolveDbFactory(), typeof(Migration1000).Assembly); 
    
    [Test]
    public void Migrate()
    {
        var migrator = CreateMigrator();
        var result = migrator.Run();
        Assert.That(result.Succeeded);
    }

    [Test]
    public void Revert_All()
    {
        var migrator = CreateMigrator();
        var result = migrator.Revert(Migrator.All);
        Assert.That(result.Succeeded);
    }

    [Test]
    public void Revert_Last()
    {
        var migrator = CreateMigrator();
        var result = migrator.Revert(Migrator.Last);
        Assert.That(result.Succeeded);
    }

    [Test]
    public void Rerun_Last_Migration()
    {
        Revert_Last();
        Migrate();
    }
}
```

Which uses your App's `ConfigureDb` [Modular Startup](/modular-startup) configuration to resolve your App's configured `OrmLiteConnectionFactory` that the migrations are run against, that if needed can be run from Unit tests to debug through any schema migration issues.

#### Revert and Rerun Last Migration

The `Rerun_Last_Migration` task is especially useful during development of new features to easily revert and rerun the last migration before checking in a completed feature, allowing you to re-iterate and check in a completed and tested DB migration along with the new feature requiring it instead of multiple "micro migrations" for each DB change run at different times.

## Running migrations from command-line

To be able to run from migrations from the command line, DB Migrations needs access to your App's DB configuration. The best way to do this is to run your App normally then access the configured `IDbConnectionFactory` from the IOC, perform the migrations then exit with either a success or failure error code.

To do this we've added support for **AppTasks** which let you define tasks in your App that you can run from the command-line. This will let you perform migrations in a separate stage to check migrations were successful before running your App.

### Configuring existing Projects

You can add DB Migration support to existing projects by applying the [migrations](https://gist.github.com/gistlyn/50df00df4b3b9faa94a73d32ab4b2484) gist to your project with:

:::sh
x mix migrations
:::

This will register the Migration **AppTasks** with your App via a [Modular Startup](/modular-startup) configuration:

```csharp
public class ConfigureDbMigrations : IHostingStartup
{
    public void Configure(IWebHostBuilder builder) => builder
        .ConfigureAppHost(afterAppHostInit:appHost => {
            var migrator = new Migrator(appHost.Resolve<IDbConnectionFactory>(), typeof(Migration1000).Assembly);
            AppTasks.Register("migrate", _ => migrator.Run());
            AppTasks.Register("migrate.revert", args => migrator.Revert(args[0]));
            AppTasks.Run();
        });
}
```

Here we can see we need to configure our `Migrator` with the `IDbConnectionFactory` we want to run against and the assemblies where all our Migration classes are maintained. It also registers an AppTasks to **migrate** our App by comparing the **Migration** table with the Migrations in the specified Assembly to workout which Migrations are left to run (in order) and the **revert** AppTask to do the opposite and revert to the specified migration.

This will now let us run your app in **"Task Mode"** where it will execute the specified task before promptly exiting with a **0** success exit code if successful or the index of the task that failed, e.g. **1** if the first Task failed. 

### dotnet Migration Tasks

We can then execute our App Task by running our App with the `AppTasks` command-line argument of the Task we want to run, so we can run all pending migrations with:

:::sh
dotnet run --AppTasks=migrate
:::

The format to revert a migration is:

:::sh
dotnet run --AppTasks=migrate.revert:<name>
:::

Where **name** is either the class name of the Migration you want to revert to (inclusive) or you can use **last** to revert the last migration:

:::sh
dotnet run --AppTasks=migrate.revert:last
:::

or **all** to revert all migrations:

:::sh
dotnet run --AppTasks=migrate.revert:all
:::

### npm Migration Scripts

To make this easier to remember and use, these tasks are also added as npm scripts:

```json
{
  "scripts": {
    "migrate": "dotnet run --AppTasks=migrate",
    "revert:last": "dotnet run --AppTasks=migrate.revert:last",
    "revert:all": "dotnet run --AppTasks=migrate.revert:all",
    "rerun:last": "npm run revert:last && npm run migrate"
  }
}
```

Which can be run with:

```bash
$ npm run migrate
$ npm run revert:last
$ npm run revert:all
$ npm run rerun:last
```

Which Rider provides a nice UX for running directly from the IDE where it will print all executed SQL output in a dedicated Console:

![](/img/pages/ormlite/migration-scripts.png)

### ASP .NET Core Projects

General (i.e. non-ServiceStack) ASP.NET Core Apps can instead configure AppTasks before `app.Run()` in their **Program.cs**:

```csharp
var migrator = new Migrator(app.Services.Resolve<IDbConnectionFactory>(), typeof(Migrations.Migration1000).Assembly);
AppTasks.Register("migrate", _ => migrator.Run());
AppTasks.Register("migrate.revert", args => migrator.Revert(args[0]));
AppTasks.Run();

app.Run();
```

### New RDBMS Projects configured with DB Migrations by default

Now that OrmLite has a formal solution for implementing and executing schema changes, the [Quick install RDBMS mix scripts](/ormlite/installation.html#quick-install-in-asp-net-core-with-mix) 
are now configured to include **migrations** by default.

### Run OrmLite and Entity Framework Migrations together

For convenience if you're using both Entity Framework and OrmLite within the same project you can change the `npm run migrate`
AppTask to run both Entity Framework and OrmLite Migrations by expanding the AppTask to run EF Migrations:

```csharp
public class ConfigureDbMigrations : IHostingStartup
{
    public void Configure(IWebHostBuilder builder) => builder
        .ConfigureAppHost(appHost => {
            var migrator = new Migrator(appHost.Resolve<IDbConnectionFactory>(), typeof(Migration1000).Assembly);
            AppTasks.Register("migrate", _ =>
            {
                var log = appHost.GetApplicationServices().GetRequiredService<ILogger<ConfigureDbMigrations>>();
                log.LogInformation("Running EF Migrations...");
                var scopeFactory = appHost.GetApplicationServices().GetRequiredService<IServiceScopeFactory>();
                using (var scope = scopeFactory.CreateScope())
                {
                    using var db = scope.ServiceProvider.GetRequiredService<ApplicationDbContext>();
                    db.Database.EnsureCreated();
                    db.Database.Migrate();
                }
                log.LogInformation("Running OrmLite Migrations...");
                migrator.Run();
            });
            AppTasks.Register("migrate.revert", args => migrator.Revert(args[0]));
            AppTasks.Run();
        });
}
```

## Running migrations from GitHub Actions

Where applicable, [GitHub Action deployments](/github-action-templates) have been updated to automatically run on deployment before the new 
version of your application starts up. This is done in the **Run remote db migrations** step. 

Output can be found in your GitHub Action run output. The task that is run is controlled in the `.deploy/docker-compose-template.yml` 
file as a separate service which is only run if specified directly or with the `--profiles migration` option.

::: info
If you are using the template GitHub Actions and deploying to an Ubuntu 22.04 server, ensure you ssh key is generated using non RSA SHA1 algorithm.
Eg `ssh-keygen -t ecdsa` or swap out the use of `appleboy/scp-action@v0.1.3` for your own step using the latest version of the `scp` command line tool in your CI environment.
For a step by step and other options, see [this Ask Ubuntu Answer](https://askubuntu.com/a/1409528/366659)
:::

This migration approach enables an easy way to test your migration with a custom local docker compose file. Such as the following for a SQLite setup.

```yaml
version: "3.9"
services:
  myapp-migration:
    build: .
    restart: "no"
    command: --AppTasks=migrate
    volumes:
      - myapp-mydb:/app/App_Data

volumes:
  myapp-mydb:
```

::: info
Ensure you have v2+ of Docker Compose
A compatibility script can be used for `docker-compose` via the following script.
`echo 'docker compose --compatibility "$@"' > /usr/local/bin/docker-compose`
`sudo chmod +x /bin/docker-compose`
:::

### Failed migration behavior

Executing migrations from the command-line is also how they are run in CI. The strategy we've employed in our
[GitHub Action Deployment Templates](/github-action-templates) is to run the container to execute the **migrate** AppTask on the host
machine first to validate migration was successful before completing deployment of the new App, so that a failed migration
will cause deployment to fail and the previous App version to continue to run.

::: info
Ensure you are using Docker Compose v2+ and `--exit-code-from` the migration service in the `release.yml` file, in the 
`Run remote db migrations` step.
:::

## Running migrations from unit tests

The migration printed in the console output and captured in the **Migration** table should typically be enough to identify any issues, but should it be needed you can also debug Migrations in a unit test with:

```csharp
var migrator = new Migrator(DbFactory, typeof(Migration1000).Assembly);
var result = migrator.Run();

result.Succeeded // true if successful
result.TasksRun  // instances of MigrationBase run, can inspect `Error` for failed Exceptions and `Log` for executed SQL
result.TypesCompleted // Migration Types successfully completed
```

Likewise uou can revert using the `Revert()` method which accepts the same options as the command-line, e.g. Migration Type name, **"all"** or **"last"**:

```csharp
var result = migrator.Revert(Migrator.All);
```

## Running Migrations individually 

Should you ever need to, you can also run individual Migrations with the static `Up()` and `Down()` methods, e.g:

```csharp
Migrator.Up(DbFactory,   new[]{ typeof(Migration1000), typeof(Migration1001) });
Migrator.Down(DbFactory, new[]{ typeof(Migration1001), typeof(Migration1000) });
```

These lets you execute migration logic out-of-band where they'll have no impact on the **Migration** table which can be useful in developing & iterating migration implementations by removing/re-adding a feature's schema changes without impacting migration state.

### Clearing Migration State

To clear your migration table at the start of tests, run:

```csharp
var db = DbFactory.Open();
Migrator.Clear(db);
```

### Running Migrations on Named Connections

By default the Migration's `base.Db` connection is configured to use the primary database's connection string, e.g:

```csharp
var dbFactory = new OrmLiteConnectionFactory(
    Configuration.GetConnectionString("DefaultConnection"), PostgreSqlDialect.Provider);    
services.AddSingleton<IDbConnectionFactory>(dbFactory);
```

But if your App has [Multiple database connections](/ormlite/getting-started#multiple-database-connections) that you need to run migrations on, e.g:

```csharp
dbFactory.RegisterConnection("Sales", Configuration.GetConnectionString("Sales"), SqlServer2012Dialect.Provider);
dbFactory.RegisterConnection("Reporting", "reporting.sqlite", SqliteDialect.Provider);
```

You can configure the Migration `base.Db` connection to be configured to use a named connection with the `[NamedConnection]` attribute, e.g:

```csharp
[NamedConnection("Sales")]
class Migration1000 : MigrationBase
{
    class Order
    {
        public decimal Freight { get; set; }
    }

    public override void Up() => Db.Migrate<Order>();
    public override void Down() => Db.Revert<Order>();
}
```

Where you would maintain schema changes to different Databases in different Migrations, alternatively you could use `base.DbFactory` to create connections to named connections within the same Migration, e.g:


```csharp
class Migration1000 : MigrationBase
{
    class Order
    {
        public decimal Freight { get; set; }
    }

    class Subscription
    {
        public string Referral { get; set; }
    }

    public override void Up()
    {
        using var dbSales = DbFactory.Open("Sales");
        dbSales.Migrate<Order>();

        using var dbReporting = DbFactory.Open("Reporting");
        dbReporting.Migrate<Subscription>();
    }

    public override void Down()
    {
        using var dbSales = DbFactory.Open("Sales");
        dbSales.Revert<Order>();

        using var dbReporting = DbFactory.Open("Reporting");
        dbReporting.Revert<Subscription>();
    }
}
```

::: info
Whilst schema changes are run on different RDBMS's, all migration state is maintained in the **primary database's** `Migration` table
:::

### Multiple Named Connections

DB Migrations also support running and reverting Migrations on multiple named connections, e.g:

```csharp
[NamedConnection("mssql")]
[NamedConnection("mysql")]
[NamedConnection("postgres")]
public class Migration1001 : MigrationBase
{
    //...
}
```

This feature is likely more useful for maintaining the same schema across multiple database shards, which is a
[popular scaling technique](https://aws.amazon.com/what-is/database-sharding/) to increase system capacity and improve response times:

```csharp
[NamedConnection("shard1")]
[NamedConnection("shard2")]
[NamedConnection("shard3")]
public class Migration1001 : MigrationBase
{
    //...
}
```

## Reviewing Migrations

The output of each Migration is logged to the Console (or configured Logger), logging useful information on Migrations found and run as well as the executed SQL run in each migration. This information is also captured in the **Migration** table on the database they were run on, where they can be easily viewed in your App's [Database Admin UI](/admin-ui-database), e.g:

[![](/img/pages/ormlite/migration-database-admin.png)](/admin-ui-database)

::: tip
In addition to capturing executed SQL in the `Log` column, failed Migrations capture error information in the `ErrorCode`, `ErrorMessage` and `ErrorStackTrace` columns
:::

## Feedback Welcome

We hope you'll find this first version of DB Migrations useful, please let us know what other features you would like in [ServiceStack/Discuss](https://github.com/ServiceStack/Discuss/discussions).


# Litestream
Source: https://docs.servicestack.net/ormlite/litestream

<div class="not-prose hide-title">
<h2 id="litestream" class="mx-auto max-w-screen-md text-center py-8 border-none">
    <a href="https://litestream.io">
        <img src="/img/pages/litestream/logo.svg">
    </a>
</h2>
</div>

One of ServiceStack's primary goals is delivering great value and performance, attributes exemplified in all modern [jamstacks.net](https://jamstacks.net) templates which are maximally designed to deliver ultimate performance for a .NET App by adopting a [Jamstack architecture](https://jamstack.org), enabling redundant hosting of their decoupled UI's on inexpensive CDN edge caches - most optimal place to deliver best performance. 

This also happens to be the cheapest to place to host its static files, taking load away from more expensive .NET App Servers and move them to free Cloudflare or GitHub CDNs, which all Jamstack Live Demos take advantage of to enable their [**$0.40 /mo** TCO](https://jamstacks.net/posts/jamstacks_hosting) for hosting their .NET Docker Apps which are only needed to serve the JSON APIs used to power their Jamstack UIs.

## Expensive Managed Databases

Having achieved the ideal architecture for max value and performance, the last expensive vital component used in most Web Apps is hosting of their expensive managed databases. Despite most RDBMS's being OSS and free of licensing costs, major cloud companies continue to charge artificially high hosting costs to provide redundant hosting of App data. The effect of which adds an artificial barrier to entry discouraging new Indie developers from building & hosting their dream Apps that could form self sustaining business models that should ideally be accessible to anyone with access to a Computer with the Internet.

If we solve this, Individual developers can take advantage of our [Free Licenses](https://servicestack.net/free) for experimenting and iterating on building their dream Apps for a few $'s a month, instead of their prohibitive recommended setup costing $100's /month.

<div id="litestream-interest" class="not-prose relative bg-white py-4 mt-12">
    <div class="mx-auto max-w-md px-4 text-center sm:max-w-3xl sm:px-6 lg:max-w-7xl lg:px-8">
        <p class="text-4xl tracking-tight font-extrabold text-gray-900 sm:text-5xl md:text-6xl">Introducing Litestream</p>
    </div>
</div>

Our [Jamstack live demos](https://jamstacks.net) have been able to avoid these expensive costs by being configured with [SQLite](https://www.sqlite.org) by default, which OrmLite lets you easily change to use your [preferred RDBMS](/ormlite/installation). But when storing live customer data you'll want to ensure you have redundant backups to protect against data loss and why we were excited to learn about [Litestream](https://litestream.io) for enabling effortless replicas & restores to a number of [popular storage providers](https://litestream.io/guides/).

Litestream is being developed by [@benbjohnson](https://twitter.com/benbjohnson), the creator of the popular [BoltDB NoSQL embeddable DB](https://github.com/boltdb/bolt), used in a number of critical software components like [etcd](https://www.ibm.com/cloud/learn/etcd) to manage critical information distributed systems need, most notably, the configuration, state and metadata for [Kubernetes](https://kubernetes.io).

Thankfully Ben saw the potential for SQLite as a better replacement of BoltDB as a dependency-free application database and went about resolving the primary issue preventing SQLite from being used in production server-side Apps.

<div class="not-prose">
<h3 class="text-3xl">
    <a href="https://litestream.io/blog/why-i-built-litestream/#the-problem-litestream-solves">
        The problem Litestream solves
    </a>
</h3>
<div class="pl-16 py-9">
  <div class="text-gray-500 font-serif text-9xl -mb-16">“</div>
  <blockquote class="text-gray-900 font-serif text-xl italic">
    <p>
        I built Litestream to bring back sanity to application development. Litestream is a tool that runs in a separate process and continuously replicates a SQLite database to Amazon S3. You can get up and running with a few lines of configuration. Then you can set-it-and-forget-it and get back to writing code.
    </p>
    <p class="mt-8">
        You might think this sounds expensive to continuously write to cloud storage that provides 99.99% uptime and 99.999999999% durability but it’s astoundingly cheap. Typical costs are only about $1 per month. Litestream is free and open-source too so there’s never a license to pay for.
    </p>
  </blockquote>
  <div class="mt-4 text-gray-600">- Ben Johnson</div>
</div>
</div>

We're so excited about the inexpensive cost, minimal infrastructure dependencies and simplified hosting complexity of this new approach that we quickly set out to provide integrated support for Litestream.

<div class="not-prose">
<div class="my-16 px-4 sm:px-6">
    <div class="text-center">
        <h3 id="litestream-video" class="text-4xl sm:text-5xl md:text-6xl tracking-tight font-extrabold text-gray-900">
            Safely run DB Apps on a single server at low cost
        </h3>
    </div>
        <p class="mx-auto mt-5 max-w-prose text-xl text-gray-500"> 
            Simple &amp; Fast! Litestream reliably runs most Apps, fast on a single server, with continuous backups to cheap managed storage.
        </p>
    <div class="my-8">
        <lite-youtube class="w-full mx-4 my-4" width="560" height="315" videoid="WXRwT7ayc1Y" style="background-image: url('https://img.youtube.com/vi/WXRwT7ayc1Y/maxresdefault.jpg')"></lite-youtube>
    </div>
</div>
<section class="my-10 text-center">
    <div class="container">
        <div class="pb-8">
            <h3 id="litestream-how" class="text-4xl tracking-tight font-extrabold text-gray-900 sm:text-5xl md:text-6xl">
                <span class="block xl:inline">How it works</span>
            </h3>
            <p class="mt-3 max-w-md mx-auto text-base text-gray-500 sm:text-lg md:mt-5 md:text-xl md:max-w-3xl">
                Litestream is run as a 
                <a href="https://litestream.io/guides/docker/">sidecar Docker container</a>,
                activated on each deployment to handle restoring &amp; replicating changes from its configured storage
            </p>
        </div>
        <img src="/img/pages/litestream/litestream-how-it-works.svg">
    </div>
</section>
</div>

## Boringly Simple

Litestream's implementation is beautiful in its simplicity which doesn't require any libraries or custom builds of SQLite, it works as an external process transparent to your application that taps into SQLite's journaling features to handle replicating changes to its configured storage provider:

<div class="not-prose pl-16 py-9">
  <div class="text-gray-500 font-serif text-9xl -mb-16">“</div>
  <blockquote class="text-gray-900 font-serif text-xl italic">
    <p>
        The most important thing you should understand about Litestream is that it's just SQLite. Your application uses standard SQLite, with whatever your standard SQLite libraries are. We're not parsing your queries or proxying your transactions, or even adding a new library dependency. We're just taking advantage of the journaling and concurrency features SQLite already has, in a tool that runs alongside your application. For the most part, your code can be oblivious to Litestream's existence.
    </p>
    <p class="mt-8">
        Or, think of it this way: you can build a Remix application backed by Litestream-replicated SQLite, and, while it's running, crack open the database using the standard <b>sqlite3</b> REPL and make some changes. It'll just work.
        You can read more about <a href="https://litestream.io/how-it-works/">how this works here</a>.
    </p>
  </blockquote>
  <div class="mt-4 text-gray-600">- Ben Johnson</div>
</div>

## The Right Time for Server-Side SQLite

Over the years CPUs, memory, & disks have become orders of magnitude faster & cheaper which now sees NVMe SSDs being able to read an entire 1 GB database in <1 second, what's not getting faster is the speed of light and the latency it takes for data to travel between networked components that's further exacerbated by 
the necessary layers of network switches, firewalls, and application protocols undertaken in each HTTP Request.

Whilst modern RDBMS's are finely-tuned modern miracles, the one thing they don't have any control over is the latency between its distributed components. A latency SQLite doesn't have courtesy of being built right in to your application process which sees per-query latency's drop down to 10-20 microseconds - a **50-100x** improvement over intra-region RDBMS queries.

In addition to applications benefiting from latency-free queries, they also become much simpler to manage, replacing entire infrastructure dependencies and n-tier architectures with a transparent sidecar process that continuously monitors and performs per-second backups to AWS S3, Azure Blob Storage & SFTP providing resilient, cost effective point-in-time restore functionality.

Best of all storing bytes is a boringly simple solved problem AWS guarantees with [11 9's durability](https://aws.amazon.com/s3/storage-classes/), a marked improvement over the [3 9's guarantee](https://aws.amazon.com/rds/sla/) when their first tier SLA kicks in for its managed RDS instances.

<div class="not-prose mt-16 mx-auto max-w-7xl px-4">
    <div class="text-center">
        <h3 class="text-4xl tracking-tight font-extrabold text-gray-900 sm:text-5xl md:text-6xl">
            <span class="block xl:inline">Reduce Complexity &amp; Save Costs</span>
        </h3>
        <p class="mt-3 max-w-md mx-auto text-base text-gray-500 sm:text-lg md:mt-5 md:text-xl md:max-w-3xl">
            Avoid expensive managed RDBMS servers, reduce deployment complexity, eliminate 
            infrastructure dependencies & save order of magnitude costs vs production hosting
        </p>
    </div>
    <img src="/img/pages/litestream/litestream-costs.svg">
</div>

## Commercially supported thanks to Fly.io

Whilst SQLite enjoys enviable reliability with one of the [most thoroughly tested](https://www.sqlite.org/testing.html) code-bases on earth, it's usage in server production databases is still nascent given there hasn't been a tool that works as seamlessly as Litestream to enable transparent replication & restores. On the surface Litestream appears to be great boring technology, beautiful in its simplicity but we only started seriously considering it for server production apps after it graduated from OSS project to a commercially supported product when Ben joined Fly.io to [work on Litestream full-time](https://fly.io/blog/all-in-on-sqlite-litestream/).

Already being excited in its potential, this was enough to immediately start work on our support for Litestream, creating load tests calling ServiceStack [AutoQuery APIs](/autoquery/) querying SQLite + Litestream to test the viability for ourselves which we we're pleasantly surprised to see it's performance and cost savings held up under load: 

<section class="not-prose my-10 text-center">
    <div class="container">
        <div class="">
            <h3 id="savings-at-scale" class="text-4xl tracking-tight font-extrabold text-gray-900 sm:text-5xl md:text-6xl">
                <span class="block xl:inline">Savings at Scale</span>
            </h3>
            <p class="mt-3 max-w-md mx-auto text-base text-gray-500 sm:text-lg md:mt-5 md:text-xl md:max-w-3xl">
                SQLite directly benefits from improving hardware's faster CPUs and SSDs with superior locality to comfortably handle most App's needs. 
            </p>
        </div>
        <img src="/img/pages/litestream/litestream-costs-perf.svg">
    </div>
</section>

We share Ben's enthusiasm and thoughts on [SQLite has become a viable option](https://fly.io/blog/all-in-on-sqlite-litestream/#you-should-take-this-option-more-seriously) for Server-side production App databases that can handle most App needs. Litestream's 
architecture [does have limitations](https://fly.io/blog/all-in-on-sqlite-litestream/#small-fast-reliable-globally-distributed-choose-any-four) where it's only suitable for single-node applications, its effortless replication will let you scale out your reads to read-only replicas, but your writes need to be either sharded or limited to a single Application. 

In effect, instead of managing Kubernetes clusters you'll need to scale up [Majestic Monolith's](https://m.signalvnoise.com/the-majestic-monolith/), a practice some high-performance sites like [StackOverflow have adopted](https://www.hanselminutes.com/847/engineering-stack-overflow-with-roberta-arcoverde) who instead of caching hot pages, have evaluated it was better to give their SQL Server 1.5TB RAM. An architectural overview of servers used to handle their impressive load:

 - 2B page views /month
 - 6000 req /sec
 - 9 servers @ 5/10% capacity
 - 1.5 TB RAM SQL Server

So whilst scaling up is an option, SQLite's no-frills core SQL featureset allows for easy migrations should you wish to migrate to micro services in future, a task effortless in [OrmLite](/ormlite/) which provides an implementation agnostic abstraction for the most popular RDBMS's.

<section class="not-prose text-center">
    <div class="container">
        <div class="">
            <h3 id="effortless-migrations" class="text-4xl tracking-tight font-extrabold text-gray-900 sm:text-5xl md:text-6xl">
                <span class="block xl:inline">Effortless Migrations</span>
            </h3>
            <p class="mt-3 max-w-md mx-auto text-base text-gray-500 sm:text-lg md:mt-5 md:text-xl md:max-w-3xl">
                No Lock-in. Migrate off whenever you want. <br> <br>
                Using SQLite with <a href="/ormlite/">OrmLite's</a> fast, typed APIs
                lets you easily migrate to any of its 
                <a href="/ormlite/installation">supported RDBMS</a> with just configuration, no other code changes required.
            </p>
        </div>
        <div class="flex justify-center pb-8 my-8">
            <img src="/img/pages/litestream/litestream-migrate.svg" class="max-w-screen-md">
        </div>
    </div>
</section>

The beauty of Litestream is that it happily runs in the background transparent to your application who doesn't need to make any changes to take advantage of it, the way to enable it is by including Litestream along with your app's deployment workflow and running it as a dedicated [sidecar container](https://docs.microsoft.com/en-us/azure/architecture/patterns/sidecar) where it restores and watches for updates to your SQLite database, replicating those changes to your configured storage.


<section class="not-prose my-20 text-center">
    <div class="container">
        <div class="">
            <h3 id="litestream-apps" class="text-4xl tracking-tight font-extrabold text-gray-900 sm:text-5xl md:text-6xl">
                <span class="block xl:inline">Create Litestream Apps</span>
            </h3>
            <p class="mt-3 max-w-md mx-auto text-base text-gray-500 sm:text-lg md:mt-5 md:text-xl md:max-w-3xl">                              
                To make it easy, we've created <a href="/github-action-templates">GitHub Action</a> Docker Compose configurations for each of Litestream's popular Storage options:
            </p>
        </div>
    </div>
</section>

<section class="not-prose my-20 text-center">
    <div class="flex">
        <div class="flex flex-1 flex-col">
            <a href="https://servicestack.net/litestream#Name=MyApp&Mix=x-litestream-aws">
                <img src="/img/pages/litestream/aws_square.svg" alt="AWS S3" class="w-52">
            </a>
            <span class="block text-2xl font-medium text-gray-900">
                S3 Simple Storage Service
            </span>
        </div>
        <div class="flex flex-1 flex-col">
            <a href="https://servicestack.net/litestream#Name=MyApp&Mix=x-litestream-azure">
                <img src="/img/pages/litestream/azure_square.svg" alt="Azure Blob Storage" class="w-52">
            </a>
            <span class="block text-2xl font-medium text-gray-900">
                Azure Blob Storage
            </span>
        </div>
        <div class="flex flex-1 flex-col">
            <a href="https://servicestack.net/litestream#Name=MyApp&Mix=x-litestream-sftp">
                <img src="/img/pages/litestream/sftp.png" alt="SFTP" class="w-52">
            </a>
            <span class="block text-2xl font-medium text-gray-900">
                SSH File Transfer Protocol
            </span>
        </div>
    </div>
    <div class="mt-10">
        <p class="max-w-md mx-auto text-base text-gray-500 sm:text-lg md:mt-5 md:text-xl md:max-w-3xl">                              
            That you can mix with any modern C# jamstacks.net Project Templates:
        </p>
        <a href="https://servicestack.net/litestream#create">
            <img src="/img/pages/litestream/litestream-project-templates.png" class="max-w-prose">
        </a>
    </div>
</section>

Alternatively as the [Docker compose](/github-action-templates) configurations are delivered as [mix](/mix-tool) configurations, they can also be applied to existing projects, e.g:

::: sh
x mix litestream-aws
:::

Since Litestream is tied to deployment, hosting environment & preferred configured storage, we've had to create a matrix of configurations to integrate with each of the above templates.

| Project Template     | AWS S3                  | Azure Blob Storage        | SFTP (generic)           | 
|----------------------|-------------------------|---------------------------|--------------------------|
| **web**              | litestream-aws          | litestream-azure          | litestream-sftp          | 
| **blazor**           | blazor-litestream-aws   | blazor-litestream-azure   | blazor-litestream-sftp   |
| **blazor-vue**       | blazor-litestream-aws   | blazor-litestream-azure   | blazor-litestream-sftp   |
| **blazor-wasm**      | blazor-litestream-aws   | blazor-litestream-azure   | blazor-litestream-sftp   |
| **vue-ssg**          | jamstack-litestream-aws | jamstack-litestream-azure | jamstack-litestream-sftp |
| **vue-vite**         | jamstack-litestream-aws | jamstack-litestream-azure | jamstack-litestream-sftp |
| **nextjs**           | jamstack-litestream-aws | jamstack-litestream-azure | jamstack-litestream-sftp |

## GitHub Action Workflow

These GitHub Action configurations are an effortless way to create and deploy new Applications within minutes, which only need to be filled in with your environment's access credentials configured in your [projects GitHub Action Secrets](/litestream-templates.html#github-action-workflow).

For a detailed overview for creating and setting up deployment for a new App from scratch checkout:

<lite-youtube class="w-full mx-4 my-4" width="560" height="315" videoid="fY50dWszpw4" style="background-image: url('https://img.youtube.com/vi/fY50dWszpw4/maxresdefault.jpg')"></lite-youtube>


# Install PostgreSQL, MySql and SQL Server with Docker
Source: https://docs.servicestack.net/ormlite/install-postgres-mysql-sqlserver

Installing developer tools has become frictionless in today's world of ubiquitous Docker adoption. First thing you'll 
need to install is [Docker Desktop](https://www.docker.com/products/docker-desktop/) which will let you run each RDBMS 
in a containerized Docker App.

After Docker is running, installing and running PostgreSQL and MySql can be done with a single command:

## Install and run PostgreSQL

:::copy
docker run --name postgres -e POSTGRES_PASSWORD=p@55wOrd -p 127.0.0.1:5432:5432 -d postgres
:::

## Install and run MySql

:::copy
docker run --name mysql -p 3306:3306 -e MYSQL_ROOT_PASSWORD=p@55wOrd -d mysql:latest
:::

> Feel free to update commands to use your preferred strong password instead

## Install and run SQL Server

SQL Server requires more resources than the popular RDBMS's and as it doesn't have a native ARM Docker Image requires
a bit more configuration.

First you'll want to ensure you have at least **4GB RAM** available to containers from
the **Resources** Tab in Docker Settings you can open with `⌘,`

![](https://servicestack.net/img/posts/postgres-mysql-sqlserver-on-apple-silicon/docker-resources.png)

## Apple Silicon

Our MacBook Air's **24GB RAM** configuration defaulted to **7.9 GB**, but if you have a lower configuration you'll want 
to ensure **4GB** is available to SQL Server.

If you're running on Apple Silicon you'll want to ensure **Use Virtualization Framework** and **VirtioFS** is checked
in the **General** tab which will allow SQL Server **AMD64** Image will run on Apple's new
[Virtualization framework](https://developer.apple.com/documentation/virtualization):

![](https://servicestack.net/img/posts/postgres-mysql-sqlserver-on-apple-silicon/docker-general.png)

After which you'll be able to install and run SQL Server with:

:::copy
docker run --platform=linux/amd64 --name mssql -e ACCEPT_EULA=1 -e MSSQL_SA_PASSWORD=p@55wOrd -p 1433:1433 -d mcr.microsoft.com/mssql/server:2022-latest
:::

You'll be able to check if all Docker containers are now running by clicking on the **Containers** tab in Docker Desktop:

![](https://servicestack.net/img/posts/postgres-mysql-sqlserver-on-apple-silicon/docker-containers.png)

## lazydocker

Another great alternative to Docker Desktop for managing Docker Containers is [lazydocker](https://github.com/jesseduffield/lazydocker) 
which can be installed with:

### macOS

:::sh
brew install lazydocker
:::

### Chocolatey (Windows)

Using [Chocolatey](https://chocolatey.org) is an easy way to install on Windows: 

:::sh
choco install lazydocker
:::

As lazydocker a Terminal UI it can be run everywhere where there's a Terminal, in local and remote terminals as well as
Rider and VS Code's built-in Terminal UIs where you can quickly perform Docker tasks without breaking your development
workflow:

[![](https://servicestack.net/img/posts/postgres-mysql-sqlserver-on-apple-silicon/lazydocker.png)](https://github.com/jesseduffield/lazydocker)

## DataGrip

Now we can see they're all running, lets connect to them. You could use the command line tools specific to each database
but my preference is to use [JetBrains DataGrip](https://www.jetbrains.com/datagrip/) which lets you connect and manage
any RDBMS from a single Desktop App, including many of the most popular NoSQL data stores.

## Connect to all Database connections

In **Database Explorer**, click on the `+` New Icon to add a new Data Source to **Microsoft SQL Server**, **MySql**
and **PostgreSQL** using the passwords used to run the Docker commands (e.g.`p@55wOrd`) and the default user names
for each RDBMS:

- SQL Server: `sa`
- MySQL: `root`
- PostgreSQL: `postgres`

After connecting to all databases you should end up with active connections to all empty databases:

[![](https://servicestack.net/img/posts/postgres-mysql-sqlserver-on-apple-silicon/datagrip-databases.png)](https://www.jetbrains.com/datagrip/)

Which you can open a **New > Query Console** or `⇧⌘L` to start executing generic queries against like `SELECT @@VERSION`
in SQL Server to display the version of SQL Server that's running:

[![](https://servicestack.net/img/posts/postgres-mysql-sqlserver-on-apple-silicon/datagrip-mssql-version.png)](https://www.jetbrains.com/datagrip/)

## Creating new Databases with DataGrip

To do anything interesting you'll need databases, which you can create with `New > Database` for SQL Server and
PostgreSQL or `New > Schema` in MySQL:

[![](https://servicestack.net/img/posts/postgres-mysql-sqlserver-on-apple-silicon/datagrip-test.png)](https://www.jetbrains.com/datagrip/)


# Multiple App Databases
Source: https://docs.servicestack.net/ormlite/multi-database-app

ServiceStack Apps have great support for multiple App Databases, for all it's [supported RDBMS](/ormlite/installation)
starting with the built-in [Database Admin UI](https://docs.servicestack.net/admin-ui-database) which lets you
browse and query an App's configured databases:

<div class="flex justify-center">
    <lite-youtube class="w-full mx-4 my-4" width="560" height="315" videoid="NZkeyuc_prg" style="background-image: url('https://img.youtube.com/vi/NZkeyuc_prg/maxresdefault.jpg')"></lite-youtube>
</div>

You can easily try this out from a new database-enabled [blazor-vue](https://blazor-vue.web-templates.io) project template,
created with the `x` [dotnet tool](https://docs.servicestack.net/dotnet-tool):

:::sh
dotnet tool install --global x
:::

This will let you create any [ServiceStack Project Template](/start) with your preferred Project Name from the command-line, e.g:

:::sh
x new blazor-vue DatabaseTest
:::

Which creates a new .NET App that you can open with your preferred .NET IDE or text editor, e.g:

:::sh
code DatabaseTest/DatabaseTest
:::

By default the App is configured to use a local SQLite database, we can extend it to 
[connect to different RDBMS's](/ormlite/install-postgres-mysql-sqlserver)
by adding the necessary **RDBMS** and `AdminDatabaseFeature` NuGet packages in `DatabaseTest.csproj`:

```xml
<PackageReference Include="ServiceStack.OrmLite.MySql" Version="8.*" />
<PackageReference Include="ServiceStack.OrmLite.PostgreSQL" Version="8.*" />
<PackageReference Include="ServiceStack.OrmLite.SqlServer.Data" Version="8.*" />
<PackageReference Include="ServiceStack.Server" Version="8.*" />
```

::: info TIP
New dependencies can be installed with VS Code's **Restore** popup or by explicitly running `dotnet restore`
:::

We can then register named connections for each of our databases by replacing the existing `Configure.Db.cs` with:

```csharp
public class ConfigureDb : IHostingStartup
{
    public void Configure(IWebHostBuilder builder) => builder
        .ConfigureServices((context,services) => {
            var dbFactory = new OrmLiteConnectionFactory(
                context.Configuration.GetConnectionString("DefaultConnection") ?? "App_Data/db.sqlite",
                SqliteDialect.Provider);

            dbFactory.RegisterConnection("postgres", 
                "Server=localhost;User Id=postgres;Password=p@55wOrd;Database=test;Pooling=true;MinPoolSize=0;MaxPoolSize=200",
                PostgreSqlDialect.Provider);

            dbFactory.RegisterConnection("mysql", 
                "Server=localhost;User Id=root;Password=p@55wOrd;Database=test;Pooling=true;MinPoolSize=0;MaxPoolSize=200",
                MySqlDialect.Provider);

            dbFactory.RegisterConnection("mssql", 
                "Server=localhost;User Id=sa;Password=p@55wOrd;Database=test;MultipleActiveResultSets=True;Encrypt=False;",
                SqlServer2012Dialect.Provider);

            services.AddSingleton<IDbConnectionFactory>(dbFactory);
        })
        .ConfigureAppHost(appHost => {
            // Enable built-in Database Admin UI at /admin-ui/database
            appHost.Plugins.Add(new AdminDatabaseFeature());
        });
}
```

This will now let us access the [registered databases](https://docs.servicestack.net/ormlite/getting-started#multiple-database-connections)
in our APIs, but first lets populate the databases with some data.

When a new project is created it populates its default configured SQLite database with some test data, we can do the same
for the other registered database by duplicating the App's initial [DB migration](https://docs.servicestack.net/ormlite/db-migrations)
to a new DB `Migration1001.cs` with:

:::sh
sed "s/1000/1001/" ./Migrations/Migration1000.cs > ./Migrations/Migration1001.cs
:::

Then annotating it with a `[NamedConnection]` attribute for each of your registered database, e.g:

```csharp
[NamedConnection("mssql")]
[NamedConnection("mysql")]
[NamedConnection("postgres")]
public class Migration1001 : MigrationBase
{
    //...
}
```

That can then be executed with:

:::sh
npm run migrate
:::

Where it will execute all new DB Migrations, in this case apply the same Migration to each configured database.

Now that our App's databases are all populated and ready to go, we can run it with:

:::sh
npm run dev
:::

Then view the built-in Admin Database UI at:

:::sh
https://localhost:5001/admin-ui/database
:::

and signing in with the Admin user created in `Configure.AuthRepository.cs`:

- `admin@email.com`
- `p@55wOrd`

Where it displays all the App's configured database tables on its home page:

![](https://servicestack.net/img/posts/postgres-mysql-sqlserver-on-apple-silicon/admin-db-home.png)

Whose contents can be viewed by drilling down and clicking on each table:

![](https://servicestack.net/img/posts/postgres-mysql-sqlserver-on-apple-silicon/admin-db-mssql-bookings.png)

Which displays its rows using the [AutoQuery Grid Vue Component](https://docs.servicestack.net/vue/autoquerygrid) that
can be sorted and filtered as needed:

![](https://servicestack.net/img/posts/postgres-mysql-sqlserver-on-apple-silicon/admin-db-postgres-coupons.png)

## Named database connections

Named connections can be opened by its name from the registered `IDbConnectionFactory`:

```csharp
using var db = dbFactory.Open("postgres");
```

Inside a Service this can be resolved using `OpenDbConnection`:

```csharp
public class MyServices : Service
{
    public object Any(GetPostgresBookings request)
    {
        using var db = OpenDbConnection("postgres");
        return db.Select<Booking>();
    } 
}
```

The `[NamedConnection]` attribute can be used to configure Services `base.Db` connection with the named connection RDBMS, e.g:

```csharp
[NamedConnection("mysql")]
public class QueryMySqlBookings {}

public class BookingServices : Service
{
    public object Any(QueryMySqlBookings request) => Db.Select<Reports>();
}
```

Or if using [AutoQuery](/autoquery/) it can be used to associate Data Models with the named connection:

```csharp
[NamedConnection("mssql")]
public class QuerySqlServerBookings : QueryDb<Booking> {}
```

Otherwise for other Services the `[ConnectionInfo]` attribute can be used to change the `base.Db` to use the registered
named connection for all APIs in a Service class, e.g:

```csharp
[ConnectionInfo(NamedConnection = "postgres")]
public class PostgresServices : Service
{
    public object Any(GetPostgresBookings request)
    {
        return db.Select<Booking>();
    }
}
```

## Vue .mjs project template features

Whilst you have the App running, check out its other high-productivity features:

### Create a multi-user Booking system with AutoQuery

The App's Bookings APIs are built using [AutoQuery CRUD](https://docs.servicestack.net/autoquery-crud), allowing for
rapid development of typed CRUD Services using only declarative POCO DTOs:

<div class="not-prose text-center">
    <a class="text-xl text-indigo-600" href="https://localhost:5001/bookings-auto">https://localhost:5001/bookings-auto</a>
</div>
<div class="flex justify-center">
    <lite-youtube class="w-full mx-4 my-4" width="560" height="315" videoid="rSFiikDjGos" style="background-image: url('https://img.youtube.com/vi/rSFiikDjGos/maxresdefault.jpg')"></lite-youtube>
</div>

In addition, all AutoQuery APIs benefit from the built-in [Locode's](https://docs.servicestack.net/locode/) Auto Management UI:

<div class="not-prose text-center">
    <a class="text-xl text-indigo-600" href="https://localhost:5001/locode">https://localhost:5001/locode</a>
</div>

[![](https://servicestack.net/img/posts/postgres-mysql-sqlserver-on-apple-silicon/db-test-locode.png)](https://docs.servicestack.net/locode/)

<div class="flex justify-center">
    <lite-youtube class="w-full mx-4 my-4" width="560" height="315" videoid="hkuO_DMFXmc" style="background-image: url('https://img.youtube.com/vi/hkuO_DMFXmc/maxresdefault.jpg')"></lite-youtube>
</div>

As well as end-to-end typed integrations with the most [popular programming languages](/service-reference) accessible
from the [code tab](https://docs.servicestack.net/api-explorer#code-tab) of the built-in
[API Explorer](https://docs.servicestack.net/api-explorer):

<div class="not-prose text-center">
    <a class="text-xl text-indigo-600" href="https://localhost:5001/ui/QueryBookings?tab=code">https://localhost:5001/ui/QueryBookings?tab=code</a>
</div>

[![](https://servicestack.net/img/posts/postgres-mysql-sqlserver-on-apple-silicon/db-test-ui-code.png)](https://docs.servicestack.net/api-explorer)

<div class="flex justify-center">
    <lite-youtube class="w-full mx-4 my-4" width="560" height="315" videoid="lUDlTMq9DHU" style="background-image: url('https://img.youtube.com/vi/lUDlTMq9DHU/maxresdefault.jpg')"></lite-youtube>
</div>

I hope this has been an informative post and highlighted some cool products and features, any questions or feedback
is welcome by commenting below.


# Scalable SQLite
Source: https://docs.servicestack.net/ormlite/scalable-sqlite

Ever since adding [support for Litestream](/ormlite/litestream) in
our project's templates [GitHub Action Deployments](https://servicestack.net/posts/kubernetes_not_required)
we've been using SQLite as the backend for our new .NET Apps as it's the 
[most cost-effective option](/ormlite/litestream#savings-at-scale)
that frees us from needing to use a cloud managed database which lets us make use of Hetzner's much cheaper
[US Cloud VMs](https://www.hetzner.com/cloud/).

We're also seeing increased usage of SQLite Server Apps with [Bluesky Social](https://github.com/bluesky-social/atproto/pull/1705)
having moved to SQLite and all of 37 Signals new [Once](https://once.com) Web Apps 
[using SQLite](https://world.hey.com/dhh/multi-tenancy-is-what-s-hard-about-scaling-web-services-dd1e0e81)
and Cloud Providers building distributed databases on top of SQLite like 
[Cloudflare D1](https://blog.cloudflare.com/introducing-d1/) and Fly.io's 
multi-region distributed [LiteFS](https://fly.io/docs/litefs/) solution.

SQLite is a highly-performant DB that can handle a large number of concurrent read operations and
[35% Faster](https://www.sqlite.org/fasterthanfs.html) filesystem performance for write operations with next 
to no latency that's often faster than other RDBMS's courtesy of its proximity to the running application which gives it unique advantages over traditional client/server RDBMS's where it's not susceptible to the 
[N+1 Queries problem](https://www.sqlite.org/np1queryprob.html) and is also able to execute your
custom C# Logic inside SQL Queries using [Application SQL Functions](https://www.sqlite.org/appfunc.html).

With [litestream.io](https://litestream.io) taking care of real-time replication to managed storage
we just need to workaround SQLite's single concurrent writer to unlock the value, performance and 
unique features of SQLite in our Apps which we cover in this release with integrated support for
Database Locks and Sync Commands.

## Single Concurrent Writer

The primary limitation of SQLite is that it only supports a single concurrent writer, which means if you 
have multiple requests writing to the same database at the same time, they will need to coordinate access. 

As long as we can overcome this limitation SQLite can be an excellent choice to power many Web Apps. In the
previous ServiceStack v8.3 release we [worked around this limitation](/commands#use-case-sqlite-writes)
by using [MQ Command DTOs](/commands#mq-command-dtos) to route all DB
Writes to be executed by a single Background MQ Thread.

This works great for [messaging-based architectures](/commands#messaging)
where you can queue commands to be processed serially, but the overhead of using commands for all 
DB writes can be cumbersome when needing to perform sporadic writes within complex logic.

## Multiple SQLite Databases

Firstly a great way to reduce contention is to use separate SQLite databases for different
subsystems of your Application that way load is distributed across multiple DBs
and writes across each SQLite database can be executed concurrently.

This is especially important for write heavy operations like
[SQLite Request Logging](https://servicestack.net/posts/sqlite-request-logs) or if your App stores every interaction 
of your App for A/B testing, storing them in separate `analytics.db` databases will remove 
any contention from your primary database.

The other techniques below demonstrates concurrent safe techniques for accessing an SQLite DB: 

### Always use Synchronous APIs for SQLite

Generally it's recommended to use non-blocking Async APIs for any I/O Operations however as
SQLite doesn't make Network I/O requests and its native implementation is blocking, its Async DB
APIs are just pseudo-async wrappers around SQLite's blocking APIs which just adds unnecessary
overhead. For this reason we recommend **always** using synchronous APIs for SQLite, especially 
as it's not possible to await inside a lock:

```csharp
lock (Locks.AppDb)
{
    //Can't await inside a lock
    //await Db.UpdateAsync(row); 
    Db.Update(row);
}
```

It's also safe to assume SQLite will always block since all
[Asynchronous I/O efforts](https://www.sqlite.org/asyncvfs.html) were abandoned in favor
of [WAL mode](https://www.sqlite.org/wal.html) which mitigates the cost of blocking **fsync()**.

## Database Locks

The new `Locks` class maintains an object lock for each registered database connection that can be 
used to synchronize **write access** for different SQLite databases, e.g:

```js
var row = db.SingleById<Table>(request.Id);
row.PopulateWithNonDefaultValues(request);
lock (Locks.AppDb)
{
    Db.Update(row);
}
```

`Locks.AppDb` can be used synchronize db writes for the App's primary database, e.g. `App_Data/app.db`.

Whilst `Locks.GetDbLock(namedConnection)` can be used to get the DB Write Lock for any other 
[registered SQLite Database](/ormlite/multi-database-app) by using
the same named connection the SQLite Database Connection was registered against, e.g:

```csharp
var dbFactory = new OrmLiteConnectionFactory(connStr, SqliteDialect.Provider);
dbFactory.RegisterConnection(Databases.Search, 
    $"DataSource=App_Data/search.db;Cache=Shared", SqliteDialect.Provider);
dbFactory.RegisterConnection(Databases.Analytics, 
    $"DataSource=App_Data/analytics.db;Cache=Shared", SqliteDialect.Provider);

//...
using var dbSearch = dbFactory.Open(Database.Search);
lock (Locks.GetDbLock(Database.Search))
{
    dbSearch.Insert(row);
}

using var dbAnalytics = dbFactory.Open(Database.Analytics);
lock (Locks.GetDbLock(Database.Analytics))
{
    dbAnalytics.Insert(row);
}
```

## Queuing DB Writes with SyncCommand

`Locks` are a great option for synchronizing DB Writes that need to be executed within
complex logic blocks, however locks can cause contention in highly concurrent Apps.
One way to remove contention is to serially execute DB Writes instead which we can
do by executing DB Writes within `SyncCommand*` commands and using a named `[Worker(Workers.AppDb)]`
attribute for Writes to the primary database, e.g: 

```csharp
[Worker(Workers.AppDb)]
public class DeleteCreativeCommand(IDbConnection db) 
    : SyncCommand<DeleteCreative>
{
    protected override void Run(DeleteCreative request)
    {
        var artifactIds = request.ArtifactIds;
        db.Delete<AlbumArtifact>(x => artifactIds.Contains(x.ArtifactId));
        db.Delete<ArtifactReport>(x => artifactIds.Contains(x.ArtifactId));
        db.Delete<ArtifactLike>(x => artifactIds.Contains(x.ArtifactId));
        db.Delete<Artifact>(x => x.CreativeId == request.Id);
        db.Delete<CreativeArtist>(x => x.CreativeId == request.Id);
        db.Delete<CreativeModifier>(x => x.CreativeId == request.Id);
        db.Delete<Creative>(x => x.Id == request.Id);
    }
}
```

Other databases should use its named connection for its named worker, e.g: 

```csharp
[Worker(Databases.Search)]
public class DeleteSearchCommand(IDbConnectionFactory dbFactory) 
    : SyncCommand<DeleteSearch>
{
    protected override void Run(DeleteSearch request)
    {
        using var db = dbFactory.Open(Databases.Search);
        db.DeleteById<ArtifactFts>(request.Id);
        //...
    }
}
```

Example of a DB Write command with result:

```csharp
[Worker(Databases.Albums)]
public class CreateAlbumCommand(IDbConnectionFactory dbFactory) 
    : SyncCommandWithResult<CreateAlbum,Album>
{
    protected override Album Run(CreateAlbum request)
    {
        using var db = dbFactory.Open(Databases.Albums);
        var album = request.ConvertTo<Album>();
        album.Id = db.Insert(album, selectIdentity:true);
        foreach (var artifact in request.Artifacts)
        {
            artifact.AlbumId = album.Id;
            db.Insert(artifact);
        }
        return album;
    }
}
```

Where it will be executed within its Database Lock. 

## Executing Commands

Now everytime commands are executed they'll be added to a ConcurrentQueue of the specified worker. Commands delegated to different named workers execute concurrently, whilst commands with the same worker are executed serially.


When using any `SyncCommand*` base class, its execution still uses database locks
but any contention is alleviated as they're executed serially by a single worker thread.


```csharp
public class MyServices(IBackgroundJobs jobs) : Service
{
    // Returns immediately with a reference to the Background Job
    public object Any(DeleteCreative request)
    {
        // Queues a durable job to execute the command with the AppDb Worker
        var jobRef = jobs.EnqueueCommand<DeleteCreativeCommand>(request);

        // Executes Command with Databases.Search worker
        jobs.EnqueueCommand<DeleteSearchCommand>(new DeleteSearch {
            Id = request.ArtifactId
        });

        return jobRef;
    }

    // Returns after the command is executed with its result (if any)
    public async Task Any(CreateAlbum request)
    {
        // Executes a transient (i.e. non-durable) job with the named worker
        var album = await jobs.RunCommandAsync<CreateAlbumCommand>(request);
        return album;
    }
}
```

### AutoQuery Crud Database Write Locks

To avoid SQLite concurrency write exceptions all DB Writes should be executed within
its database lock or a named worker. Including the auto-generated [AutoQuery Crud](/autoquery/crud)
APIs which will implicitly use Database Locks if the **primary database is SQLite**.

AutoQuery CRUD can also be explicitly configured to always be executed within Database Locks with:

```csharp
services.AddPlugin(new AutoQueryFeature {
    UseDatabaseWriteLocks = true
});
```

## SQLite Web Apps

That's about it, by using any of the above techniques to guard against concurrent writes
you can take advantage of the [simplicity, value and performance benefits](/ormlite/litestream#the-right-time-for-server-side-sqlite)
of SQLite in your Apps and utilize a solution like [litestream.io](https://litestream.io)
for real-time replication of your SQLite databases to highly reliable managed storage.

SQLite's [Checklist For Choosing The Right Database Engine](https://www.sqlite.org/whentouse.html#checklist_for_choosing_the_right_database_engine)
covers the few situations when a traditional Client/Server RDBMS will be more appropriate.

The primary use-case would be when your App needs to be distributed across multiple App Servers 
as using SQLite essentially forces you into scaling up, which gets more appealing every year 
with hardware getting cheaper and faster and cheap hosting providers like [hetzner.com](https://www.hetzner.com)
where you can get bare metal 48 Core/96 vCore EPYC Servers with fast NVMe SSDs for **€236** per month - 
a fraction of the cost of comparable performance with any cloud managed solution

[![](/img/pages/sqlite/hetzner-epyc-48.webp)](https://www.hetzner.com/dedicated-rootserver/)

Which is a fraction of what it would cost for comparable performance using cloud managed databases:

[![](/img/pages/sqlite/azure-sql-database.webp)](https://azure.microsoft.com/en-us/pricing/details/azure-sql-database/single/)

In the rare cases where you need to scale beyond a single server you'll initially be able to 
scale out your different App databases onto different servers.

Beyond that, if your App permits you may be able to adopt a multi-tenant architecture like 
[Bluesky Social](https://bsky.social/about) with each tenant having their own SQLite database 
to effectively enable infinite scaling.

For further info on using high performance SQLite in production web apps check out
[@aarondfrancis](https://x.com/aarondfrancis) comprehensive website and course at 
[highperformancesqlite.com](https://highperformancesqlite.com) - 
which contains a lot of great content accessible for free.

## Example SQLite Apps

Our confidence in SQLite being the best choice for many web applications has led us to adopt
it to power our latest web applications which are all 
[deployed to a shared Hetzner VM](https://servicestack.net/posts/kubernetes_not_required) 
whose [inexpensive hosting costs](https://servicestack.net/posts/jamstacks_hosting) allows us to host 
and make them **available for free!**

All projects are open-source and employ the different techniques detailed above that should serve
as a great resource of how they're used in real-world Web Applications:

### Blazor Diffusion

Generate images for free using custom [Civit AI](https://civitai.com) and [FLUX-schnell](https://huggingface.co/black-forest-labs/FLUX.1-schnell)
models:

[![](/img/pages/sqlite/blazordiffusion.webp)](https://blazordiffusion.com)

- Website: [blazordiffusion.com](https://blazordiffusion.com)
- GitHub: [github.com/NetCoreApps/BlazorDiffusionVue](https://github.com/NetCoreApps/BlazorDiffusionVue/)

### pvq.app

An OSS alternative to StackOverflow which uses the best proprietary and OSS Large Language Models 
to answer your technical questions. [pvq.app](https://pvq.app) is populated with over **1M+ answers** for the highest
rated StackOverflow questions - checkout [pvq.app/leaderboard](https://pvq.app/leaderboard) 
to find the best performing LLM models (results are surprising!)

[![](/img/pages/sqlite/pvq.webp)](https://pvq.app)

- Website: [pvq.app](https://pvq.app)
- GitHub: [github.com/ServiceStack/pvq.app](https://github.com/ServiceStack/pvq.app)

### AI Server

The independent Microservice used to provide all AI Features used by the above applications. 
It's already been used to execute millions of LLM and Comfy UI Requests to generate Open AI Chat Answers
and Generated Images used to populate the
[blazordiffusion.com](https://blazordiffusion.com) and [pvq.app](https://pvq.app) websites. 

It was the project used to develop and test [Background Jobs](/background-jobs) in action 
where it serves as a private gateway to process all LLM, AI and image transformations requests 
that any of our Apps need where it dynamically delegates requests across multiple Ollama, 
Open AI Chat, LLM Gateway, Comfy UI, Whisper and ffmpeg providers. 

[![](/img/pages/sqlite/ai-server.webp)](https://openai.servicestack.net)
[![](/img/pages/sqlite/ai-server-chat.webp)](https://openai.servicestack.net)

- Website: [openai.servicestack.net](https://openai.servicestack.net)
- GitHub: [github.com/ServiceStack/ai-server](https://github.com/ServiceStack/ai-server)

In addition to maintaining a history of AI Requests, it also provides file storage
for its CDN-hostable AI generated assets and on-the-fly, cacheable image transformations.

### Private AI Gateway

We're developing AI Server as a **Free OSS Product** that runs as a single Docker Container
Microservice that Admins can use its built-in UIs to add multiple Ollama instances, 
Open AI Gateways to execute LLM requests and Client Docker agents installed with Comfy UI, 
ffmpeg and Whisper to handle all other non-LLM Requests. 

#### Multiple Ollama, Open AI Gateway and Comfy UI Agents

The AI Server Docker container itself wont require any infrastructure dependencies or 
specific hardware requirements, however any Ollama endpoints or Docker Comfy UI Agents added 
will need to run on GPU-equipped servers.

#### Native end-to-end Typed Integrations to most popular languages

ServiceStack's [Add ServiceStack Reference](/add-servicestack-reference)
feature is used to provide native typed integrations to C#, TypeScript, JavaScript, Python, PHP, Swift, Java, 
Kotlin, Dart, F# and VB.NET projects which organizations can drop into their heterogeneous
environments to manage their private AI Services used across their different Apps.

#### Protected Access with API Keys

AI Server utilizes [Simple Auth with API Keys](/auth/admin-apikeys)
letting Admins create and distribute API Keys to only allow authorized clients to access their 
AI Server's APIs, which can be optionally further restricted to only
[allow access to specific APIs](/auth/apikeys#creating-user-api-keys).

## Active Development

AI Server is still actively developed whilst we finish adding support for different 
AI Requests in its first V1 release, including:

#### Large Language Models
- Open AI Chat
  - Support for Ollama endpoints 
  - Support for Open Router, Open AI, Mistral AI, Google and Groq API Gateways

#### Comfy UI Agent / Replicate / DALL-E 3
- Text to Image

#### Comfy UI Agent
- Image to Image
  - Image Upscaling
  - Image with Mask
- Image to Text
- Text to Audio
- Text to Speech
- Speech to Text

#### ffmpeg 
- image/video/audio format conversions
- image/video scaling
- image/video cropping
- image/video watermarking
- video trimming

#### Managed File Storage
- Blob Storage - isolated and restricted by API Key

### V1 Release

We'll announce **V1** after we've finished implementing the above AI Features with any
necessary Admin UIs, feature documentation / API Docs and have streamlined the 
Server Install / Client Setup experience. After V1 we'll be happy to start accepting 
any external contributions for other AI Features users would like AI Server to support.

To get notified when AI Server is ready for public consumption, 
follow [@ServiceStack](https://twitter.com/servicestack)
or [join our ~Quarterly Newsletter](https://servicestack.net/posts/scalable-sqlite#top).

In the meantime you can reach us at [ServiceStack/Discuss](https://github.com/ServiceStack/Discuss/discussions)
with any AI Server questions.


# OrmLite SELECT APIs
Source: https://docs.servicestack.net/ormlite/apis/select

OrmLite has extensive support for Querying exposing an intuitive 1:1 Typed API that maps cleanly and has a high affinity with SQL that's not only natural to write and easy to predict what SQL it generates.

OrmLite provides terse and intuitive typed APIs for database querying from simple lambda expressions to more complex LINQ-Like Typed SQL Expressions which 
you can use to construct more complex queries. To give you a flavour here are some examples:


## Querying with SELECT

```csharp
int agesAgo = DateTime.Today.AddYears(-20).Year;
db.Select<Author>(x => x.Birthday >= new DateTime(agesAgo, 1, 1) 
                    && x.Birthday <= new DateTime(agesAgo, 12, 31));
```

```csharp
db.Select<Author>(x => Sql.In(x.City, "London", "Madrid", "Berlin"));
```

```csharp
db.Select<Author>(x => x.Earnings <= 50);
```

```csharp
db.Select<Author>(x => x.Name.StartsWith("A"));
```

```csharp
db.Select<Author>(x => x.Name.EndsWith("garzon"));
```

```csharp
db.Select<Author>(x => x.Name.Contains("Benedict"));
```

```csharp
db.Select<Author>(x => x.Rate == 10 && x.City == "Mexico");
```

```csharp
db.Select<Author>(x => x.Rate.ToString() == "10"); //impicit string casting
```

```csharp
db.Select<Author>(x => "Rate " + x.Rate == "Rate 10"); //server string concatenation
```

## Convenient data access patterns

OrmLite also includes a number of convenient APIs providing DRY, typed data access for common queries:

The `SingleById<T>` uses the provided value to query against a primary key, expecting 1 result.

```csharp
Person person = db.SingleById<Person>(1);
```

Lambda expressions can be provided to `Single` as a way to return the first instance from the result set.

```csharp
Person person = db.Single<Person>(x => x.Age == 42);
```

## Using Typed SqlExpression

The `From<T>` can be used to create an `SqlExpression<T>` query to build on and use later. 

```csharp
var q = db.From<Person>()
          .Where(x => x.Age > 40)
          .Select(Sql.Count("*"));

int peopleOver40 = db.Scalar<int>(q);
```

Common aggregate methods can be used with type safety. For example:

```csharp
int peopleUnder50 = db.Count<Person>(x => x.Age < 50);
```

```csharp
bool has42YearOlds = db.Exists<Person>(new { Age = 42 });
```

```csharp
int maxAgeUnder50 = db.Scalar<Person, int>(x => Sql.Max(x.Age), x => x.Age < 50);
```

Returning a single column from a query can be used with `.Select` of a property and `.Column`.

```csharp
var q = db.From<Person>()
    .Where(x => x.Age == 27)
    .Select(x => x.LastName);
    
List<string> results = db.Column<string>(q);
```

```csharp
var q = db.From<Person>()
          .Where(x => x.Age < 50)
          .Select(x => x.Age);

HashSet<int> results = db.ColumnDistinct<int>(q);
```

Multiple columns can do the same. For example using the same `.Select` on a `SqlExpression<T>` with an anonymous type, returning a Dictionary of matching types. 

```csharp
var q = db.From<Person>()
          .Where(x => x.Age < 50)
          .Select(x => new { x.Id, x.LastName });

Dictionary<int,string> results = db.Dictionary<int, string>(q);
```

The `Lookup<T,K>` method returns a `Dictionary<K,List<V>>` grouping made from the first two columns using n SQL Expression.

```csharp
var q = db.From<Person>()
          .Where(x => x.Age < 50)
          .Select(x => new { x.Age, x.LastName });

Dictionary<int, List<string>> results = db.Lookup<int, string>(q);
```

The `db.KeyValuePair<K,V>` API is similar to `db.Dictionary<K,V>` where it uses the **first 2 columns** for its Key/Value Pairs to
create a Dictionary but is more appropriate when the results can contain duplicate Keys or when ordering needs to be preserved:

```csharp
var q = db.From<StatsLog>()
    .GroupBy(x => x.Name)
    .Select(x => new { x.Name, Count = Sql.Count("*") })
    .OrderByDescending("Count");

var results = db.KeyValuePairs<string, int>(q);
```

## Lambda Expression examples

For simple queries you can use terse lambda Expressions to specify the filter conditions you want:

```csharp
var nirvana = db.Select<Artist>(x => x.Name == "Nirvana").First();

var nirvanaTracks = db.Select<Track>(x => x.ArtistId == nirvana.Id);

var nirvanaTrackIds = nirvanaTracks.Map(x => x.Id); // Convenience Extension method

//Using SQL IN by .NET Collection `Contains()` or explicit `Sql.In()`
var nirvanaTracksByIn = db.Select<Track>(x => nirvanaTrackIds.Contains(x.Id));
var nirvanaTracksByInAlt = db.Select<Track>(x => Sql.In(x.Id, nirvanaTrackIds));

var pearlJam = db.Select<Artist>(x => x.Name.StartsWith("Pearl")).First();

var faithNoMore = db.Select<Artist>(x => x.Name.EndsWith("More")).First();

var smellsLikeTeenSpirit = db.Select<Track>(x => x.Name.Contains("Teen")).First();

var latestTracks = db.Select<Track>(x => x.Year >= 1997);

var heartShapedBox = db.Select<Track>(x => x.ArtistId == nirvana.Id 
	&& x.Year == 1993 && x.Album == "In Utero").First();
```

## SqlExpression examples

For more advanced queries you can leverage the SqlExpression builder which provides a Typed API that closely follows SQL except it's created by calling 
`db.From<T>` with the table you want to query and optionally ends with a Custom .Select() if you want to customize the resultset that's returned (similar to LINQ). Some examples of SqlExpression in action:

```csharp
var q = db.From<Track>()
    .OrderByDescending(x => x.Year)
    .Take(3);
var latest3Tracks = db.Select(q);

var faithAndLiveTracks = db.Select(db.From<Track>()
    .Where(x => x.Album == "Angel Dust" && x.Year == 1992)
    .Or(x => x.Album == "Throwing Copper" && x.Year == 1994));

// More advanced SQL Expression
var customYears = new[] { 1993, 1994, 1997 };
q = db.From<Track>()
    .Where(x => customYears.Contains(x.Year))
    .And(x => x.Name.Contains("A"))
    .GroupBy(x => x.Year)
    .OrderByDescending("Total")
    .ThenBy(x => x.Year)
    .Take(2)
    .Select(x => new { x.Year, Total = Sql.Count("*") });

var top2CountOfAByYear = db.Dictionary<string, int>(q);
```

## Sql.In

### Nested Typed Sub Select Sql Expressions 

The `Sql.In()` API supports nesting and combining of multiple Typed SQL Expressions together
in a single SQL Query, e.g:

```csharp
var usaCustomerIds = db.From<Customer>(c => c.Country == "USA").Select(c => c.Id);
var usaCustomerOrders = db.Select(db.From<Order>()
    .Where(x => Sql.In(x.CustomerId, usaCustomerIds)));
``` 

### SQL IN with collections

By using `Sql.In` from within a `SqlExpression<T>`, multiple values can be checked for a match in your query.

```csharp
db.Select<Author>(x => Sql.In(x.City, "London", "Madrid", "Berlin"));

var cities = new[] { "London", "Madrid", "Berlin" };
db.Select<Author>(x => Sql.In(x.City, cities));
```

## SqlExpression with JOIN examples

Just like SQL, SqlExpression supports multiple JOIN's that can leverage OrmLite's Reference Conventions for Simple, Terse and Intuitive Table JOIN's:

```csharp
var q = db.From<Track>()
    .Join<Artist>() //Uses implicit reference convention
    .Where<Artist>(x => x.Name == "Nirvana");
var implicitJoin = db.Select(q);

var explicitJoin = db.Select(db.From<Track>()
	.Join<Artist>((track,artist) => track.ArtistId == artist.Id)
    .Where<Artist>(x => x.Name == "Nirvana"));

var nirvanaWithRefs = db.LoadSingleById<Artist>(explicitJoin[0].ArtistId);

var oldestTracks = db.Select(db.From<Track>()
    .Where(x => Sql.In(x.Year, db.From<Track>().Select(y => Sql.Min(y.Year)))));

var oldestTrackIds = oldestTracks.Map(x => x.Id);
var earliestArtistsWithRefs = db.LoadSelect(db.From<Artist>()
    .Where(a => oldestTracks.Map(t => t.ArtistId).Contains(a.Id)));

var oldestTracksAndArtistNames = db.Dictionary<string, string>(db.From<Track>()
	.Join<Artist>()
	.Where(x => oldestTrackIds.Contains(x.Id))
    .Select<Track,Artist>((t,a) => new { t.Name, Artist = a.Name }));

var oldestTrackAndArtists = db.SelectMulti<Track,Artist>(db.From<Track>()
      .Join<Artist>()
      .Where(x => oldestTrackIds.Contains(x.Id)));
```

## Single, Scalar, Count, Exists examples

In addition to `db.Select()` OrmLite provides a number of other convenience API's to return results for your preferred use-case:

```csharp
var nevermind = db.Single<Track>(x => x.Album == "Nevermind");

var nirvana = db.SingleById<Artist>(nevermind.ArtistId);

var latestYear = db.Scalar<int>(db.From<Track>()
    .Select(x => Sql.Max(x.Year)));

var differentArtistsCount = db.Scalar<int>(db.From<Track>()
    .Select(x => Sql.CountDistinct(x.ArtistId)));

int tracksAfter93 = db.Scalar<Track,int>(x=> Sql.Count("*"), x=> x.Year > 1993);

var nirvanaTracksCount = db.Count<Track>(x => x.ArtistId == nirvana.Id);

$"\nHave Tracks in 1990: {db.Exists<Track>(x => x.Year == 1990)}".Print();
$"\nHave Tracks in 1991: {db.Exists<Track>(x => x.Year == 1991)}".Print();

var inUtero = db.Where<Track>(new { ArtistId = nirvana.Id, Year = 1993 });

var lazySequence = db.SelectLazy(db.From<Track>().OrderBy(x => x.Year));
var lazyLinq = lazySequence.Take(3).Select(x => $"{x.Year}: {x.Album}");
db.Insert(new Track {
    Name = "About a Girl", ArtistId = nirvana.Id, Album="Bleach", Year=1989 }); 
lazyLinq.Each(x => x.Print());
```

## Column, ColumnDistinct, Dictionary and Lookup Examples

In addition there are convenience API's to return results in your preferred .NET Collection:

```csharp
List<int> trackIds = db.Column<int>(db.From<Track>());

HashSet<int> years = db.ColumnDistinct<int>(db.From<Track>().Select(x => x.Year));

Dictionary<string, int> trackAndYears = db.Dictionary<string, int>(
    db.From<Track>().Select(x => new { x.Name, x.Year }));

var tracksCountByYear = db.Dictionary<int, int>(db.From<Track>()
	.Join<Artist>()
    .GroupBy(x => x.Year)     
    .OrderBy(x => x.Year)
    .Select(x => new { x.Year, Count = Sql.Count("*") }));

Dictionary<int, List<string>> tracksByYear = db.Lookup<int, string>(
	db.From<Track>().Select(x => new { x.Year, x.Name }));
```

## Custom SQL Examples

If you need more flexibility or RDBMS-specific functionality that's not possible using Typed APIs you can drop down to raw SQL using our 
[Custom SQL APIs](/ormlite/custom-sql).

## Dynamic Result Set Examples

Whilst OrmLite is predominantly a typed code-first ORM it also offers 
[several options for reading unstructured results](/ormlite/dynamic-result-sets)
when the Schema is unknown or unavailable.


# OrmLite INSERT APIs
Source: https://docs.servicestack.net/ormlite/apis/insert

## Insert Examples

In most cases INSERT's in OrmLite is as straight forward as passing the POCO you want inserted:

```csharp
public record Artist(int Id, string Name);

//INSERT one row
db.Insert(new Artist { Id = 1, Name = "Faith No More" });

db.Insert( //INSERT multiple rows (params)
    new Artist { Id = 2, Name = "Live" },
    new Artist { Id = 3, Name = "Nirvana" });

//INSERT multiple rows (IEnumerable<T>)
db.InsertAll(new[] { 
    new Artist { Id = 4, Name = "Pearl Jam" },
    new Artist { Id = 5, Name = "Tool" } });

var artists = db.Select<Artist>();
$"All Artists: {artists.Dump()}".Print();
```

To see the behaviour of the different APIs, the examples below uses the following data models:

```csharp
public class Person
{
    public int Id { get; set; }
    public string FirstName { get; set; }
    public string LastName { get; set; }
    public int? Age { get; set; }
}

public class Artist 
{
    public int Id { get; set; }
    public string Name { get; set; }
    [Reference] public List<Track> Tracks { get; set; }
    public override string ToString() => Name;
}

public class Track 
{
    [AutoIncrement] 
    public int Id { get; set; }
    public string Name { get; set; }
    public int ArtistId { get; set; }
    public string Album { get; set; }
    public int Year { get; set; }
    public override string ToString() => Name;
}
```

## Full Inserts

An `Insert` will insert every field by default:

```csharp
db.Insert(new Person { Id = 1, FirstName = "Jimi", LastName = "Hendrix", Age = 27 });
```

## Partial Inserts

You can use `InsertOnly` for the cases you don't want to insert every field

```csharp
db.InsertOnly(() => new Person { FirstName = "Amy" });
```

Alternative API using an SqlExpression

```csharp
var q = db.From<Person>()
    .Insert(p => new { p.FirstName });

db.InsertOnly(new Person { FirstName = "Amy" }, onlyFields: q)
```

## Insert by Dictionary

```csharp
var row = new Person { FirstName = "John", LastName = "Smith" };
Dictionary<string,object> obj = row.ToObjectDictionary();
obj[nameof(Person.LastName)] = null;

row.Id = (int) db.Insert<Person>(obj, selectIdentity:true);
```

## Insert records with AutoIncrement Ids

OrmLite provides a couple of different ways to handle Inserting records with AutoIncrementing Ids:

```csharp
var autoId = db.Insert(new Track { 
    Name = "Everything's Ruined", Album = "Angel Dust", Year = 1992 
}, selectIdentity:true);

var track = db.SingleById<Track>(autoId);

var savedTrack = new Track { Name = "Ashes to Ashes", Album = "Album of the Year", Year = 1997 };
db.Save(savedTrack); // Populates savedTrack.Id

$"\nSaved AutoIncrement Id: {savedTrack.Id}".Print();
$"\nSaved Track: {savedTrack.Dump()}".Print();
```

## Save API

OrmLite's Save() API offers high-level functionality over Insert() including auto populating AutoIncrementing Ids, transparently handling Insert or Updates and saving reference data:

```csharp
db.Save(new Artist { 
    Id = 1, Name = "Faith No More", 
    Tracks = new List<Track> { 
        new Track { Name = "Everythings Ruined", Album = "Angel Dust", Year = 1992 },
        new Track { Name = "Ashes to Ashes", Album = "Album of the Year", Year = 1997 },
    }
}, references:true);

var artist = db.SingleById<Artist>(1);
var tracks = db.Select<Track>();
var artistWithTracks = db.LoadSingleById<Artist>(1);

var track = new Track { Name = "The Gentle Art of Making Enemies", Album = "King for a Day", Year = 1995, ArtistId=1 };
db.Save(track); // Inserts new Track
$"\nInserted Track: {db.SingleById<Track>(track.Id).Dump()}".Print();

track.Name = "King for a Day... Fool for a Lifetime";
db.Save(track); // Updates existing Track
$"\nUpdated Track: {db.SingleById<Track>(track.Id).Dump()}".Print();
```

## InsertOnly

Use InsertOnly() for the rare cases when you don't want to insert an entire record. One instance when you would want to do this is to use the default value defined on the underlying CREATE TABLE RDBMS Schema:

```csharp
db.InsertOnly(() => new Track { Name = "State of Love and Trust", Album = "Singles" });

//Using explicit fields
db.InsertOnly(new Track { Name = "I Got ID", Album = "Merkin Ball" }, x => new { x.Name, x.Album });

var tracks = db.Select<Track>();
```


# OrmLite UPDATE APIs
Source: https://docs.servicestack.net/ormlite/apis/update

To see the behaviour of the different APIs, the examples below uses the following data models:

```csharp
public class Person
{
    public int Id { get; set; }
    public string FirstName { get; set; }
    public string LastName { get; set; }
    public int? Age { get; set; }
}

public class Track 
{
    [AutoIncrement] 
    public int Id { get; set; }
    public string Name { get; set; }
    public int ArtistId { get; set; }
    public string Album { get; set; }
    public int Year { get; set; }
    public override string ToString() => Name;
}
```

## Updates

Updating any model without any filters will update every field, except the **Id** which
is used to filter the update to this specific record:

```csharp
db.Update(new Person { Id = 1, FirstName = "Jimi", LastName = "Hendrix", Age = 27});
```

Example updating existing data model in-place:

```csharp
var alive = db.Single<Track>(x => x.Name == "Alive"); 
alive.Name = "Still Alive";
alive.Year = 2000;
db.Update(alive); // Updates all fields except `Id` which is used to filter
var updatedTrackById = db.SingleById<Track>(alive.Id);
```

If you supply your own where expression, it updates every field (inc. Id) but uses your filter instead:

```csharp
db.Update(new Person { Id = 1, FirstName = "JJ" }, p => p.LastName == "Hendrix");
```

One way to limit the fields which gets updated is to use an **Anonymous Type**:

```csharp
db.Update<Person>(new { FirstName = "JJ" }, p => p.LastName == "Hendrix");
```

Updates ALL fields matching specified filter:

```csharp
db.Update(new Track { Id = 20, Name = "Partially Alive...", ArtistId = alive.ArtistId }, 
	where: x => x.Name == "Still Alive...");
```

Or by using `UpdateNonDefaults` which only updates the non-default values in your model using the filter specified:

```csharp
db.UpdateNonDefaults(new Person { FirstName = "JJ" }, p => p.LastName == "Hendrix");
```

Update only fields in anonymous type:

```csharp
db.Update<Track>(new { Year = 2000 }, where: x => x.Id == 20);
```

Multi update example:

```csharp
var pearlJamTracks = db.Select<Track>(x => x.ArtistId == alive.ArtistId);
pearlJamTracks.Each(x => x.Album = "Rear View Mirror (Greatest Hits 1991–2003)");
db.Update(pearlJamTracks[0], pearlJamTracks[1]); //Update by params
```

## UpdateOnly

As updating a partial row is a common use-case in Db's, we've added a number of methods for just
this purpose, named **UpdateOnly**.

The lambda syntax lets you update only the fields listed in property initializers, e.g:

```csharp
db.UpdateOnly(() => new Person { FirstName = "JJ" });
```

The second argument lets you specify a filter for updates:

```csharp
db.UpdateOnly(() => new Person { FirstName = "JJ" }, where: p => p.LastName == "Hendrix");
```

Alternatively you can pass in a POCO directly, in which case the first expression in an `UpdateOnlyFields`
statement is used to specify which fields should be updated:

```csharp
db.UpdateOnlyFields(new Person { FirstName = "JJ" }, onlyFields: p => p.FirstName);

db.UpdateOnlyFields(new Person { FirstName = "JJ", Age = 12 }, 
    onlyFields: p => new { p.FirstName, p.Age });

db.UpdateOnlyFields(new Person { FirstName = "JJ", Age = 12 }, 
    onlyFields: p => new[] { "Name", "Age" });
```

When present, the second expression is used as the where filter:

```csharp
db.UpdateOnlyFields(new Person { FirstName = "JJ" }, 
    onlyFields: p => p.FirstName, 
    where: p => p.LastName == "Hendrix");
```
Instead of using the expression filters above you can choose to use an SqlExpression builder which provides more flexibility when you want to programmatically construct the update statement:

```csharp
var q = db.From<Person>()
    .Update(p => p.FirstName);

db.UpdateOnlyFields(new Person { FirstName = "JJ", LastName = "Hendo" }, onlyFields: q);
```

Using an Object Dictionary:

```csharp
var updateFields = new Dictionary<string,object> {
    [nameof(Person.FirstName)] = "JJ",
};

db.UpdateOnly<Person>(updateFields, p => p.LastName == "Hendrix");
```

Using a typed SQL Expression:

```csharp
var q = db.From<Person>()
    .Where(x => x.FirstName == "Jimi")
    .Update(p => p.FirstName);
          
db.UpdateOnlyFields(new Person { FirstName = "JJ" }, onlyFields: q);
```

## Updating existing values

The `UpdateAdd` API provides several Typed API's for updating existing values:

```csharp
//Increase everyone's Score by 3 points
db.UpdateAdd(() => new Person { Score = 3 }); 

//Remove 5 points from Jackson Score
db.UpdateAdd(() => new Person { Score = -5 }, where: x => x.LastName == "Jackson");

//Graduate everyone and increase everyone's Score by 2 points 
db.UpdateAdd(() => new Person { Points = 2, Graduated = true });

//Add 10 points to Michael's score
var q = db.From<Person>()
    .Where(x => x.FirstName == "Michael");
db.UpdateAdd(() => new Person { Points = 10 }, q);

//UpdateAdd on non-numeric fields are updated normally:
db.UpdateAdd(() => new Track { Year = -10, Album = "Lost a decade" }, x => x.Year == 1997); 

//Add 10 years to all 1991 Tracks
var q = db.From<Track>()
    .Where(x => x.Year == 1991);
db.UpdateAdd(() => new Track { Year = 10 }, q);
```

::: info
Any non-numeric values in an `UpdateAdd` statement (e.g. strings) are replaced as normal.
:::

## Update by Dictionary

```csharp
Person row = db.SingleById<Person>(row.Id);
var obj = row.ToObjectDictionary();
obj[nameof(Person.LastName)] = "Smith";
db.Update<Person>(obj);
```

## UpdateOnly by Dictionary

```csharp
// By Primary Key Id
var fields = new Dictionary<string, object> {
    [nameof(Person.Id)] = 1,
    [nameof(Person.FirstName)] = "John",
    [nameof(Person.LastName)] = null,
};

db.UpdateOnly<Person>(fields);

// By Custom Where Expression
var fields = new Dictionary<string, object> {
    [nameof(Person.FirstName)] = "John",
    [nameof(Person.LastName)] = null,
};

db.UpdateOnly<Person>(fields, p => p.LastName == "Hendrix");
```


# OrmLite DELETE APIs
Source: https://docs.servicestack.net/ormlite/apis/delete

Deleting rows in OrmLite is simple and straight-forward with APIs to support multiple use-cases including deleting by entity, by Id, by lambda expression, by SqlExpression, or Custom SQL expression.

## Delete By Entity:

```csharp
var alive = db.Single<Track>(x => x.Name == "Alive");
db.Delete(alive);
var stillAlive = db.Exists<Track>(x => x.Id == alive.Id);
```

## Delete By Id:

```csharp
db.DeleteById<Track>(trackId);
```

## Delete By inline Expression:

Like updates for DELETE's we also provide APIs that take a where Expression:

```csharp
db.Delete<Person>(p => p.Age == 27);

var noOfNirvanaTracksDeleted = db.Delete<Track>(x => x.ArtistId == nirvana.Id && x.Year == 1991);
```

## Delete By SqlExpression:

```csharp
var q = db.From<Person>()
    .Where(p => p.Age == 27);

db.Delete<Person>(q);
```

## Delete By Custom SQL

As well as un-typed, string-based expressions:

```csharp
db.Delete<Person>(where: "Age = @age", new { age = 27 });
```

## Delete from Table JOIN

Using a SqlExpression to delete rows by querying from a joined table:

```csharp
var q = db.From<Person>()
    .Join<PersonJoin>((x, y) => x.Id == y.PersonId)
    .Where<PersonJoin>(x => x.Id == 2);

db.Delete(q);
```

> Not supported in MySql

## Delete by Dictionary

```csharp
db.Delete<Rockstar>(new Dictionary<string, object> {
    ["Age"] = 27
});
```

## Delete Multiple Rows Examples

```csharp
//Multiple Entities
var nirvana = db.Single<Artist>(x => x.Name == "Nirvana");
var nirvanaTracks = db.Select<Track>(x => x.ArtistId == nirvana.Id);
var noOfNirvanaTracksDeleted = db.DeleteAll(nirvanaTracks);

//Multiple rows by Ids
var live = db.Single<Artist>(x => x.Name == "Live");
var liveTrackIds = db.Column<int>(db.From<Track>().Where(x => x.ArtistId == live.Id).Select(x => x.Id));
var noOfLiveTracksDeleted = db.DeleteByIds<Track>(liveTrackIds);

// Delete all Tracks (WARNING)
var noOfTracksDeleted = db.DeleteAll<Track>();
```


# Schema, Table &amp; Column APIs
Source: https://docs.servicestack.net/ormlite/apis/schema

## Create Table APIs

OrmLite's `CreateTable` APIs can be used to create RDBMS tables from your C# POCO Data Models.

If you also need to ensure tables are populated with Seed Data when they're created, use `CreateTableIfNotExists`, e.g:

```csharp
using var db = appHost.Resolve<IDbConnectionFactory>().Open();

if (db.CreateTableIfNotExists<Person>())
{
    db.Insert(new Person { Id = 1, Name = "John Doe" });
}
```

### Create Tables

Or if you just want to create tables that don't exist:

```csharp
db.CreateTableIfNotExists<Person>()
db.CreateTable<Person>(overwrite:false);

// Runtime Type
db.CreateTableIfNotExists(typeof(Person));
db.CreateTables(overwrite:false, typeof(Person));

// Multiple Tables
db.CreateTableIfNotExists(typeof(TableA), typeof(TableB), typeof(TableC));
db.CreateTables(overwrite:false, typeof(TableA), typeof(TableB), typeof(TableC));
```

### Recreate Tables

To ensure existing tables are dropped and new tables are always re-created, use:

```csharp
db.DropAndCreateTable<Person>();
db.CreateTable<Person>(overwrite:true);


// Multiple Runtime Types
db.DropAndCreateTables(typeof(TableA), typeof(TableB), typeof(TableC));
db.CreateTables(overwrite:true, typeof(TableA), typeof(TableB), typeof(TableC));
```

### Drop and Create Tables

However if your tables have foreign keys, you'll need to drop and re-create them in the order that satisfies their foreign key constraints, e.g:

```csharp
db.DropTable<TableB>();
db.DropTable<TableA>();

db.CreateTable<TableA>();
db.CreateTable<TableB>();

// Runtime Type
db.DropTable(typeof(Person));
db.CreateTable(typeof(Person));

// Multiple Runtime Types
db.DropTables(typeof(TableA), typeof(TableB), typeof(TableC));
db.CreateTables(overwrite:true, typeof(TableA), typeof(TableB), typeof(TableC));
```

#### Pre / Post Custom SQL Hooks when Creating and Dropping tables

Pre / Post Custom SQL Hooks allow you to inject custom SQL before and after tables are created or dropped, e.g:

```csharp
[PostCreateTable("INSERT INTO Person (Name) VALUES ('Foo');" +
                 "INSERT INTO Person (Name) VALUES ('Bar');")]
public class Person
{
    [AutoIncrement]
    public int Id { get; set; }
    public string Name { get; set; }
}
```

## Create Schemas

The `CreateSchema` APIs can be used to create Schemas in RDBMSs that support it, where they don't already exist:

```csharp
db.CreateSchema("TheSchema");
```

Alternatively you can use the typed API to create Schemas defined on Data Models, e.g:

```csharp
[Schema("Schema")]
public class Person
{
    [AutoIncrement]
    public int Id { get; set; }
    public string Name { get; set; }
}

db.CreateSchema<Person>();
```

## Query Existing Tables

As the queries for retrieving table names can vary amongst different RDBMS's, we've abstracted their implementations behind uniform APIs
where you can now get a list of table names and their row counts for all supported RDBMS's with:

```csharp
List<string> tableNames = db.GetTableNames();

List<KeyValuePair<string,long>> tableNamesWithRowCounts = db.GetTableNamesWithRowCounts();
```

::: info
`*Async` variants also available
:::

Both APIs can be called with an optional `schema` if you only want the tables for a specific schema.
It defaults to using the more efficient RDBMS APIs, which if offered typically returns an approximate estimate of rowcounts in each table.

If you need exact table row counts, you can specify `live:true`:

```csharp
var tablesWithRowCounts = db.GetTableNamesWithRowCounts(live:true);
```

## Modify Custom Schema

OrmLite provides Typed APIs for modifying Table Schemas that makes it easy to inspect the state of an
RDBMS Table which can be used to determine what modifications you want on it, e.g:

```csharp
class Poco 
{
    public int Id { get; set; }
    public string Name { get; set; }
    public string Ssn { get; set; }
}

db.DropTable<Poco>();
db.TableExists<Poco>(); //= false

db.CreateTable<Poco>(); 
db.TableExists<Poco>(); //= true

db.ColumnExists<Poco>(x => x.Ssn); //= true
db.DropColumn<Poco>(x => x.Ssn);
db.ColumnExists<Poco>(x => x.Ssn); //= false
```

In a future version of your Table POCO you can use `ColumnExists` to detect which columns haven't been
added yet, then use `AddColumn` to add it, e.g:

```csharp
class Poco 
{
    public int Id { get; set; }
    public string Name { get; set; }

    [Default(0)]
    public int Age { get; set; }
}

if (!db.ColumnExists<Poco>(x => x.Age)) //= false
    db.AddColumn<Poco>(x => x.Age);

db.ColumnExists<Poco>(x => x.Age); //= true
```

## Modify Schema APIs

Additional Modify Schema APIs available in OrmLite include:

### AlterTable

When maximum flexibility is needed to perform Alter table commands with custom SQL, e.g:

```csharp
db.AlterTable<Poco>("ADD Email VARCHAR(255)");
db.AlterTable(typeof(Poco), "ADD Email VARCHAR(255)");
```

### AddColumn

For adding a **new column** definition to an existing table, e.g:

```csharp
public class Poco
{
    [Index]
    public string Code { get; set; }
}

db.AddColumn<Poco>(x => x.Code);
db.AddColumn(table:"Poco", new FieldDefinition { Name = "Code", FieldType = typeof(string) });
```

### AlterColumn

For modifying an **existing column** definition, e.g:

```csharp
public class Poco
{
    [Index]
    public string Code { get; set; }
}

db.AlterColumn<Poco>(x => x.Code);
db.AlterColumn(table:"Booking", new FieldDefinition { Name = "Code", FieldType = typeof(string), IsIndexed = true });
```

### RenameColumn

For renaming an existing column, e.g:

```csharp
db.RenameColumn<Poco>(x => x.ToName, fromName);
db.RenameColumn(typeof(Poco), fromName, toName);
db.RenameColumn(table:"Poco", oldColumn:fromName, newColumn:toName);
```

### DropColumn

For dropping an existing column, e.g:

```csharp
db.DropColumn<Poco>(x => x.Name);
db.DropColumn(typeof(Poco), "Name");
db.DropColumn(table:"Poco", column:"Name");
```

### AddForeignKey

To add a Foreign Key relationship to existing tables, e.g:

```csharp
db.AddForeignKey<Poco, ReferencedType>(
    field: t => t.RefId, 
    foreignField: tr => tr.Id,
    onUpdate: OnFkOption.NoAction, 
    onDelete: OnFkOption.Cascade, 
    foreignKeyName);
```

### DropForeignKey

To delete an existing Foreign Key:

```csharp
db.DropForeignKey<Poco>(foreignKeyName);
```

### CreateIndex

To create an index on an existing column, e.g:

```csharp
db.CreateIndex<Poco>(x => x.Code);
db.CreateIndex<Poco>(x => x.Code, indexName);
db.CreateIndex<Poco>(x => x.Code, indexName, unique:true);
```

### DropIndex

To drop an existing index, e.g:

```csharp
db.DropIndex<Poco>(indexName);
```

## Custom SQL

When you need functionality beyond what's available in the Modify Schema APIs like needing to access RDBMS-specific features you can drop down to SQL:

```csharp
db.ExecuteSql("ALTER TABLE Track ADD Rand INT default 0");
db.ExecuteSql("UPDATE Track SET Rand = abs(random()) % 1000");

Db.ExecuteSql("INSERT INTO page_stats (ref_id, fav_count) VALUES (@refId, @favCount)",
              new { refId, favCount })

//Async:
Db.ExecuteSqlAsync("UPDATE page_stats SET view_count = view_count + 1 WHERE id = @id", new { id })

//PostgreSQL Arrays
await Db.ExecuteSqlAsync(@"UPDATE notification SET emailed_user_ids = emailed_user_ids || @userId WHERE id = @id", 
    new { userId, id = notificationId });
```


## Typed `Sql.Cast()` SQL Modifier

The `Sql.Cast()` provides a cross-database abstraction for casting columns or expressions in SQL queries, e.g:

```csharp
db.Insert(new SqlTest { Value = 123.456 });

var results = db.Select<(int id, string text)>(db.From<SqlTest>()
    .Select(x => new {
        x.Id,
        text = Sql.Cast(x.Id, Sql.VARCHAR) + " : " + Sql.Cast(x.Value, Sql.VARCHAR) + " : " 
             + Sql.Cast("1 + 2", Sql.VARCHAR) + " string"
    }));

results[0].text //= 1 : 123.456 : 3 string
```

## Typed `Column<T>` and `Table<T>` APIs

You can use the `Column<T>` and `Table<T>()` methods to resolve the quoted names of a Column or Table within SQL Fragments (taking into account any configured aliases or naming strategies).

Usage Example of the new APIs inside a `CustomJoin()` expression used to join on a custom SELECT expression:

```csharp
q.CustomJoin($"LEFT JOIN (SELECT {q.Column<Job>(x => x.Id)} ...")
q.CustomJoin($"LEFT JOIN (SELECT {q.Column<Job>(nameof(Job.Id))} ...")

q.CustomJoin($"LEFT JOIN (SELECT {q.Column<Job>(x => x.Id, tablePrefix:true)} ...")
//Equivalent to:
q.CustomJoin($"LEFT JOIN (SELECT {q.Table<Job>()}.{q.Column<Job>(x => x.Id)} ...")

q.Select($"{q.Column<Job>(x => x.Id)} as JobId, {q.Column<Task>(x => x.Id)} as TaskId")
//Equivalent to:
q.Select<Job,Task>((j,t) => new { JobId = j.Id, TaskId = t.Id })
```

## DB Parameter APIs

To enable even finer-grained control of parameterized queries we've added new overloads that take a collection of IDbDataParameter's:

```csharp
List<T> Select<T>(string sql, IEnumerable<IDbDataParameter> sqlParams)
T Single<T>(string sql, IEnumerable<IDbDataParameter> sqlParams)
T Scalar<T>(string sql, IEnumerable<IDbDataParameter> sqlParams)
List<T> Column<T>(string sql, IEnumerable<IDbDataParameter> sqlParams)
IEnumerable<T> ColumnLazy<T>(string sql, IEnumerable<IDbDataParameter> sqlParams)
HashSet<T> ColumnDistinct<T>(string sql, IEnumerable<IDbDataParameter> sqlParams)
Dictionary<K, List<V>> Lookup<K, V>(string sql, IEnumerable<IDbDataParameter> sqlParams)
List<T> SqlList<T>(string sql, IEnumerable<IDbDataParameter> sqlParams)
List<T> SqlColumn<T>(string sql, IEnumerable<IDbDataParameter> sqlParams)
T SqlScalar<T>(string sql, IEnumerable<IDbDataParameter> sqlParams)
```

::: info
Including Async equivalents for each of the above Sync APIs.
:::

The new APIs let you execute parameterized SQL with finer-grained control over the `IDbDataParameter` used, e.g:

```csharp
IDbDataParameter pAge = db.CreateParam("age", 40, dbType:DbType.Int16);
db.Select<Person>("SELECT * FROM Person WHERE Age > @pAge", new[] { pAge });
```

The new `CreateParam()` extension method above is a useful helper for creating custom IDbDataParameter's.

## Customize null values

The new `OrmLiteConfig.OnDbNullFilter` lets you replace DBNull values with a custom value, so you could convert all `null` strings to be populated with `"NULL"` using:

```csharp
OrmLiteConfig.OnDbNullFilter = fieldDef => 
    fieldDef.FieldType == typeof(string)
        ? "NULL"
        : null;
```

## Modify Schema Versioning Examples

OrmLite provides Typed APIs for modifying Table Schemas that makes it easy to inspect the state of an RDBMS Table which can be used to determine what modifications you want to apply to it to upgrade it to the latest version:

```csharp
public class Track
{
    [AutoIncrement]
    public int Id { get; set; }
    public string Name { get; set; }
    public string Album { get; set; }
    public int ArtistId { get; set; } 
}

// Map to same "Track" RDBMS Table, not needed when Track is refactored
[Alias("Track")]
public class Track_v2
{
    [AutoIncrement]
    public int Id { get; set; }
    public string Name { get; set; }
    public string Album { get; set; }
    public int ArtistId { get; set; } 
    [Default(5)]
    public int Rating { get; set; }  // ADD
}

var v1TableExists = db.TableExists<Track>();
$"Table Exists: {v1TableExists}".Print();
if (!v1TableExists)
{
	db.CreateTable<Track>(); 
	v1TableExists = db.TableExists<Track>();
}

var v1RatingExists = db.ColumnExists<Track_v2>(x => x.Rating);
$"Rating Exists v1: {v1RatingExists}".Print();
if (!v1RatingExists)
{
    db.AddColumn<Track_v2>(x => x.Rating);
    var v2RatingExists = db.ColumnExists<Track_v2>(x => x.Rating);
}
```

## Create Table Examples

As a code-first ORM, creating tables is effortless in OrmLite that uses your POCO Type definition to generate RDBMS Table schemas that cleanly maps .NET data types 1:1 to the most appropriate RDBMS column definition:

```csharp
public class AllFields
{
    public string Id { get; set; } //implicit Primary Key
    public int Int { get; set; }
    public int? NInt { get; set; }
    public long Long { get; set; }
    public long? NLong { get; set; }
    public uint Uint { get; set; }
    public uint? NUint { get; set; }
    public Guid Guid { get; set; }
    public Guid? NGuid { get; set; }
    public bool Bool { get; set; }
    public bool? NBool { get; set; }
    public DateTime DateTime { get; set; }
    public DateTime? NDateTime { get; set; }
    public float Float { get; set; }
    public float? NFloat { get; set; }
    public double Double { get; set; }
    public double? NDouble { get; set; }
    public decimal Decimal { get; set; }
    public decimal? NDecimal { get; set; }
    public TimeSpan TimeSpan { get; set; }
    public TimeSpan? NTimeSpan { get; set; }
}

if (db.CreateTableIfNotExists<AllFields>())  //= true; if table was created
{
    db.Insert(new AllFields { 
        Id = "Id", Int = 1, Long = 2, Uint = 3, Guid = Guid.NewGuid(), Bool = true, DateTime = DateTime.UtcNow,
        Float = 1.1f, Double = 2.2d, Decimal = 3.3m, TimeSpan = new TimeSpan(1,1,1,1) });
}

var allFields = db.SingleById<AllFields>("Id");

db.DropAndCreateTable<AllFields>();
var emptyAllFieldsCount = db.Count<AllFields>();

db.DropTable<AllFields>();
var oldTableExists = db.TableExists<AllFields>();

db.CreateTable<AllFields>();
var newTableExists = db.TableExists<AllFields>();
```

## Create Tables with Complex Types

OrmLite also supports persisting rich complex types which are blobbed by default or you can use the [Reference] support to persist Nested Complex Types in their own Table Definitions:

```csharp
public class ArtistWithBlobTracks
{
    public int Id { get; set; }
    public string Name { get; set; }
    //By default Complex Types are blobbed with the containing record
    public List<Track> Tracks { get; set; }
}
public class Artist
{
    public int Id { get; set; }
    public string Name { get; set; }
    //Complex Type References are persisted in own table
    [Reference] public List<Track> Tracks { get; set; }
}
public class Track
{
    [AutoIncrement] 
    public int Id { get; set; }
    public string Name { get; set; }
    public string Album { get; set; }
    public int ArtistId { get; set; } // Implicit Reference Id
}

db.CreateTable<ArtistWithBlobTracks>();
db.CreateTable<Artist>();
db.CreateTable<Track>();

db.Insert(new ArtistWithBlobTracks { 
    Id = 1, Name = "Faith No More", 
    Tracks = new List<Track> { 
        new Track { Name = "Everythings Ruined", Album = "Angel Dust" },
        new Track { Name = "Ashes to Ashes", Album = "Album of the Year" } } 
});
var artistWithBlobTracks = db.SingleById<ArtistWithBlobTracks>(1);
$"Artist with blobbed Tracks: {artistWithBlobTracks.Dump()}".Print();
$"\nBlob Tracks Count: {db.Count<Track>()}".Print();

db.Save(new Artist { 
    Id = 1, Name = "Faith No More", 
    Tracks = new List<Track> { 
        new Track { Name = "Everythings Ruined", Album = "Angel Dust" },
        new Track { Name = "Ashes to Ashes", Album = "Album of the Year" } }
}, references: true);

var artistWithRefTracks = db.LoadSingleById<Artist>(1);
$"\nArtist with referenced Tracks: {artistWithRefTracks.Dump()}".Print();
$"\nReferenced Tracks Count: {db.Count<Track>()}".Print();
```

## Customize Tables using Attributes

When needed you can markup your POCO's with .NET Attributes to allow further specialization of your Table schema and unlock RDBMS server features:

```csharp
[Schema("TheSchema")]
[Alias("TableAlias")]
public class CustomTable
{
    [PrimaryKey]
    [AutoIncrement]
    public int CustomKey { get; set; }
    
    [Alias("RDBMS_NAME")]
    public string CSharpName { get; set; }
    
    [Index(Unique = true)]
    public string IndexColumn { get; set; }

    [Default(100)]
    public int? DefaultValue { get; set; }
    
    [Default(OrmLiteVariables.SystemUtc)]
    public DateTime CurrentDate { get; set; }

    [Required]
    [StringLength(3)]
    public string RequiredCustomLength { get; set; } //= NOT NULL
    
    [DecimalLength(18,4)]
    public decimal? CustomDecimalPrecision { get; set; }
    
    [CustomField("DECIMAL(18,4)")]
    public decimal? CustomProperty { get; set; }
    
    // Completely ignored in OrmLite (used in Serialization only)
    [Ignore]
    public int IgnoredProperty { get; set; }

    // Doesn't exist on Table, only used in SELECT Statements
    [CustomSelect("CustomKey + DefaultValue")] 
	public int SelectOnlyProperty { get; set; }
}

db.CreateTable<CustomTable>();

var id = db.Insert(new CustomTable { CSharpName = "Name", IndexColumn = "bar", RequiredCustomLength = "foo",
	CustomDecimalPrecision = 1.111m, CustomProperty = 2.222m }, selectIdentity:true);

var customTableRow = db.SingleById<CustomTable>(id);
```

## Create Tables with Foreign Keys

A popular use-case where you'd want to use Attributes is to define Foreign Keys:

```csharp
public class Artist
{
    public int Id { get; set; }
    public string Name { get; set; }
}

public class Album
{
    public int Id { get; set; }
    public string Name { get; set; }

    [ForeignKey(typeof(Album), OnDelete = "CASCADE")]
    public int ArtistId { get; set; }
}

public class Track
{
    public int Id { get; set; }
    public string Name { get; set; }

    [References(typeof(Album))]
    public int AlbumId { get; set; } // db-agnostic attribute, generates FK to Artist

    [ForeignKey(typeof(Artist), OnDelete = "CASCADE")]
    public int ArtistId { get; set; }
}


db.CreateTable<Artist>();
db.CreateTable<Album>();
db.CreateTable<Track>(); //Order is important for tables with Foreign Keys

db.Insert(new Artist { Id = 1, Name = "Nirvana" });
db.Insert(new Album { Id = 2, Name = "Nevermind", ArtistId = 1 });
db.Insert(new Track { Id = 3, Name = "Smells Like Teen Spirit", AlbumId = 2, ArtistId = 1 });

var artist = db.SingleById<Artist>(1);
var album = db.SingleById<Album>(2);
var track = db.SingleById<Track>(3);
```


# Bulk Inserts
Source: https://docs.servicestack.net/ormlite/bulk-inserts

<div class="py-8 max-w-7xl mx-auto px-4 sm:px-6">
    <lite-youtube class="w-full mx-4 my-4" width="560" height="315" videoid="3gO_OEWIyPo" style="background-image: url('https://img.youtube.com/vi/3gO_OEWIyPo/maxresdefault.jpg')"></lite-youtube>
</div>

Bulk Insert implementations are available for each [supported RDBMS](/ormlite/installation) enabling the most efficient
ways for inserting large amounts of data from code, which is encapsulated behind OrmLite's `BulkInsert` API:

```csharp
db.BulkInsert(rows);
```

## Bulk Insert Implementations

Which uses the optimal implementation available for each RDBMS:

- **PostgreSQL** - Uses PostgreSQL's [COPY](https://www.postgresql.org/docs/current/sql-copy.html)
  command via Npgsql's [Binary Copy](https://www.npgsql.org/doc/copy.html) import
- **MySql** - Uses [MySqlBulkLoader](https://dev.mysql.com/doc/connector-net/en/connector-net-programming-bulk-loader.html)
  feature where data is written to a temporary **CSV** file that's imported directly by `MySqlBulkLoader`
- **MySqlConnector** - Uses [MySqlConnector's MySqlBulkLoader](https://mysqlconnector.net/api/mysqlconnector/mysqlbulkloadertype/)
  implementation which makes use of its `SourceStream` feature to avoid writing to a temporary file
- **SQL Server** - Uses SQL Server's `SqlBulkCopy` feature which imports data written to an in-memory `DataTable`
- **SQLite** - SQLite doesn't have a specific import feature, instead Bulk Inserts are performed using batches of [Multiple Rows Inserts](https://www.tutorialscampus.com/sql/insert-multiple-rows.htm)
  to reduce I/O calls down to a configurable batch size
- **Firebird** - Is also implemented using **Multiple Rows Inserts** within an [EXECUTE BLOCK](https://firebirdsql.org/refdocs/langrefupd20-execblock.html)
  configurable up to Firebird's maximum of **256** statements

## SQL Multiple Row Inserts

All RDBMS's also support SQL's Multiple Insert Rows feature which is an efficient and compact alternative to inserting
multiple rows within a single INSERT statement:

```sql
INSERT INTO Contact (Id, FirstName, LastName, Age) VALUES 
(1, 'John', 'Doe', 27),
(2, 'Jane', 'Doe', 42);
```

Normally OrmLite APIs uses parameterized statements however for Bulk Inserts it uses inline rasterized values in order
to construct and send large SQL INSERT statements that avoids RDBMS's max parameter limitations, which if preferred can
be configured to be used instead of its default RDBMS-specific implementation:

```csharp
db.BulkInsert(rows, new BulkInsertConfig {
    Mode = BulkInsertMode.Sql
});
```

## Batch Size

**Multiple Row Inserts** are sent in batches of **1000** (Maximum for SQL Server), Firebird uses a maximum of **256**
whilst other RDBMS's can be configured to use larger batch sizes:

```csharp
db.BulkInsert(rows, new BulkInsertConfig {
    BatchSize = 1000
});
```

## Bulk Insert Benchmarks

To test the performance of Bulk Inserts we've ran a number of benchmarks across macOS, Linux and Windows in our
[Bulk Insert Performance](https://servicestack.net/posts/bulk-insert-performance) blog post.

The Relative performances of Apple M2 macOS Benchmarks provide some indication of the performance benefits of Bulk Inserts
you can expect, confirming that they offer much better performance when needing to insert a significant number of rows,
we're it's up to **138x** more efficient than inserting just **1,000 rows**.

:::{.table .table-striped .text-base}

Relative performance for Inserting **1,000** records:

| Database       | Bulk Inserts | Multiple Rows Inserts | Single Row Inserts |
|----------------|-------------:|----------------------:|-------------------:|
| PostgreSQL     |           1x |                 1.32x |             57.04x |
| MySqlConnector |           1x |                 1.04x |            137.78x |
| MySql          |           1x |                 1.16x |            131.47x |
| SqlServer      |           1x |                 6.61x |             74.19x |

Relative performance for Inserting **10,000** records:

| Database       | Bulk Inserts | Multiple Rows Inserts |
|----------------|-------------:|----------------------:|
| PostgreSQL     |           1x |                 3.37x |
| MySqlConnector |           1x |                 1.24x |
| MySql          |           1x |                 1.52x |
| SqlServer      |           1x |                 9.36x |

Relative performance for Inserting **100,000** records:

| Database       | Bulk Inserts | Multiple Rows Inserts |
|----------------|-------------:|----------------------:|
| PostgreSQL     |           1x |                 3.68x |
| MySqlConnector |           1x |                 2.04x |
| MySql          |           1x |                 2.31x |
| SqlServer      |           1x |                10.14x |

:::

It also shows that batched Multiple Row Inserts Bulk Insert mode is another good option for inserting large number of
rows that's within **3.4x** performance range of optimal Bulk Insert implementations, for all but SQL Server which
is an order of magnitude slower than using `SqlBulkCopy`.


# Reference Support, POCO style
Source: https://docs.servicestack.net/ormlite/reference-support

OrmLite lets you Store and Load related entities in separate tables using `[Reference]` attributes in primary tables in conjunction with `{Parent}Id` property convention in child tables, e.g:

```csharp
public class Customer
{
    [AutoIncrement]
    public int Id { get; set; }
    public string Name { get; set; }

    [Reference] // Save in CustomerAddress table
    public CustomerAddress PrimaryAddress { get; set; }

    [Reference] // Save in Order table
    public List<Order> Orders { get; set; }
}

public class CustomerAddress
{
    [AutoIncrement]
    public int Id { get; set; }
    public int CustomerId { get; set; } //`{Parent}Id` convention to refer to Customer
    public string AddressLine1 { get; set; }
    public string AddressLine2 { get; set; }
    public string City { get; set; }
    public string State { get; set; }
    public string Country { get; set; }
}

public class Order
{
    [AutoIncrement]
    public int Id { get; set; }
    public int CustomerId { get; set; } //`{Parent}Id` convention to refer to Customer
    public string LineItem { get; set; }
    public int Qty { get; set; }
    public decimal Cost { get; set; }
}
```

With the above structure you can save a POCO and all its entity references with `db.Save(T,references:true)`, e.g:

```csharp
var customer =  new Customer {
    Name = "Customer 1",
    PrimaryAddress = new CustomerAddress {
        AddressLine1 = "1 Australia Street",
        Country = "Australia"
    },
    Orders = new[] {
        new Order { LineItem = "Line 1", Qty = 1, Cost = 1.99m },
        new Order { LineItem = "Line 2", Qty = 2, Cost = 2.99m },
    }.ToList(),
};

db.Save(customer, references:true);
```

This saves the root customer POCO in the `Customer` table, its related PrimaryAddress in the `CustomerAddress` table and its 2 Orders in the `Order` table.

## Querying POCO's with References

The `Load*` APIs are used to automatically load a POCO and all it's child references, e.g:

```csharp
var customer = db.LoadSingleById<Customer>(customerId);
```

Using Typed SqlExpressions:

```csharp
var customers = db.LoadSelect<Customer>(x => x.Name == "Customer 1");
```

More examples available in [LoadReferencesTests.cs](https://github.com/ServiceStack/ServiceStack/blob/main/ServiceStack.OrmLite/tests/ServiceStack.OrmLite.Tests/LoadReferencesTests.cs)

Unlike normal complex properties, references:

- Doesn't persist as complex type blobs
- Doesn't impact normal querying
- Saves and loads references independently of itself
- Are serializable with Text serializers (only populated are visible).
- Loads related data only 1-reference-level deep

Basically they provide a better story when dealing with referential data that doesn't impact the POCO's ability to be used as DTOs.

## Merge Disconnected POCO Result Sets

The `Merge` extension method can stitch disconnected POCO collections together as per their relationships defined in OrmLite's POCO References.

For example, you can select a collection of Customers who've made an order with quantities of 10 or more and in a separate query select their filtered Orders and then merge the results of these 2 distinct queries together with:

```csharp
//Select Customers who've had orders with Quantities of 10 or more
var q = db.From<Customer>()
          .Join<Order>()
          .Where<Order>(o => o.Qty >= 10)
          .SelectDistinct();

List<Customer> customers = db.Select<Customer>(q);

//Select Orders with Quantities of 10 or more
List<Order> orders = db.Select<Order>(o => o.Qty >= 10);

customers.Merge(orders); // Merge disconnected Orders with their related Customers

customers.PrintDump();   // Print merged customers and orders datasets
```

## Custom Load References

You can selectively specify which references you want to load using the `include` parameter, e.g:

```csharp
var customerWithAddress = db.LoadSingleById<Customer>(customer.Id, include: new[] { "PrimaryAddress" });

//Alternative
var customerWithAddress = db.LoadSingleById<Customer>(customer.Id, include: x => new { x.PrimaryAddress });
```

### Custom Select with JOIN

You can specify SQL Aliases for ambiguous columns using anonymous properties, e.g:

```csharp
var q = db.From<Table>()
    .Join<JoinedTable>()
    .Select<Table, JoinedTable>((a, b) => new { a, JoinId = b.Id, JoinName = b.Name });
```

Which is roughly equivalent to:

```sql
SELECT a.*, b.Id AS JoinId, b.Name AS JoinName
```

Where it selects all columns from the primary `Table` as well as `Id` and `Name` columns from `JoinedTable,`
returning them in the `JoinId` and `JoinName` custom aliases.

## Nested JOIN Table Expressions

You can also query POCO References on JOIN tables, e.g:

```csharp
var q = db.From<Table>()
    .Join<Join1>()
    .Join<Join1, Join2>()
    .Where(x => !x.IsValid.HasValue && 
        x.Join1.IsValid &&
        x.Join1.Join2.Name == theName &&
        x.Join1.Join2.IntValue == intValue)
    .GroupBy(x => x.Join1.Join2.IntValue)
    .Having(x => Sql.Max(x.Join1.Join2.IntValue) != 10)
    .Select(x => x.Join1.Join2.IntValue);
```

## Table aliases

The `TableAlias` APIs lets you specify table aliases when joining same table multiple times together to differentiate from any
ambiguous columns in Queries with multiple self-reference joins, e.g:

```csharp
var q = db.From<Page>(db.TableAlias("p1"))
    .Join<Page>((p1, p2) => 
        p1.PageId == p2.PageId && 
        p2.ActivityId == activityId, db.TableAlias("p2"))
    .Join<Page,Category>((p2,c) => Sql.TableAlias(p2.Category) == c.Id)
    .Join<Page,Page>((p1,p2) => Sql.TableAlias(p1.Rank,"p1") < Sql.TableAlias(p2.Rank,"p2"))
    .Select<Page>(p => new {
        ActivityId = Sql.TableAlias(p.ActivityId, "p2")
    });

var rows = db.Select(q);
```

## Unique Constraints

In addition to creating an Index with unique constraints using `[Index(Unique=true)]` you can now use `[Unique]` to enforce a single column should only contain unique values or annotate the class with `[UniqueConstraint]` to specify a composite unique constraint, e.g:

```csharp
[UniqueConstraint(nameof(PartialUnique1), nameof(PartialUnique2), nameof(PartialUnique3))]
public class UniqueTest
{
    [AutoIncrement]
    public int Id { get; set; }

    [Unique]
    public string UniqueField { get; set; }

    public string PartialUnique1 { get; set; }
    public string PartialUnique2 { get; set; }
    public string PartialUnique3 { get; set; }
}
```

## Auto populated Guid Ids

Support for Auto populating `Guid` Primary Keys is available using the `[AutoId]` attribute, e.g:

```csharp
public class Table
{
    [AutoId]
    public Guid Id { get; set; }
}
```

In SQL Server it will populate `Id` primary key with `newid()`, in `PostgreSQL` it uses `uuid_generate_v4()` which requires installing the the **uuid-ossp** extension by running the SQL below on each PostgreSQL RDBMS it's used on:

```sql
CREATE EXTENSION IF NOT EXISTS "uuid-ossp"
```

For all other RDBMS's OrmLite will populate the `Id` with `Guid.NewGuid()`. In all RDBMS's it will populate the `Id` property on `db.Insert()` or `db.Save()` with the new value, e.g:

```csharp
var row = new Table { ... };
db.Insert(row);
row.Id //= Auto populated with new Guid
```

## BelongTo Attribute

The `[BelongTo]` attribute can be used for specifying how Custom POCO results are mapped when the resultset is ambiguous, e.g:

```csharp
class A { 
    public int Id { get; set; }
}
class B {
    public int Id { get; set; }
    public int AId { get; set; }
}
class C {
    public int Id { get; set; }
    public int BId { get; set; }
}
class Combined {
    public int Id { get; set; }
    [BelongTo(typeof(B))]
    public int BId { get; set; }
}

var q = db.From<A>()
    .Join<B>()
    .LeftJoin<B,C>();

var results = db.Select<Combined>(q); //Combined.BId = B.Id
```

## Advanced Example

Seeing how the SqlExpression is constructed, joined and mapped, we can take a look at a more advanced example to showcase more of the new API's available:

```csharp
List<FullCustomerInfo> rows = db.Select<FullCustomerInfo>(  // Map results to FullCustomerInfo POCO
  db.From<Customer>()                                       // Create typed Customer SqlExpression
    .LeftJoin<CustomerAddress>()                            // Implicit left join with base table
    .Join<Customer, Order>((c,o) => c.Id == o.CustomerId)   // Explicit join and condition
    .Where(c => c.Name == "Customer 1")                     // Implicit condition on base table
    .And<Order>(o => o.Cost < 2)                            // Explicit condition on joined Table
    .Or<Customer,Order>((c,o) => c.Name == o.LineItem));    // Explicit condition with joined Tables
```

The comments next to each line document each Type of API used. Some of the new API's introduced in this example include:

- Usage of `LeftJoin` for specifying a LEFT JOIN, `RightJoin` and `FullJoin` also available
- Usage of `And<Table>()`, to specify an **AND** condition on a Joined table
- Usage of `Or<Table1,Table2>`, to specify an **OR** condition against 2 joined tables

More code examples of References and Joined tables are available in:

- [LoadReferencesTests.cs](https://github.com/ServiceStack/ServiceStack/blob/main/ServiceStack.OrmLite/tests/ServiceStack.OrmLite.Tests/LoadReferencesTests.cs)
- [LoadReferencesJoinTests.cs](https://github.com/ServiceStack/ServiceStack/blob/main/ServiceStack.OrmLite/tests/ServiceStack.OrmLite.Tests/LoadReferencesJoinTests.cs)


# Typed SqlExpression support for JOINs
Source: https://docs.servicestack.net/ormlite/typed-joins

Whilst OrmLite aims to provide a light-weight typed wrapper around SQL, it offers a number of convenient features that makes working with relational databases a clean and enjoyable experience.

Starting with the most basic example you can simply specify the table you want to join with:

```csharp
var q = db.From<Customer>()
          .Join<CustomerAddress>();

var dbCustomers = db.Select<Customer>(q);
```

This query roughly maps to the following SQL:

```sql
SELECT Customer.* 
  FROM Customer 
       INNER JOIN 
       CustomerAddress ON (Customer.Id == CustomerAddress.CustomerId)
```

Just like before `q` is an instance of `SqlExpression<Customer>` which is bounded to the base `Customer` type (and what any subsequent implicit API's apply to).

To better illustrate the above query, lets expand it to the equivalent explicit query:

```csharp
SqlExpression<Customer> q = db.From<Customer>();
q.Join<Customer,CustomerAddress>((cust,address) => cust.Id == address.CustomerId);

List<Customer> dbCustomers = db.Select(q);
```

## Reference Conventions

The above query implicitly joins together the `Customer` and `CustomerAddress` POCO's using the same `{ParentType}Id` property convention used in [OrmLite's support for References](https://github.com/ServiceStack/ServiceStack/blob/main/ServiceStack.OrmLite/tests/ServiceStack.OrmLite.Tests/LoadReferencesTests.cs), e.g:

```csharp
class Customer {
    public int Id { get; set; }
    ...
}
class CustomerAddress {
    public int Id { get; set; }
    public int CustomerId { get; set; }  // Reference based on Property name convention
}
```

References based on matching alias names is also supported, e.g:

```csharp
[Alias("LegacyCustomer")]
class Customer {
    public int Id { get; set; }
    ...
}
class CustomerAddress {
    public int Id { get; set; }

    [Alias("LegacyCustomerId")]             // Matches `LegacyCustomer` Alias
    public int RenamedCustomerId { get; set; }  // Reference based on Alias Convention
}
```

## Self References

Self References are also supported for **1:1** relations where the Foreign Key can instead be on the parent table:

```csharp
public class Customer
{
    ...
    public int CustomerAddressId { get; set; }

    [Reference]
    public CustomerAddress PrimaryAddress { get; set; }
}
```

## Foreign Key and References Attributes

References that don't follow the above naming conventions can be declared explicitly using
the `[References]` and `[ForeignKey]` attributes:

```csharp
public class Customer
{
    [References(typeof(CustomerAddress))]
    public int PrimaryAddressId { get; set; }

    [Reference]
    public CustomerAddress PrimaryAddress { get; set; }
}
```

::: info
Reference Attributes take precedence over naming conventions
:::

### Multiple Self References

The example below shows a customer with multiple `CustomerAddress` references which are able to be matched with
the `{PropertyReference}Id` naming convention, e.g:

```csharp
public class Customer
{
    [AutoIncrement]
    public int Id { get; set; }
    public string Name { get; set; }

    [References(typeof(CustomerAddress))]
    public int? HomeAddressId { get; set; }

    [References(typeof(CustomerAddress))]
    public int? WorkAddressId { get; set; }

    [Reference]
    public CustomerAddress HomeAddress { get; set; }

    [Reference]
    public CustomerAddress WorkAddress { get; set; }
}
```

Once defined, it can be saved and loaded via OrmLite's normal Reference and Select API's, e.g:

```csharp
var customer = new Customer
{
    Name = "The Customer",
    HomeAddress = new CustomerAddress {
        Address = "1 Home Street",
        Country = "US"
    },
    WorkAddress = new CustomerAddress {
        Address = "2 Work Road",
        Country = "UK"
    },
};

db.Save(customer, references:true);

var c = db.LoadSelect<Customer>(x => x.Name == "The Customer");
c.WorkAddress.Address.Print(); // 2 Work Road

var ukAddress = db.Single<CustomerAddress>(x => x.Country == "UK");
ukAddress.Address.Print();     // 2 Work Road
```

## Implicit Reference Conventions are applied by default

The implicit relationship above allows you to use any of these equivalent APIs to JOIN tables:

```csharp
q.Join<CustomerAddress>();
q.Join<Customer,CustomerAddress>();
q.Join<Customer,CustomerAddress>((cust,address) => cust.Id == address.CustomerId);
```

## Selecting multiple columns across joined tables

The `SelectMulti` API lets you select from multiple joined tables into a typed tuple

```csharp
var q = db.From<Customer>()
    .Join<Customer, CustomerAddress>()
    .Join<Customer, Order>()
    .Where(x => x.CreatedDate >= new DateTime(2016,01,01))
    .And<CustomerAddress>(x => x.Country == "Australia");

var results = db.SelectMulti<Customer, CustomerAddress, Order>(q);

foreach (var tuple in results)
{
    Customer customer = tuple.Item1;
    CustomerAddress custAddress = tuple.Item2;
    Order custOrder = tuple.Item3;
}
```

Thanks to Micro ORM's lightweight abstractions over ADO.NET that maps to clean POCOs, we can also use
OrmLite's embedded version of [Dapper's QueryMultiple](http://stackoverflow.com/a/37420341/85785):

```csharp
var q = db.From<Customer>()
    .Join<Customer, CustomerAddress>()
    .Join<Customer, Order>()
    .Select("*");

using (var multi = db.QueryMultiple(q.ToSelectStatement()))
{
    var results = multi.Read<Customer, CustomerAddress, Order, 
        Tuple<Customer,CustomerAddress,Order>>(Tuple.Create).ToList();

    foreach (var tuple in results)
    {
        Customer customer = tuple.Item1;
        CustomerAddress custAddress = tuple.Item2;
        Order custOrder = tuple.Item3;
    }
}
```

## SELECT DISTINCT in SelectMulti

[SelectMulti](typed-joins) APIs for populating
multiple tables now supports **SELECT DISTINCT** with:

```csharp
var tuples = db.SelectMulti<Customer, CustomerAddress>(q.SelectDistinct());
```

## Select data from multiple tables into a Custom POCO

Another implicit behaviour when selecting from a typed SqlExpression is that results are mapped to the
`Customer` POCO. To change this default we just need to explicitly specify what POCO it should map to instead:

```csharp
List<FullCustomerInfo> customers = db.Select<FullCustomerInfo>(
    db.From<Customer>().Join<CustomerAddress>());
```

Where `FullCustomerInfo` is any POCO that contains a combination of properties matching any of the joined
tables in the query.

The above example is also equivalent to the shorthand `db.Select<Into,From>()` API:

```csharp
var q = db.From<Customer>()
          .Join<CustomerAddress>();

var customers = db.Select<FullCustomerInfo,Customer>(q);
```

Rules for how results are mapped is simply each property on `FullCustomerInfo` is mapped to the first matching property in any of the tables in the order they were added to the SqlExpression.

The mapping also includes a fallback for referencing fully-qualified names in the format: `{TableName}{FieldName}` allowing you to reference ambiguous fields, e.g:

- `CustomerId` => **"Customer"."Id"**
- `OrderId` => **"Order"."Id"**
- `CustomerName` => **"Customer"."Name"**
- `OrderCost` => **"Order"."Cost"**


### SELECT JOIN examples

You can SELECT all fields for a table by returning the entire instance in the custom anonymous type, e.g:

```csharp
var q = db.From<Table>()
    .Join<JoinedTable>()
    .OrderBy(x => x.Id)
    .Select<Table, JoinedTable>((a, b) => new { a, b.TableId });

var rows = db.Select<CombinedResult>(q);
```

Which selects all columns from the primary `Table` as well as `TableId` from `JoinedTable`.

You can also specify SQL Aliases for ambiguous columns using anonymous properties, e.g:

```csharp
var q = db.From<Table>()
    .Join<JoinedTable>()
    .Select<Table, JoinedTable>((a, b) => new { a, JoinId = b.Id, JoinName = b.Name });
```

Which is roughly equivalent to:

    SELECT a.*, b.Id AS JoinId, b.Name AS JoinName

Where it selects all columns from the primary `Table` as well as `Id` and `Name` columns from `JoinedTable,` 
returning them in the `JoinId` and `JoinName` custom aliases.

Being able to select all columns works in other areas as well, e.g. you can **GROUP BY** all columns of 
a table with:

```csharp
var q = db.From<Table>()
    .GroupBy(x => new { x });
```

Which would return the same results as a **SELECT DISTINCT** on all columns of `Table`.


# Dynamic Result Sets
Source: https://docs.servicestack.net/ormlite/dynamic-result-sets

In addition to populating Typed POCOs, OrmLite has a number of flexible options for accessing dynamic resultsets with adhoc schemas:

## Dynamic Results Examples

```csharp

var aggregates = db.Select<List<object>>(
    db.From<Track>().Select("COUNT(*), MIN(Year), MAX(Year)")).First();

var keyValuePairs = db.Select<Dictionary<string, object>>(
    db.From<Track>().Select("COUNT(*) Total, MIN(Year) Min, MAX(Year)")).First();

var q = db.From<Track>().Select("COUNT(*) Total, MIN(Year) Min, MAX(Year) Max");

var customPoco = db.Select<Poco>(q).First();

var dynamicResult = db.Select<dynamic>(q).First();
long total = dynamicResult.Total;
long min = dynamicResult.Min;
long max = dynamicResult.Max;

var artistsWithTracksFrom93 = db.SelectMulti<Track,Artist>(db.From<Track>()
      .Join<Artist>()
      .Where(x => x.Year == 1993));

$"\nArtists with Tracks from 1993:".Print();
foreach (var tuple in artistsWithTracksFrom93)
{
    $"\nTrack/Artist: {new {track=tuple.Item1, artist=tuple.Item2}.Dump()}".Print();
}
```

## C# 7 Value Tuples

The C# 7 Value Tuple support enables a terse, clean and typed API for accessing the Dynamic Result Sets returned when using a custom Select expression:

```csharp
var query = db.From<Employee>()
    .Join<Department>()
    .OrderBy(e => e.Id)
    .Select<Employee, Department>(
        (e, d) => new { e.Id, e.LastName, d.Name });
 
var results = db.Select<(int id, string lastName, string deptName)>(query);
 
var row = results[i];
$"row: ${row.id}, ${row.lastName}, ${row.deptName}".Print();
```

Full Custom SQL Example:

```csharp
var results = db.SqlList<(int count, string min, string max, int sum)>(
    "SELECT COUNT(*), MIN(Word), MAX(Word), Sum(Total) FROM Table");
```

Partial Custom SQL Select Example:

```csharp
var query = db.From<Table>()
    .Select("COUNT(*), MIN(Word), MAX(Word), Sum(Total)");
 
var result = db.Single<(int count, string min, string max, int sum)>(query);
```

Same as above, but using Typed APIs:

```csharp
var result = db.Single<(int count, string min, string max, int sum)>(
    db.From<Table>()
        .Select(x => new {
            Count = Sql.Count("*"),
            Min = Sql.Min(x.Word),
            Max = Sql.Max(x.Word),
            Sum = Sql.Sum(x.Total)
        }));
```

There's also support for returning unstructured resultsets in `List<object>`, e.g:

```csharp
var results = db.Select<List<object>>(db.From<Poco>()
  .Select("COUNT(*), MIN(Id), MAX(Id)"));

results[0].PrintDump();
```

Output of objects in the returned `List<object>`:

```
[
    10,
    1,
    10
]
```

You can also Select `Dictionary<string,object>` to return a dictionary of column names mapped with their values, e.g:

```csharp
var results = db.Select<Dictionary<string,object>>(db.From<Poco>()
  .Select("COUNT(*) Total, MIN(Id) MinId, MAX(Id) MaxId"));

results[0].PrintDump();
```

Output of objects in the returned `Dictionary<string,object>`:

```
{
    Total: 10,
    MinId: 1,
    MaxId: 10
}
```

and can be used for API's returning a **Single** row result:

```csharp
var result = db.Single<List<object>>(db.From<Poco>()
  .Select("COUNT(*) Total, MIN(Id) MinId, MAX(Id) MaxId"));
```

or use `object` to fetch an unknown **Scalar** value:

```csharp
object result = db.Scalar<object>(db.From<Poco>().Select(x => x.Id));
```

## Selecting from multiple tables

You can also select data from multiple tables into
[dynamic result sets](dynamic-result-sets)
which provide [several Convenience APIs](http://stackoverflow.com/a/37443162/85785)
for accessing data from an unstructured queries.

Using dynamic:

```csharp
var q = db.From<Employee>()
    .Join<Department>()
    .Select<Employee, Department>((e, d) => new { e.FirstName, d.Name });
    
List<dynamic> results = db.Select<dynamic>(q);
foreach (dynamic result in results)
{
    string firstName = result.FirstName;
    string deptName = result.Name;
}
```

Dictionary of Objects:

```csharp
List<Dictionary<string,object>> rows = db.Select<Dictionary<string,object>>(q);
```

List of Objects:

```csharp
List<List<object>> rows = db.Select<Dictionary<string,object>>(q);
```

Custom Key/Value Dictionary:

```csharp
Dictionary<string,string> rows = db.Dictionary<string,string>(q);
```


# Database Transactions
Source: https://docs.servicestack.net/ormlite/transactions

As a Micro ORM OrmLite has direct access to ADO.NET's `IDbConnection` classes, where starting a transaction can be done with 
`OpenTransaction` to create a new transaction and attach it to its containing executed ADO.NET commands:

```csharp
using (IDbTransaction dbTrans = db.OpenTransaction())
{
    try
    {
        db.Insert(new ShipperType { Name = "Trains" });
        db.Insert(new ShipperType { Name = "Planes" });
    
        dbTrans.Commit();
    }
    catch (Exception e)
    {
        dbTrans.Rollback();
    }
}
```

## Custom Isolation Level

Which also supports custom Isolation Levels:

```csharp
using (IDbTransaction dbTrans = db.OpenTransaction(IsolationLevel.ReadCommitted))
{
    db.Insert(new ShipperType { Name = "Automobiles" });
}
```

## Transaction SavePoints

A savepoint is a special mark inside a transaction that allows all commands that are executed after it was created
to be rolled back, restoring the transaction state to what it was at the time of the savepoint.

Transaction SavePoints are available for all [supported RDBMS](https://docs.servicestack.net/ormlite/installation)
with the `SavePoint()` API which will let you Create and `Rollback()` to a SavePoint or `Release()` its resources, e.g:

```csharp
// Sync
using (var trans = db.OpenTransaction())
{
    try
    {
        db.Insert(new Person { Id = 2, Name = "John" });

        var firstSavePoint = trans.SavePoint("FirstSavePoint");

        db.UpdateOnly(() => new Person { Name = "Jane" }, where: x => x.Id == 1);

        firstSavePoint.Rollback();

        var secondSavePoint = trans.SavePoint("SecondSavePoint");

        db.UpdateOnly(() => new Person { Name = "Jack" }, where: x => x.Id == 1);

        secondSavePoint.Release();

        db.Insert(new Person { Id = 3, Name = "Diane" });

        trans.Commit();
    }
    catch (Exception e)
    {
        trans.Rollback();
    }
}
```

Equivalent async versions are also available with `SavePointAsync()` to create a Save Point, `RollbackAsync()` and `ReleaseAsync()`
to Rollback and Release Save Points, e.g:

```csharp
// Async
using (var trans = db.OpenTransaction())
{
    try
    {
        await db.InsertAsync(new Person { Id = 2, Name = "John" });

        var firstSavePoint = await trans.SavePointAsync("FirstSavePoint");

        await db.UpdateOnlyAsync(() => new Person { Name = "Jane" }, where: x => x.Id == 1);

        await firstSavePoint.RollbackAsync();

        var secondSavePoint = await trans.SavePointAsync("SecondSavePoint");

        await db.UpdateOnlyAsync(() => new Person { Name = "Jack" }, where: x => x.Id == 1);

        await secondSavePoint.ReleaseAsync();

        await db.InsertAsync(new Person { Id = 3, Name = "Diane" });

        trans.Commit();
    }
    catch (Exception e)
    {
        trans.Rollback();
    }
}
```


# OrmLite Type Converters
Source: https://docs.servicestack.net/ormlite/type-converters

OrmLite has become a lot more customizable and extensible thanks to the internal redesign decoupling all
custom logic for handling different Field Types into individual Type Converters.

This use of individual decoupled Type Converters makes it possible to enhance or entirely replace how .NET Types are handled and can also be extended to support new Types it has no knowledge about, a feature taken advantage of by the [SQL Server Types](/ormlite/sql-server-features#sql-server-types) support.

![OrmLite Converters](https://raw.githubusercontent.com/ServiceStack/Assets/master/img/release-notes/ormlite-converters.png)

## Encapsulated, reusable, customizable and debuggable

Converters allow for great re-use as common functionality to support each type is maintained in the common
[ServiceStack.OrmLite/Converters](https://github.com/ServiceStack/ServiceStack/tree/main/ServiceStack.OrmLite/src/ServiceStack.OrmLite/Converters)
whilst any RDBMS-specific functionality can inherit the common converters and provide any specialization
required to support that type. E.g. SQL Server specific converters are maintained in
[ServiceStack.OrmLite.SqlServer/Converters](https://github.com/ServiceStack/ServiceStack/tree/main/ServiceStack.OrmLite/src/ServiceStack.OrmLite.SqlServer/Converters) with each converter inheriting shared functionality and only adding custom logic required to support that
Type in Sql Server.

## Creating Converters

Converters also provide good encapsulation as everything relating to handling the field type is contained within
a single class definition. A Converter is any class implementing
[IOrmLiteConverter](https://github.com/ServiceStack/ServiceStack/blob/main/ServiceStack.OrmLite/src/ServiceStack.OrmLite/IOrmLiteConverter.cs)
although, it's instead recommended inheriting from the `OrmLiteConverter` abstract class which allows
only the minimum APIs needing to be overridden, namely the `ColumnDefinition`
used when creating the Table definition and the ADO.NET `DbType` it should use in parameterized queries.
An example of this is in
[GuidConverter](https://github.com/ServiceStack/ServiceStack/blob/main/ServiceStack.OrmLite/src/ServiceStack.OrmLite/Converters/GuidConverter.cs):

```csharp
public class GuidConverter : OrmLiteConverter
{
    public override string ColumnDefinition => "GUID";
    public override DbType DbType => DbType.Guid;

    public override object FromDbValue(Type fieldType, object value)
    {
        if (value is string s)
            return Guid.Parse(s);
        
        return base.FromDbValue(fieldType, value);
    }
}
```

For this to work in SQL Server the `ColumnDefinition` should instead be **UniqueIdentifier** which is also
what it needs to be cast to, to be able to query Guid's within an SQL Statement.
Therefore, Guids require a custom
[SqlServerGuidConverter](https://github.com/ServiceStack/ServiceStack/blob/main/ServiceStack.OrmLite/src/ServiceStack.OrmLite.SqlServer/Converters/SqlServerGuidConverter.cs)
to support Guids in SQL Server which looks like:

```csharp
public class SqlServerGuidConverter : GuidConverter
{
    public override string ColumnDefinition => "UniqueIdentifier";

    public override string ToQuotedString(Type fieldType, object value)
    {
        var guidValue = (Guid)value;
        return $"CAST('{guidValue}' AS UNIQUEIDENTIFIER)";
    }
}
```

## Registering Converters

To get OrmLite to use this new Custom Converter for SQL Server, the `SqlServerOrmLiteDialectProvider` just
[registers it in its constructor](https://github.com/ServiceStack/ServiceStack/blob/e764d49a1a0c760bec2c5cb5714a03ea8c39af99/ServiceStack.OrmLite/src/ServiceStack.OrmLite.SqlServer/SqlServerOrmLiteDialectProvider.cs#L50):

```csharp
base.RegisterConverter<Guid>(new SqlServerGuidConverter());
```

i.e. overriding the pre-registered `GuidConverter` to enable its extended functionality in SQL Server.

You'll also use the same `RegisterConverter<T>()` API to register your own Custom Guid Coverter on the RDBMS
provider you want it to apply to, e.g for SQL Server:

```csharp
SqlServerDialect.Provider.RegisterConverter<Guid>(new MyCustomGuidConverter());
```

## Resolving Converters

If needed, it can be later retrieved with:

```csharp
IOrmLiteConverter converter = SqlServerDialect.Provider.GetConverter<Guid>();
var myGuidConverter = (MyCustomGuidConverter)converter;
```

## Debugging Converters

Custom Converters also makes it easier to debug Type issues where if you want to see what value gets retrieved
from the database, you can override and add a breakpoint on the base method letting you inspect the value
returned from the ADO.NET Data Reader:

```csharp
public class MyCustomGuidConverter : SqlServerGuidConverter
{
    public override object FromDbValue(Type fieldType, object value)
    {
        return base.FromDbValue(fieldType, value); //add breakpoint
    }
}
```

## Enhancing an existing Converter

An example of when you'd want to do this is if you wanted to use the `Guid` property in your POCO's on
legacy tables which stored Guids in `VARCHAR` columns, in which case you can also add support for converting
the returned strings back into Guid's with:

```csharp
public class MyCustomGuidConverter : SqlServerGuidConverter
{
    public override object FromDbValue(Type fieldType, object value)
    {
        var strValue = value as string; 
        return strValue != null
            ? new Guid(strValue);
            : base.FromDbValue(fieldType, value); 
    }
}
```

## SQL Server TIME Converter

Another popular Use Case now enabled with Converters is being able to override built-in functionality based on preference. E.g. by default TimeSpans are stored in the database as Ticks in a `BIGINT` column since it's the most reliable way to retain the same TimeSpan value uniformly across all RDBMS's.

E.g. SQL Server's **TIME** data type can't store Times greater than 24 hours or with less precision than **3ms**.
But if using a **TIME** column was preferred it can now be enabled by registering to use the new
[SqlServerTimeConverter](https://github.com/ServiceStack/ServiceStack.OrmLite/blob/master/src/ServiceStack.OrmLite.SqlServer/Converters/SqlServerTimeConverter.cs)
instead:

```csharp
SqlServerDialect.Provider.RegisterConverter<TimeSpan>(
    new SqlServerTimeConverter { 
       Precision = 7 
    });
```

## Customizable Field Definitions

Another benefit is they allow for easy customization as seen with `Precision` property which will now
create tables using the `TIME(7)` Column definition for TimeSpan properties.

## Compact Guid Converters

For RDBMS's that don't have a native `Guid` type like Oracle or Firebird, you had an option to choose whether
you wanted to save them as text for better readability (default) or in a more efficient compact binary format.
Previously this preference was maintained in a boolean flag along with multiple Guid implementations hard-coded
at different entry points within each DialectProvider. This complexity has now been removed, now to store guids
in a compact binary format you'll instead register the preferred Converter implementation, e.g:

```csharp
FirebirdDialect.Provider.RegisterConverter<Guid>(
    new FirebirdCompactGuidConverter());
```

## String Converters

To customize the behavior of how strings are stored you can change them directly on the `StringConverter`, e.g:

```csharp
StringConverter converter = OrmLiteConfig.DialectProvider.GetStringConverter();
converter.UseUnicode = true;
converter.StringLength = 100;
```

Which will change the default column definitions for strings to use `NVARCHAR(100)` for RDBMS's that support
Unicode or `VARCHAR(100)` for those that don't.

The `GetStringConverter()` API is just an extension method wrapping the generic `GetConverter()` API to return
a concrete type:

```csharp
public static StringConverter GetStringConverter(this IOrmLiteDialectProvider d)
{
    return (StringConverter)d.GetConverter(typeof(string));
}
```

## DateTime Converters

### Specify the DateKind in DateTimes

It's now much simpler and requires less effort to implement new features that maintain the same behavior
across all supported RDBMS thanks to better cohesion, re-use and reduced internal state. One new feature
we've added as a result is the new `DateStyle` customization on `DateTimeConverter` which lets you change how
Dates are persisted and populated, e.g:

```csharp
DateTimeConverter dates = OrmLiteConfig.DialectProvider.GetDateTimeConverter();
dates.DateStyle = DateTimeKind.Local;
```

Will save `DateTime` in the database and populate them back on data models as LocalTime.
This is also available for Utc:

```csharp
dates.DateStyle = DateTimeKind.Utc;
```

Default is `Unspecified` which doesn't do any conversions and just uses the DateTime returned by the ADO.NET provider.
Examples of the behavior of the different DateStyle's is available in
[DateTimeTests](https://github.com/ServiceStack/ServiceStack/blob/main/ServiceStack.OrmLite/tests/ServiceStack.OrmLite.Tests/DateTimeTests.cs).

## Noda Time

SQL Server Converter for [NodaTime](http://nodatime.org/) `Instant` Type in `DATETIMEOFFSET` with TimeZone:

```csharp
public class SqlServerInstantConverter : OrmLiteConverter
{
    public override string ColumnDefinition => "DATETIMEOFFSET";

    public override DbType DbType => DbType.DateTimeOffset;

    public override object ToDbValue(Type fieldType, object value)
    {
        var instantValue = (Instant)value;
        return instantValue.ToDateTimeOffset();
    }

    public override object FromDbValue(Type fieldType, object value)
    {
        return Instant.FromDateTimeOffset((DateTimeOffset)value);
    }
}

SqlServerDialect.Provider.RegisterConverter<Instant>(new SqlServerInstantConverter());
```

In `DATETIME2` in UTC:

```csharp
public class SqlServerInstantDateTimeConverter : OrmLiteConverter
{
    public override string ColumnDefinition => "DATETIME2";

    public override DbType DbType => DbType.DateTime;

    public override object ToDbValue(Type fieldType, object value)
    {
        var instantValue = (Instant) value;
        return instantValue.ToDateTimeUtc();
    }

    public override object FromDbValue(Type fieldType, object value)
    {
        var dateTime = DateTime.SpecifyKind((DateTime)value, DateTimeKind.Utc);
        return Instant.FromDateTimeUtc(dateTime);
    }
}

SqlServerDialect.Provider.RegisterConverter<Instant>(new SqlServerInstantDateTimeConverter());
```

## SQL Server Types

See [SQL Server Types](sql-server-features.md#sql-server-types) for how to enable support for SQL Server-specific `SqlGeography`, `SqlGeometry` and `SqlHierarchyId` Types.


# OrmLite Utils
Source: https://docs.servicestack.net/ormlite/ormlite-utils

The `Sql.In()` API supports nesting and combining of multiple Typed SQL Expressions together
in a single SQL Query, e.g:

```csharp
var usaCustomerIds = db.From<Customer>(c => c.Country == "USA").Select(c => c.Id);
var usaCustomerOrders = db.Select(db.From<Order>()
    .Where(x => Sql.In(x.CustomerId, usaCustomerIds)));
``` 

By using `Sql.In` from within a `SqlExpression<T>`, multiple values can be checked for a match in your query.

```csharp
db.Select<Author>(x => Sql.In(x.City, "London", "Madrid", "Berlin"));

var cities = new[] { "London", "Madrid", "Berlin" };
db.Select<Author>(x => Sql.In(x.City, cities));
```

## Parametrized IN Values

OrmLite also supports providing collection of values which is automatically split into multiple DB parameters to simplify executing parameterized SQL with multiple IN Values, e.g:

```csharp
var ids = new[]{ 1, 2, 3};
var results = db.Select<Table>("Id in (@ids)", new { ids });

var names = new List<string>{ "foo", "bar", "qux" };
var results = db.SqlList<Table>("SELECT * FROM Table WHERE Name IN (@names)", new { names });
```

## Spread Util

The `SqlSpread()` API is useful to generate an escaped list of parameterized values for use in SQL `IN()` statements and SQL functions:

```csharp
var dialect = db.Dialect();
dialect.SqlSpread(1, 2, 3);         //= 1,2,3
dialect.SqlSpread("A", "B", "C");   //= 'A','B','C'
dialect.SqlSpread("A'B", "C\"D");   //= 'A''B','C\"D'
```

## Lazy Queries

APIs ending with `Lazy` yield an IEnumerable sequence letting you stream the results without having to map the entire resultset into a disconnected List of POCO's first, e.g:

```csharp
var lazyQuery = db.SelectLazy<Person>("Age > @age", new { age = 40 });
// Iterate over a lazy sequence 
foreach (var person in lazyQuery) {
   //...  
}
```

## Save Methods

`Save` and `SaveAll` will Insert if no record with **Id** exists, otherwise it Updates.

`Save` will populate any `[AutoIncrement]` or `[AutoId]` Primary Keys, e.g:

```csharp
db.Save(item);
item.Id // RDBMS populated Auto Id 
```

Alternatively you can also manually Select and Retrieve the Inserted RDBMS Auto Id in a single query with `Insert` APIs by specifying `selectIdentity:true`:

```csharp
item.Id = db.Insert(item, selectIdentity:true);
```

## Other examples

```csharp
var topVIPs = db.WhereLazy<Person>(new { Age = 27 }).Where(p => IsVip(p)).Take(5)
```

## Other Notes

- All **Insert**, **Update**, and **Delete** methods take multiple params, while `InsertAll`, `UpdateAll` and `DeleteAll` take IEnumerables.
- Methods containing the word **Each** return an `IEnumerable<T>` and are lazily loaded (i.e. non-buffered).


# OrmLite Ensure APIs
Source: https://docs.servicestack.net/ormlite/ensure-apis

The `Ensure()` API on OrmLite's typed `SqlExpression<T>` can be used to ensure that a condition is always applied irrespective
of other conditions, e.g:

## Typed API

```csharp
var q = db.From<Rockstar>();
q.Ensure(x => x.Id == 1); //always applied

//...
q.Where(x => x.Age == 27);
q.Or(x => x.LivingStatus == LivingStatus.Dead);

var rows = db.Select(q);
```

## Custom Parameterized SQL Expression

Custom SQL Ensure parameterized expressions:

```csharp
 q.Ensure("Id = {0}", 1); 
```

## Multiple Ensure expressions

```csharp
var q = db
    .From<Rockstar>()
    .Join<RockstarAlbum>((r,a) => r.Id == a.RockstarId);

q.Ensure<Rockstar,RockstarAlbum>((r,a) => a.Name == "Nevermind" && r.Id == a.RockstarId);

q.Where(x => x.Age == 27)
 .Or(x => x.LivingStatus == LivingStatus.Dead);

q.Ensure(x => x.Id == 3);

var rows = db.Select(q);
```

These APIs are useful for mandatory filters like "Soft Deletes" and Multitenant records.


# OrmLite Logging and Introspection
Source: https://docs.servicestack.net/ormlite/introspection

### SQL Profiler

The easiest way to view your App's generated SQL is by enabling the [Admin Profiling UI](/admin-ui-features#request-logging-profiling) where it's built-in [SQL Profiling](/admin-ui-profiling#sql-profiling) will show generated queries in context with your other App events:

<a href="/admin-ui-profiling#sql-profiling" class="block flex justify-center items-center">
    <img class="max-w-screen-md" src="/img/pages/admin-ui/profiling-CreateBooking-CommandAfter.png">
</a>

### Logging Executed SQL

Alternatively you can see what queries OrmLite generates by configuring it to use a **debug** enabled logger, e.g:

```csharp
LogManager.LogFactory = new ConsoleLogFactory(debugEnabled:true);
```

Where it will log the generated SQL and Params OrmLite executes to the Console.

## BeforeExecFilter and AfterExecFilter filters

An alternative to debug logging which can easily get lost in the noisy stream of other debug messages is to use the `BeforeExecFilter` and `AfterExecFilter` filters where you can inspect executed commands with a custom lambda expression before and after each query is executed. So if one of your a queries are failing you can put a breakpoint in `BeforeExecFilter` to inspect the populated `IDbCommand` object before it's executed or use the `.GetDebugString()` extension method for an easy way to print the Generated SQL and DB Params to the Console:

```csharp
OrmLiteConfig.BeforeExecFilter = dbCmd => Console.WriteLine(dbCmd.GetDebugString());

//OrmLiteConfig.AfterExecFilter = dbCmd => Console.WriteLine(dbCmd.GetDebugString());
```

## Output Generated SQL

You can use `OrmLiteUtils.PrintSql()` for the common debugging task of viewing the generated SQL OrmLite executes:

```csharp
OrmLiteUtils.PrintSql();
```

To later disable logging use:

```csharp
OrmLiteUtils.UnPrintSql();
```

## Exec, Result and String Filters

OrmLite's core Exec filters makes it possible to inject your own behavior, tracing, profiling, etc.

It's useful in situations like wanting to use SqlServer in production but use an `in-memory` Sqlite database in tests and being able to emulate any missing SQL Server Stored Procedures in code:

```csharp
public class MockStoredProcExecFilter : OrmLiteExecFilter
{
    public override T Exec<T>(IDbConnection dbConn, Func<IDbCommand, T> filter)
    {
        try
        {
            return base.Exec(dbConn, filter);
        }
        catch (Exception ex)
        {
            if (dbConn.GetLastSql() == "exec sp_name @firstName, @age")
                return (T)(object)new Person { FirstName = "Mocked" };
            throw;
        }
    }
}

OrmLiteConfig.ExecFilter = new MockStoredProcExecFilter();

using (var db = OpenDbConnection())
{
    var person = db.SqlScalar<Person>("exec sp_name @firstName, @age",
        new { firstName = "aName", age = 1 });

    person.FirstName.Print(); //Mocked
}
```

## CaptureSqlFilter

Result filters makes it trivial to implement the `CaptureSqlFilter` which allows you to capture SQL Statements without running them.
[CaptureSqlFilter](https://github.com/ServiceStack/ServiceStack.OrmLite/blob/4c56bde197d07cfc78a80be06dd557732ecf68fa/src/ServiceStack.OrmLite/OrmLiteResultsFilter.cs#L321)
is just a simple Results Filter which can be used to quickly found out what SQL your DB calls generate by surrounding DB access in a using scope, e.g:

```csharp
using (var captured = new CaptureSqlFilter())
using (var db = OpenDbConnection())
{
    db.Where<Person>(new { Age = 27 });

    captured.SqlStatements[0].PrintDump();
}
```

Emits the Executed SQL along with any DB Parameters:

```
{
    Sql: "SELECT ""Id"", ""FirstName"", ""LastName"", ""Age"" FROM ""Person"" WHERE ""Age"" = @Age",
    Parameters: 
    {
        Age: 27
    }
}
```

## Replay Exec Filter

Or if you want to do things like executing each operation multiple times, e.g:

```csharp
public class ReplayOrmLiteExecFilter : OrmLiteExecFilter
{
    public int ReplayTimes { get; set; }

    public override T Exec<T>(IDbConnection dbConn, Func<IDbCommand, T> filter)
    {
        var holdProvider = OrmLiteConfig.DialectProvider;
        var dbCmd = CreateCommand(dbConn);
        try
        {
            var ret = default(T);
            for (var i = 0; i < ReplayTimes; i++)
            {
                ret = filter(dbCmd);
            }
            return ret;
        }
        finally
        {
            DisposeCommand(dbCmd);
            OrmLiteConfig.DialectProvider = holdProvider;
        }
    }
}

OrmLiteConfig.ExecFilter = new ReplayOrmLiteExecFilter { ReplayTimes = 3 };

using (var db = OpenDbConnection())
{
    db.DropAndCreateTable<PocoTable>();
    db.Insert(new PocoTable { Name = "Multiplicity" });

    var rowsInserted = db.Count<PocoTable>(x => x.Name == "Multiplicity"); //3
}
```


## Mockable extension methods

The Result Filters also lets you easily mock results and avoid hitting the database, typically useful in Unit Testing Services to mock OrmLite API's directly instead of using a repository, e.g:

```csharp
using (new OrmLiteResultsFilter {
    PrintSql = true,
    SingleResult = new Person { 
      Id = 1, FirstName = "Mocked", LastName = "Person", Age = 100 
    },
})
{
    db.Single<Person>(x => x.Age == 42).FirstName // Mocked
    db.Single(db.From<Person>().Where(x => x.Age == 42)).FirstName // Mocked
    db.Single<Person>(new { Age = 42 }).FirstName // Mocked
    db.Single<Person>("Age = @age", new { age = 42 }).FirstName // Mocked
}
```

More examples showing how to mock different APIs including support for nesting available in [MockAllApiTests.cs](https://github.com/ServiceStack/ServiceStack/blob/main/ServiceStack.OrmLite/tests/ServiceStack.OrmLite.Tests/MockAllApiTests.cs)

## String Filter

There's also a specific filter for strings available which allows you to apply custom sanitization on String fields, e.g. you can ensure all strings are right trimmed with:

```csharp
OrmLiteConfig.StringFilter = s => s.TrimEnd();

db.Insert(new Poco { Name = "Value with trailing   " });
db.Select<Poco>().First().Name // "Value with trailing"
```


# Pluggable Complex Type Serializers
Source: https://docs.servicestack.net/ormlite/complex-type-serializers

Pluggable serialization lets you specify different serialization strategies of Complex Types for each available RDBMS provider, e.g:

## Defaults

```csharp
//ServiceStack's JSON and JSV Format
SqliteDialect.Provider.StringSerializer = new JsvStringSerializer();       
PostgreSqlDialect.Provider.StringSerializer = new JsonStringSerializer();

//.NET's XML and JSON DataContract serializers
SqlServerDialect.Provider.StringSerializer = new DataContractSerializer();
MySqlDialect.Provider.StringSerializer = new JsonDataContractSerializer();

//.NET XmlSerializer
OracleDialect.Provider.StringSerializer = new XmlSerializableSerializer();
```
You can also provide a custom serialization strategy by implementing
[IStringSerializer](https://github.com/ServiceStack/ServiceStack/blob/main/ServiceStack.Text/src/ServiceStack.Text/IStringSerializer.cs).

By default, all dialects use the existing `JsvStringSerializer`, except for PostgreSQL which due to its built-in support for JSON, uses the JSON format by default.


# OrmLite Filters
Source: https://docs.servicestack.net/ormlite/filters

Similar to interceptors in some heavy ORMs, Insert and Update filters get fired just before any **INSERT** or **UPDATE** operation using OrmLite's typed API's (i.e. not dynamic SQL or partial updates using anon types). This functionality can be used for easily auto-maintaining Audit information for your POCO data models, e.g:

```csharp
public interface IAudit 
{
    DateTime CreatedDate { get; set; }
    DateTime ModifiedDate { get; set; }
    string ModifiedBy { get; set; }
}

OrmLiteConfig.InsertFilter = (dbCmd, row) => {
    if (row is IAudit auditRow)
        auditRow.CreatedDate = auditRow.ModifiedDate = DateTime.UtcNow;
};

OrmLiteConfig.UpdateFilter = (dbCmd, row) => {
    if (row is IAudit auditRow)
        auditRow.ModifiedDate = DateTime.UtcNow;
};
```

Which will ensure that the `CreatedDate` and `ModifiedDate` fields are populated on every insert and update.

## Validation Example

The filters can also be used for validation where throwing an exception will prevent the operation and bubble the exception, e.g:

```csharp
OrmLiteConfig.InsertFilter = OrmLiteConfig.UpdateFilter = (dbCmd, row) => {
    if (row is IAudit auditRow && auditRow.ModifiedBy == null)
        throw new ArgumentNullException("ModifiedBy");
};

try
{
    db.Insert(new AuditTable());
}
catch (ArgumentNullException) {
   //throws ArgumentNullException
}

db.Insert(new AuditTable { ModifiedBy = "Me!" }); //succeeds
```


# Custom SQL
Source: https://docs.servicestack.net/ormlite/custom-sql

OrmLite's Expression support satisfies the most common RDBMS queries with a strong-typed API.
For more complex queries you can easily fall back to raw SQL where the Custom SQL APIs
let you map custom SqlExpressions into different responses:

```csharp
var q = db.From<Person>()
          .Where(x => x.Age < 50)
          .Select("*");
List<Person> results = db.SqlList<Person>(q);

List<Person> results = db.SqlList<Person>(
    "SELECT * FROM Person WHERE Age < @age", new { age=50});

List<string> results = db.SqlColumn<string>(db.From<Person>().Select(x => x.LastName));
List<string> results = db.SqlColumn<string>("SELECT LastName FROM Person");

HashSet<int> results = db.ColumnDistinct<int>(db.From<Person>().Select(x => x.Age));
HashSet<int> results = db.ColumnDistinct<int>("SELECT Age FROM Person");

var q = db.From<Person>()
          .Where(x => x.Age < 50)
          .Select(Sql.Count("*"));
int result = db.SqlScalar<int>(q);
int result = db.SqlScalar<int>("SELECT COUNT(*) FROM Person WHERE Age < 50");
```

## Custom SQL with Typed SqlExpression

Using a typed SQL Expression with a mix of typed an custom SQL Expressions:

```csharp
var q = db.From<Person>();
q.Where("Age < {0}", 50);
List<Person> results = db.Select(q)

var q = db.From<Person>().Where("Age < {0}", 50);
string sql = q.ToSelectStatement();
List<Person> results = db.Select(sql, q.Params);
```

:::tip
If your custom SQL Expression fails because it contains raw SQL with comments or write commands you can use `Unsafe*` APIs to by-pass SQL Validation, e.g. `q.UnsafeWhere(rawSql)`
:::

## Custom Selects

```csharp
public record CustomPoco(int Year, string Max);

var upperNamesWithA = db.SqlColumn<string>(
    "SELECT upper(Name) FROM Track WHERE instr(Name,'a') > 0");

var meta = db.SqlList<CustomPoco>(
    "SELECT DISTINCT Year % 10 as Year, hex(Year % 10) as Hex FROM Track");

db.ExecuteSql("ALTER TABLE Track ADD Rand INT default 0");
db.ExecuteSql("UPDATE Track SET Rand = abs(random()) % 1000");

var trackRandValues = db.Dictionary<string,int>("SELECT Name, Rand FROM Track");

var maxRand = db.SqlScalar<int>("SELECT MAX(Rand) FROM Track");
```

## Custom Insert and Updates

```csharp
Db.ExecuteSql("INSERT INTO page_stats (ref_id, fav_count) VALUES (@refId, @favCount)",
              new { refId, favCount })

//Async:
Db.ExecuteSqlAsync("UPDATE page_stats SET view_count = view_count + 1 WHERE id = @id", new { id })
```

## INSERT INTO SELECT

You can use OrmLite's Typed `SqlExpression` to create a subselect expression that you can use to create and execute a
typed **INSERT INTO SELECT** `SqlExpression` with:

```csharp
var q = db.From<User>()
    .Where(x => x.UserName == "UserName")
    .Select(x => new {
        x.UserName, 
        x.Email, 
        GivenName = x.FirstName, 
        Surname = x.LastName, 
        FullName = x.FirstName + " " + x.LastName
    });

var id = db.InsertIntoSelect<CustomUser>(q)
```

## Foreign Key attribute for referential actions on Update/Deletes

Creating a foreign key in OrmLite can be done by adding `[References(typeof(ForeignKeyTable))]` on the relation property,
which will result in OrmLite creating the Foreign Key relationship when it creates the DB table with `db.CreateTable<Poco>`.

Additional fine-grain options and behaviour are available in the `[ForeignKey]` attribute which will let you specify the desired behaviour when deleting or updating related rows in Foreign Key tables.

An example of a table with the different available options:

```csharp
public class TableWithAllCascadeOptions
{
	[AutoIncrement] public int Id { get; set; }
	
	[References(typeof(ForeignKeyTable1))]
	public int SimpleForeignKey { get; set; }
	
	[ForeignKey(typeof(ForeignKeyTable2), OnDelete = "CASCADE", OnUpdate = "CASCADE")]
	public int? CascadeOnUpdateOrDelete { get; set; }
	
	[ForeignKey(typeof(ForeignKeyTable3), OnDelete = "NO ACTION")]
	public int? NoActionOnCascade { get; set; }
	
	[Default(typeof(int), "17")]
	[ForeignKey(typeof(ForeignKeyTable4), OnDelete = "SET DEFAULT")]
	public int SetToDefaultValueOnDelete { get; set; }
	
	[ForeignKey(typeof(ForeignKeyTable5), OnDelete = "SET NULL")]
	public int? SetToNullOnDelete { get; set; }
}
```

## System Variables and Default Values

To provide richer support for non-standard default values, each RDBMS Dialect Provider contains a
`OrmLiteDialectProvider.Variables` placeholder dictionary for storing common, but non-standard RDBMS functionality.
We can use this to define non-standard default values, in a declarative way, that works across all supported RDBMS's
like automatically populating a column with the RDBMS UTC Date when Inserted with a `default(T)` Value:

```csharp
public class Poco
{
    [Default(OrmLiteVariables.SystemUtc)]  //= {SYSTEM_UTC}
    public DateTime CreatedTimeUtc { get; set; }
}
```

OrmLite variables need to be surrounded with `{}` braces to identify that it's a placeholder variable, e.g `{SYSTEM_UTC}`.

The [ForeignKeyTests](https://github.com/ServiceStack/ServiceStack/blob/main/ServiceStack.OrmLite/tests/ServiceStack.OrmLite.Tests/ForeignKeyAttributeTests.cs)
show the resulting behaviour with each of these configurations in more detail.

::: info
Note: Only supported on RDBMS's with foreign key/referential action support, e.g.
[Sql Server](http://msdn.microsoft.com/en-us/library/ms174979.aspx),
[PostgreSQL](http://www.postgresql.org/docs/9.1/static/ddl-constraints.html),
[MySQL](http://dev.mysql.com/doc/refman/5.5/en/innodb-foreign-key-constraints.html). Otherwise they're ignored.
:::


## Custom SQL using PostgreSQL Arrays

The `PgSql.Array()` provides a typed API for generating [PostgreSQL Array Expressions](https://www.postgresql.org/docs/current/arrays.html), e.g:

```csharp
PgSql.Array(1,2,3)     //= ARRAY[1,2,3]
var strings = new[]{ "A","B","C" };
PgSql.Array(strings)   //= ARRAY['A','B','C']
```

Which you can safely use in Custom SQL Expressions that use PostgreSQL's native ARRAY support:

```csharp
q.And($"{PgSql.Array(anyTechnologyIds)} && technology_ids")
q.And($"{PgSql.Array(labelSlugs)} && labels");
```

If you want and empty collection to return `null` instead of an empty `ARRAY[]` you can use the `nullIfEmpty` overload:

```csharp
PgSql.Array(new string[0], nullIfEmpty:true)      //= null
PgSql.Array(new[]{"A","B","C"}, nullIfEmpty:true) //= ARRAY['A','B','C']
```


# Customized SQL Features
Source: https://docs.servicestack.net/ormlite/customized-sql-features

A number of new hooks are available to provide more flexibility when creating and dropping your RDBMS tables.

## CustomSelect Attribute

The `[CustomSelect]` can be used to define properties you want populated from a Custom SQL Function or
Expression instead of a normal persisted column, e.g:

```csharp
public class Block
{
    public int Id { get; set; }
    public int Width { get; set; }
    public int Height { get; set; }

    [CustomSelect("Width * Height")]
    public int Area { get; set; }

    [Default(OrmLiteVariables.SystemUtc)]
    public DateTime CreatedDate { get; set; }

    [CustomSelect("FORMAT(CreatedDate, 'yyyy-MM-dd')")]
    public string DateFormat { get; set; }
}

db.Insert(new Block { Id = 1, Width = 10, Height = 5 });

var block = db.SingleById<Block>(1);

block.Area.Print(); //= 50

block.DateFormat.Print(); //= 2016-06-08 (SQL Server)
```

## Order by dynamic expressions

The `[CustomSelect]` attribute can be used to populate a property with a dynamic SQL Expression instead of an existing column, e.g:

```csharp
public class FeatureRequest
{
    public int Id { get; set; }
    public int Up { get; set; }
    public int Down { get; set; }

    [CustomSelect("1 + Up - Down")]
    public int Points { get; set; }
}
```

You can also order by the SQL Expression by referencing the property as you would a normal column. By extension this feature now also works in AutoQuery where you can [select it in a partial result set](/autoquery/rdbms#custom-fields) and order the results by using its property name, e.g:

```
/features?fields=id,points&orderBy=points
```

## Custom SQL Fragments

The `Sql.Custom()` API lets you use raw SQL Fragments in Custom `.Select()` expressions, e.g:

```csharp
var q = db.From<Table>()
    .Select(x => new {
        FirstName = x.FirstName,
        LastName = x.LastName,
        Initials = Sql.Custom("CONCAT(LEFT(FirstName,1), LEFT(LastName,1))")
    });
```

## Custom Field Declarations

The `[CustomField]` attribute can be used for specifying custom field declarations in the generated Create table DDL statements, e.g:

```csharp
public class PocoTable
{
    public int Id { get; set; }

    [CustomField("CHAR(20)")]
    public string CharColumn { get; set; }

    [CustomField("DECIMAL(18,4)")]
    public decimal? DecimalColumn { get; set; }

    [CustomField(OrmLiteVariables.MaxText)]        //= {MAX_TEXT}
    public string MaxText { get; set; }

    [CustomField(OrmLiteVariables.MaxTextUnicode)] //= {NMAX_TEXT}
    public string MaxUnicodeText { get; set; }
}

db.CreateTable<PocoTable>(); 
```

Generates and executes the following SQL in SQL Server:

```sql
CREATE TABLE "PocoTable" 
(
  "Id" INTEGER PRIMARY KEY, 
  "CharColumn" CHAR(20) NULL, 
  "DecimalColumn" DECIMAL(18,4) NULL, 
  "MaxText" VARCHAR(MAX) NULL, 
  "MaxUnicodeText" NVARCHAR(MAX) NULL 
); 
```

::: info
OrmLite replaces any variable placeholders with the value in each RDBMS DialectProvider's `Variables` Dictionary.
:::

## Custom Insert and Update Expressions

The `[CustomInsert]` and `[CustomUpdate]` attributes can be used to override what values rows are inserted during INSERT's and UPDATE's.

We can use this to insert a salted and hashed password using PostgreSQL native functions:

```csharp
public class CustomSqlUser
{
    [AutoIncrement]
    public int Id { get; set; }

    public string Email { get; set; }

    [CustomInsert("crypt({0}, gen_salt('bf'))"),
     CustomUpdate("crypt({0}, gen_salt('bf'))")]
    public string Password { get; set; }
}

var user = new CustomSqlUser {
    Email = "user@email.com", 
    Password = "secret"
};
db.Insert(user);
```

We can then use `Sql.Custom()` to create a partially typed custom query to match on the hashed password, e.g:

```csharp
var quotedSecret = db.Dialect().GetQuotedValue("secret");
var q = db.From<CustomSqlUser>()
    .Where(x => x.Password == Sql.Custom($"crypt({quotedSecret}, password)"));
var row = db.Single(q);
```

#### Pre / Post Custom SQL Hooks when Creating and Dropping tables

Pre / Post Custom SQL Hooks allow you to inject custom SQL before and after tables are created or dropped, e.g:

```csharp
[PostCreateTable("INSERT INTO TableWithSeedData (Name) VALUES ('Foo');" +
                 "INSERT INTO TableWithSeedData (Name) VALUES ('Bar');")]
public class TableWithSeedData
{
    [AutoIncrement]
    public int Id { get; set; }
    public string Name { get; set; }
}
```

Which like other ServiceStack attributes, can also be added dynamically, e.g:

```csharp
typeof(TableWithSeedData)
    .AddAttributes(new PostCreateTableAttribute(
        "INSERT INTO TableWithSeedData (Name) VALUES ('Foo');" +
        "INSERT INTO TableWithSeedData (Name) VALUES ('Bar');"));
```

Custom SQL Hooks also allow executing custom SQL before and after a table has been created or dropped, i.e:

```csharp
[PreCreateTable(runSqlBeforeTableCreated)]
[PostCreateTable(runSqlAfterTableCreated)]
[PreDropTable(runSqlBeforeTableDropped)]
[PostDropTable(runSqlAfterTableDropped)]
public class Table {}
```

## Custom SqlExpression Filter

The generated SQL from a Typed `SqlExpression` can also be customized using `.WithSqlFilter()`, e.g:

```csharp
var q = db.From<Table>()
    .Where(x => x.Age == 27)
    .WithSqlFilter(sql => sql + " option (recompile)");

var q = db.From<Table>()
    .Where(x => x.Age == 27)
    .WithSqlFilter(sql => sql + " WITH UPDLOCK");

var results = db.Select(q);
```

## Ignoring DTO Properties

You may use the `[Ignore]` attribute to denote DTO properties that are not fields in the table. This will force the SQL generation to ignore that property.


# Dictionary APIs
Source: https://docs.servicestack.net/ormlite/dictionary-apis

OrmLite's Dictionary APIs allow you to customize which parts of a Data Model should be modified by
converting it into then manipulating an Object Dictionary, e.g:

## Insert by Dictionary

```csharp
var row = new Person { FirstName = "John", LastName = "Smith" };
Dictionary<string,object> obj = row.ToObjectDictionary();
obj[nameof(Person.LastName)] = null;

row.Id = (int) db.Insert<Person>(obj, selectIdentity:true);
```

## Update by Dictionary

```csharp
Person row = db.SingleById<Person>(row.Id);
var obj = row.ToObjectDictionary();
obj[nameof(Person.LastName)] = "Smith";
db.Update<Person>(obj);
```

## UpdateOnly by Dictionary

```csharp
// By Primary Key Id
var fields = new Dictionary<string, object> {
    [nameof(Person.Id)] = 1,
    [nameof(Person.FirstName)] = "John",
    [nameof(Person.LastName)] = null,
};

db.UpdateOnly<Person>(fields);

// By Custom Where Expression
var fields = new Dictionary<string, object> {
    [nameof(Person.FirstName)] = "John",
    [nameof(Person.LastName)] = null,
};

db.UpdateOnly<Person>(fields, p => p.LastName == "Hendrix");
```

## Delete by Dictionary

```csharp
db.Delete<Rockstar>(new Dictionary<string, object> {
    ["Age"] = 27
});
```


# SQL Server Features
Source: https://docs.servicestack.net/ormlite/sql-server-features

## SQL Server 2012 Sequences

The `[Sequence]` attribute can be used as an alternative to `[AutoIncrement]` for inserting rows with an auto incrementing integer value populated by SQL Server, but instead of needing an `IDENTITY` column it can populate a normal `INT` column from a user-defined Sequence, e.g:

```csharp
public class SequenceTest
{
    [Sequence("Seq_SequenceTest_Id"), ReturnOnInsert]
    public int Id { get; set; }

    public string Name { get; set; }
    public string UserName { get; set; }
    public string Email { get; set; }

    [Sequence("Seq_Counter")]
    public int Counter { get; set; }
}

var user = new SequenceTest { Name = "me", Email = "me@mydomain.com" };
db.Insert(user);

user.Id //= Populated by next value in "Seq_SequenceTest_Id" SQL Server Sequence
```

The new `[ReturnOnInsert]` attribute tells OrmLite which columns to return the values of, in this case it returns the new Sequence value the row was inserted with. Sequences offer more flexibility than `IDENTITY` columns where you can use multiple sequences in a table or have the same sequence shared across multiple tables.

When creating tables, OrmLite will also create any missing Sequences automatically so you can continue to have reproducible tests and consistent Startups states that's unreliant on external state. But it doesn't drop sequences when OrmLite drops the table as they could have other external dependents.

To be able to use the new sequence support you'll need to use an SQL Server dialect greater than SQL Server 2012+, e.g:

```csharp
var dbFactory = new OrmLiteConnectionFactory(connString, SqlServer2012Dialect.Provider);
```

## SQL Server Table Hints

Using the same JOIN Filter feature OrmLite also lets you add SQL Server Hints on JOIN Table expressions, e.g:

```csharp
var q = db.From<Car>()
    .Join<Car, CarType>((c, t) => c.CarId == t.CarId, SqlServerTableHint.ReadUncommitted);
```

Which emits the appropriate SQL Server hints:

```sql
SELECT "Car"."CarId", "CarType"."CarTypeName" 
FROM "Car" INNER JOIN "CarType" WITH (READUNCOMMITTED) ON ("Car"."CarId" = "CarType"."CarId")
```

## Memory Optimized Tables

OrmLite allows access to many advanced SQL Server features including
[Memory-Optimized Tables](https://msdn.microsoft.com/en-us/library/dn133165.aspx) where you can tell
SQL Server to maintain specific tables in Memory using the `[SqlServerMemoryOptimized]` attribute, e.g:

```csharp
[SqlServerMemoryOptimized(SqlServerDurability.SchemaOnly)]
public class SqlServerMemoryOptimizedCacheEntry : ICacheEntry
{
    [PrimaryKey]
    [StringLength(StringLengthAttribute.MaxText)]
    [SqlServerBucketCount(10000000)]
    public string Id { get; set; }
    [StringLength(StringLengthAttribute.MaxText)]
    public string Data { get; set; }
    public DateTime CreatedDate { get; set; }
    public DateTime? ExpiryDate { get; set; }
    public DateTime ModifiedDate { get; set; }
}
```

The `[SqlServerBucketCount]` attribute can be used to
[configure the bucket count for a hash index](https://msdn.microsoft.com/en-us/library/mt706517.aspx#configuring_bucket_count)
whilst the new `[SqlServerCollate]` attribute can be used to specify an SQL Server collation.

## SQL Server Types

OrmLite can be extended to support new Types using SQL Server Special Type Converters which currently adds support for the SQL Server-specific
[SqlGeography](https://github.com/ServiceStack/ServiceStack.OrmLite/blob/master/src/ServiceStack.OrmLite.SqlServer.Converters/SqlServerGeographyTypeConverter.cs),
[SqlGeometry](https://github.com/ServiceStack/ServiceStack.OrmLite/blob/master/src/ServiceStack.OrmLite.SqlServer.Converters/SqlServerGeometryTypeConverter.cs)
and
[SqlHierarchyId](https://github.com/ServiceStack/ServiceStack.OrmLite/blob/master/src/ServiceStack.OrmLite.SqlServer.Converters/SqlServerHierarchyIdTypeConverter.cs)
Types.

Since these Types require an external dependency to the **Microsoft.SqlServer.Types** NuGet package they're
contained in a separate NuGet package that can be installed with:

```
PM> Install-Package ServiceStack.OrmLite.SqlServer.Converters
```

Once installed, all available SQL Server Types can be registered on your SQL Server Provider with:

```csharp
SqlServerConverters.Configure(SqlServer2012Dialect.Provider);
```

## SqlServer 2012 Connection String

In addition to using `SqlServer2012Dialect.Provider` you'll also need to specify you're using MSSQL 2012 on the connection string by adding the `;Type System Version=SQL Server 2012;` suffix, e.g:

```csharp
var dbFactory = new OrmLiteConnectionFactory(
  "Server=host;Database=db;User Id=sa;Password=test;Type System Version=SQL Server 2012",
  SqlServer2012Dialect.Provider);

var db = dbFactory.OpenDbConnection();
```

### Example Usage

After the Converters are registered they can treated like a normal .NET Type, e.g:

**SqlHierarchyId** Example:

```csharp
public class Node {
    [AutoIncrement]
    public long Id { get; set; }
    public SqlHierarchyId TreeId { get; set; }
}

db.DropAndCreateTable<Node>();

var treeId = SqlHierarchyId.Parse("/1/1/3/"); // 0x5ADE is hex
db.Insert(new Node { TreeId = treeId });

var parent = db.Scalar<SqlHierarchyId>(
    db.From<Node>().Select("TreeId.GetAncestor(1)"));
parent.ToString().Print(); //= /1/1/
```

**SqlGeography** and **SqlGeometry** Example:

```csharp
public class GeoTest {
    public long Id { get; set; }
    public SqlGeography Location { get; set; }
    public SqlGeometry Shape { get; set; }
}

db.DropAndCreateTable<GeoTest>();

var geo = SqlGeography.Point(40.6898329,-74.0452177, 4326); // Statue of Liberty

// A simple line from (0,0) to (4,4)  Length = SQRT(2 * 4^2)
var wkt = new System.Data.SqlTypes.SqlChars("LINESTRING(0 0,4 4)".ToCharArray());
var shape = SqlGeometry.STLineFromText(wkt, 0);

db.Insert(new GeoTestTable { Id = 1, Location = geo, Shape = shape });
var dbShape = db.SingleById<GeoTest>(1).Shape;

new { dbShape.STEndPoint().STX, dbShape.STEndPoint().STY }.PrintDump();
```

Output:

```
{
    STX: 4,
    STY: 4
}
```


# PostgreSQL Features
Source: https://docs.servicestack.net/ormlite/postgres-features

## PostgreSQL Rich Data Types

The `[PgSql*]` specific attributes lets you use attributes to define PostgreSQL rich data types, e.g:

```csharp
public class MyPostgreSqlTable
{
    [PgSqlJson]
    public List<Poco> AsJson { get; set; }

    [PgSqlJsonB]
    public List<Poco> AsJsonB { get; set; }

    [PgSqlTextArray]
    public string[] AsTextArray { get; set; }

    [PgSqlIntArray]
    public int[] AsIntArray { get; set; }

    [PgSqlBigIntArray]
    public long[] AsLongArray { get; set; }
}
```

By default, all arrays of .NET's built-in **numeric**, **string** and **DateTime** types will be stored in PostgreSQL array types:

```csharp
public class Table
{
    public Guid Id { get; set; }

    public int[] Ints { get; set; }
    public long[] Longs { get; set; }
    public float[] Floats { get; set; }
    public double[] Doubles { get; set; }
    public decimal[] Decimals { get; set; }
    public string[] Strings { get; set; }
    public DateTime[] DateTimes { get; set; }
    public DateTimeOffset[] DateTimeOffsets { get; set; }
}
```

You can opt in to annotate other collections like `List<T>` to also be stored in array types by annotating them with `[Pgsql*]` attributes, e.g:

```csharp
public class Table
{
    public Guid Id { get; set; }

    [PgSqlIntArray]
    public List<int> ListInts { get; set; }
    [PgSqlBigIntArray]
    public List<long> ListLongs { get; set; }
    [PgSqlFloatArray]
    public List<float> ListFloats { get; set; }
    [PgSqlDoubleArray]
    public List<double> ListDoubles { get; set; }
    [PgSqlDecimalArray]
    public List<decimal> ListDecimals { get; set; }
    [PgSqlTextArray]
    public List<string> ListStrings { get; set; }
    [PgSqlTimestamp]
    public List<DateTime> ListDateTimes { get; set; }
    [PgSqlTimestampTz]
    public List<DateTimeOffset> ListDateTimeOffsets { get; set; }
}
```

Alternatively if you **always** want `List<T>` stored in Array types, you can register them in the `PostgreSqlDialect.Provider`:

```csharp
PostgreSqlDialect.Provider.RegisterConverter<List<string>>(new PostgreSqlStringArrayConverter());
PostgreSqlDialect.Provider.RegisterConverter<List<int>>(new PostgreSqlIntArrayConverter());
PostgreSqlDialect.Provider.RegisterConverter<List<long>>(new PostgreSqlLongArrayConverter());
PostgreSqlDialect.Provider.RegisterConverter<List<float>>(new PostgreSqlFloatArrayConverter());
PostgreSqlDialect.Provider.RegisterConverter<List<double>>(new PostgreSqlDoubleArrayConverter());
PostgreSqlDialect.Provider.RegisterConverter<List<decimal>>(new PostgreSqlDecimalArrayConverter());
PostgreSqlDialect.Provider.RegisterConverter<List<DateTime>>(new PostgreSqlDateTimeTimeStampArrayConverter());
PostgreSqlDialect.Provider.RegisterConverter<List<DateTimeOffset>>(new PostgreSqlDateTimeOffsetTimeStampTzArrayConverter());
```

## PostgreSQL Params

The `PgSql.Param()` API provides a resolve the correct populated `NpgsqlParameter` and `NpgsqlDbType` from a C# Type
which can be used to query custom PostgreSQL Data Types in APIs that accept `IDbDataParameter` parameters, e.g:

```csharp
public class FunctionResult
{
    public int[] Val { get; set; }
}

var p = PgSql.Param("paramValue", testVal);
var sql = "SELECT * FROM my_func(@paramValue)";
var rows = db.Select<FunctionResult>(sql, new [] { p });
```

## Hstore support

To use `hstore`, its extension needs to be enabled in your PostgreSQL RDBMS by running:

```
CREATE EXTENSION hstore;
```

Which can then be enabled in OrmLite with:

```csharp
PostgreSqlDialect.Instance.UseHstore = true;
```

Where it will now store **string Dictionaries** in `Hstore` columns:

```csharp
public class TableHstore
{
    public int Id { get; set; }

    public Dictionary<string,string> Dictionary { get; set; }
    public IDictionary<string,string> IDictionary { get; set; }
}

db.DropAndCreateTable<TableHstore>();

db.Insert(new TableHstore
{
    Id = 1,
    Dictionary = new Dictionary<string, string> { {"A", "1"} },
    IDictionary = new Dictionary<string, string> { {"B", "2"} },
});
```

Where they can than be queried in postgres using [Hstore SQL Syntax](https://www.postgresql.org/docs/9.0/hstore.html):

```csharp
db.Single(db.From<PostgreSqlTypes>().Where("dictionary -> 'A' = '1'")).Id //= 1
```

Thanks to [@cthames](https://forums.servicestack.net/users/cthames/activity) for this feature.

## JSON data types

If you instead wanted to store arbitrary complex types in PostgreSQL's rich column types to enable deep querying in postgres,
you'd instead annotate them with `[PgSqlJson]` or `[PgSqlJsonB]`, e.g:

```csharp
public class TableJson
{
    public int Id { get; set; }

    [PgSqlJson]
    public ComplexType ComplexTypeJson { get; set; }

    [PgSqlJsonB]
    public ComplexType ComplexTypeJsonb { get; set; }
}

db.Insert(new TableJson
{
    Id = 1,
    ComplexTypeJson = new ComplexType {
        Id = 2, SubType = new SubType { Name = "JSON" }
    },
    ComplexTypeJsonb = new ComplexType {
        Id = 3, SubType = new SubType { Name = "JSONB" }
    },
});
```

Where they can then be queried on the server with [JSON SQL Syntax and functions](https://www.postgresql.org/docs/9.3/functions-json.html):

```csharp
var result = db.Single<TableJson>("table_json->'SubType'->>'Name' = 'JSON'");
```

## Custom SQL using PostgreSQL Arrays

The `PgSql.Array()` provides a typed API for generating [PostgreSQL Array Expressions](https://www.postgresql.org/docs/current/arrays.html), e.g:

```csharp
PgSql.Array(1,2,3)     //= ARRAY[1,2,3]
var strings = new[]{ "A","B","C" };
PgSql.Array(strings)   //= ARRAY['A','B','C']
```

Which you can safely use in Custom SQL Expressions that use PostgreSQL's native ARRAY support:

```csharp
q.And($"{PgSql.Array(anyTechnologyIds)} && technology_ids")
q.And($"{PgSql.Array(labelSlugs)} && labels");
```

If you want and empty collection to return `null` instead of an empty `ARRAY[]` you can use the `nullIfEmpty` overload:

```csharp
PgSql.Array(new string[0], nullIfEmpty:true)      //= null
PgSql.Array(new[]{"A","B","C"}, nullIfEmpty:true) //= ARRAY['A','B','C']
```


# Optimistic Concurrency
Source: https://docs.servicestack.net/ormlite/optimistic-concurrency

Optimistic concurrency can be added to any table by adding the `ulong RowVersion { get; set; }` property, e.g:

```csharp
public class Poco
{
    ...
    public ulong RowVersion { get; set; }
}
```

RowVersion is implemented efficiently in all major RDBMS's, i.e:

- Uses `rowversion` datatype in SqlServer
- Uses PostgreSql's `xmin` system column (no column on table required)
- Uses UPDATE triggers on MySql, Sqlite and Oracle whose lifetime is attached to Create/Drop tables APIs

Despite their differing implementations each provider works the same way where the `RowVersion` property is populated when the record is selected and only updates the record if the RowVersion matches with what's in the database, e.g:

```csharp
var rowId = db.Insert(new Poco { Text = "Text" }, selectIdentity:true);

var row = db.SingleById<Poco>(rowId);
row.Text += " Updated";
db.Update(row); //success!

row.Text += "Attempting to update stale record";

//Can't update stale record
Assert.Throws<OptimisticConcurrencyException>(() =>
    db.Update(row));

//Can update latest version
var updatedRow = db.SingleById<Poco>(rowId);  // fresh version
updatedRow.Text += "Update Success!";
db.Update(updatedRow);

updatedRow = db.SingleById<Poco>(rowId);
db.Delete(updatedRow);                        // can delete fresh version
```

Optimistic concurrency is only verified on API's that update or delete an entire entity, i.e. it's not enforced in partial updates. There's also an Alternative API available for DELETE's:

```csharp
db.DeleteById<Poco>(id:updatedRow.Id, rowversion:updatedRow.RowVersion)
```

## RowVersion Byte Array

To improve reuse of OrmLite's Data Models in Dapper, OrmLite also supports `byte[] RowVersion` which lets you use OrmLite Data Models with `byte[] RowVersion` properties in Dapper queries.

## Conflict Resolution using commandFilter

An optional `Func<IDbCommand> commandFilter` is available in all `INSERT` and `UPDATE` APIs to allow customization and inspection of the populated `IDbCommand` before it's run.
This feature is utilized in the [Conflict Resolution Extension methods](https://github.com/ServiceStack/ServiceStack.OrmLite/blob/master/src/ServiceStack.OrmLite/OrmLiteConflictResolutions.cs)
where you can specify the conflict resolution strategy when a Primary Key or Unique constraint violation occurs:

```csharp
db.InsertAll(rows, dbCmd => dbCmd.OnConflictIgnore());

//Equivalent to: 
db.InsertAll(rows, dbCmd => dbCmd.OnConflict(ConflictResolution.Ignore));
```

In this case it will ignore any conflicts that occur and continue inserting the remaining rows in SQLite, MySql and PostgreSQL, whilst in SQL Server it's a NOOP.

SQLite offers [additional fine-grained behavior](https://sqlite.org/lang_conflict.html) that can be specified for when a conflict occurs:

- ROLLBACK
- ABORT
- FAIL
- IGNORE
- REPLACE


# OrmLite Untyped API and T4 Templates
Source: https://docs.servicestack.net/ormlite/untyped-apis

The [IUntypedApi](https://github.com/ServiceStack/ServiceStack.OrmLite/blob/master/src/ServiceStack.OrmLite/IUntypedApi.cs) interface is useful for when you only have access to a late-bound object runtime type which is accessible via `db.CreateTypedApi`, e.g:

```csharp
public class BaseClass
{
    public int Id { get; set; }
}

public class Target : BaseClass
{
    public string Name { get; set; }
}

var row = (BaseClass)new Target { Id = 1, Name = "Foo" };

var useType = row.GetType();
var typedApi = db.CreateTypedApi(useType);

db.DropAndCreateTables(useType);

typedApi.Save(row);

var typedRow = db.SingleById<Target>(1);
typedRow.Name //= Foo

var updateRow = (BaseClass)new Target { Id = 1, Name = "Bar" };

typedApi.Update(updateRow);

typedRow = db.SingleById<Target>(1);
typedRow.Name //= Bar

typedApi.Delete(typedRow, new { Id = 1 });

typedRow = db.SingleById<Target>(1); //= null
```

## T4 Template Support

[OrmLite's T4 Template](https://github.com/ServiceStack/ServiceStack.OrmLite/tree/master/src/T4)
are useful in database-first development or when wanting to use OrmLite with an existing
RDBMS by automatically generating POCO's and strong-typed wrappers
for executing stored procedures.

```
PM> Install-Package ServiceStack.OrmLite.T4
```


# AutoGen &amp; T4 Templates
Source: https://docs.servicestack.net/ormlite/autogen-t4

## AutoQuery AutoGen

The recommended way to auto generate Tables and APIs for your existing RDBMS tables is to use [AutoQuery AutoGen](/autoquery/autogen) whose declarative nature allows us to easily generate AutoQuery & Crud Services using just declarative DTOs.

<lite-youtube class="w-full mx-4 my-4" width="560" height="315" videoid="NaJ7TW-Q_pU" style="background-image: url('https://img.youtube.com/vi/NaJ7TW-Q_pU/maxresdefault.jpg')"></lite-youtube>

## T4 Templates

[OrmLite's T4 Template](https://github.com/ServiceStack/ServiceStack.OrmLite/tree/master/src/T4) are useful in database-first development or when wanting to use OrmLite with an existing RDBMS by automatically generating POCO's and strong-typed wrappers for executing stored procedures.

:::copy
`<PackageReference Include="ServiceStack.OrmLite.T4" Version="8.*" />`
:::


# OrmLite Stored Procedure Usage
Source: https://docs.servicestack.net/ormlite/stored-procedures

The Raw SQL APIs provide a convenient way for mapping results of any Custom SQL like
executing Stored Procedures:

```csharp
List<Poco> results = db.SqlList<Poco>("EXEC GetAnalyticsForWeek 1");
List<Poco> results = db.SqlList<Poco>(
    "EXEC GetAnalyticsForWeek @weekNo", new { weekNo = 1 });

List<int> results = db.SqlList<int>("EXEC GetTotalsForWeek 1");
List<int> results = db.SqlList<int>(
    "EXEC GetTotalsForWeek @weekNo", new { weekNo = 1 });

int result = db.SqlScalar<int>("SELECT 10");
```

## SqlList with Out Params

```csharp
IDbDataParameter pTotal = null;
var results = await db.SqlListAsync<LetterFrequency>("spSearchLetters",
    cmd => {
        cmd.CommandType = CommandType.StoredProcedure;
        cmd.AddParam("pLetter", "C");
        pTotal = cmd.AddParam("pTotal", direction: ParameterDirection.Output);
    });
```

## Custom Results with SqlProc

`ConvertToList` should be used to read the results into the matching resultset, e.g. tabular or a single column of values:

```csharp
using var cmd = db.SqlProc("spSearchLetters", new { pLetter = "C" }));

var rows = cmd.ConvertToList<LetterFrequency>();
var ints = cmd.ConvertToList<int>();
```

## Stored Procedures with output params

The `SqlProc` API provides even greater customization by letting you modify the underlying
ADO.NET Stored Procedure call by returning a prepared `IDbCommand` allowing for
advanced customization like setting and retrieving OUT parameters, e.g:

```csharp
db.ExecuteSql(@"DROP PROCEDURE IF EXISTS spSearchLetters;
    CREATE PROCEDURE spSearchLetters (IN pLetter varchar(10), OUT pTotal int)
    BEGIN
        SELECT COUNT(*) FROM LetterFrequency WHERE Letter = pLetter INTO pTotal;
        SELECT * FROM LetterFrequency WHERE Letter = pLetter;
    END");

using var cmd = db.SqlProc("spSearchLetters", new { pLetter = "C" });
var pTotal = cmd.AddParam("pTotal", direction: ParameterDirection.Output);

var results = cmd.ConvertToList<LetterFrequency>();
var total = pTotal.Value;
```

An alternative approach is to use `SqlList` which lets you use a filter to customize a
Stored Procedure or any other command type, e.g:

```csharp
IDbDataParameter pTotal = null;
var results = db.SqlList<LetterFrequency>("spSearchLetters", cmd => {
        cmd.CommandType = CommandType.StoredProcedure;
        cmd.AddParam("pLetter", "C");
        pTotal = cmd.AddParam("pTotal", direction: ParameterDirection.Output);
    });
var total = pTotal.Value;
```

More examples can be found in:

 - [CustomSqlTests.cs](https://github.com/ServiceStack/ServiceStack/blob/main/ServiceStack.OrmLite/tests/ServiceStack.OrmLite.SqlServer.Tests/CustomSqlTests.cs)
 - [CustomSqlTestsAsync.cs](https://github.com/ServiceStack/ServiceStack/blob/main/ServiceStack.OrmLite/tests/ServiceStack.OrmLite.Tests/Async/CustomSqlTestsAsync.cs)


# Multi-nested database connections example
Source: https://docs.servicestack.net/ormlite/multi-database-connections

The `OrmLiteConnectionFactory` class supports registering multiple named connections allows you to define all your 
db connections when registering it in your IOC, that can be accessed later using its registered name.

## Primary DB & Multi Shard DB Example

A popular way of scaling RDBMS's is to create a Master / Shard setup where datasets for queries that span entire system
are kept in the master database, whilst context-specific related data can be kept together in an isolated shard.
This feature makes it trivial to maintain multiple separate db shards with a master database in a different RDBMS.

Here's an (entire source code) sample of the code needed to define, and populate a Master/Shard setup.
Sqlite can create DB shards on the fly so only the blank SqlServer master database needed to be created out-of-band:

### Sharding 1000 Robots into 10 Sqlite DB shards

```csharp
public class MasterRecord {
    public Guid Id { get; set; }
    public int RobotId { get; set; }
    public string RobotName { get; set; }
    public DateTime? LastActivated { get; set; }
}

public class Robot {
    public int Id { get; set; }
    public string Name { get; set; }
    public bool IsActivated { get; set; }
    public long CellCount { get; set; }
    public DateTime CreatedDate { get; set; }
}

const int NoOfShards = 10;
const int NoOfRobots = 1000;

var dbFactory = new OrmLiteConnectionFactory(
    "Data Source=host;Initial Catalog=RobotsMaster;Integrated Security=SSPI",  //Connection String
    SqlServerDialect.Provider); 

dbFactory.Run(db => db.CreateTable<MasterRecord>(overwrite:false));

NoOfShards.Times(i => {
    var namedShard = "robots-shard" + i;
    dbFactory.RegisterConnection(namedShard, 
        $"~/App_Data/{shardId}.sqlite".MapAbsolutePath(),                //Connection String
        SqliteDialect.Provider);
	
	dbFactory.OpenDbConnection(namedShard).Run(db => db.CreateTable<Robot>(overwrite:false));
});

var newRobots = NoOfRobots.Times(i => //Create 1000 Robots
    new Robot { Id=i, Name="R2D"+i, CreatedDate=DateTime.UtcNow, CellCount=DateTime.Now.ToUnixTimeMs() % 100000 });

foreach (var newRobot in newRobots) 
{
    using (IDbConnection db = dbFactory.OpenDbConnection()) //Open Connection to Master DB 
    {
        db.Insert(new MasterRecord { Id = Guid.NewGuid(), RobotId = newRobot.Id, RobotName = newRobot.Name });
        using (IDbConnection robotShard = dbFactory.OpenDbConnection("robots-shard"+newRobot.Id % NoOfShards)) //Shard
        {
            robotShard.Insert(newRobot);
        }
    }
}
```

Using the [SQLite Manager](https://addons.mozilla.org/en-US/firefox/addon/sqlite-manager/?src=search) Firefox extension
we can peek at one of the created shards to see 100 Robots in each shard. This is the dump of `robots-shard0.sqlite`:

![Data dump of Robot Shard #1](/img/pages/ormlite/robots-shard0.sqlite.jpg)

As expected each shard has every 10th robot inside.


# OrmLite walk through example
Source: https://docs.servicestack.net/ormlite/shippers-example

In its simplest usage, OrmLite can persist any POCO type without any attributes required:

```csharp
public class SimpleExample
{
	public int Id { get; set; }
	public string Name { get; set; }
}

//Set once before use (i.e. in a static constructor).
OrmLiteConfig.DialectProvider = SqliteDialect.Provider;

using (IDbConnection db = "/path/to/db.sqlite".OpenDbConnection())
{
	db.CreateTable<SimpleExample>(true);
	db.Insert(new SimpleExample { Id=1, Name="Hello, World!"});
	var rows = db.Select<SimpleExample>();

	Assert.That(rows, Has.Count(1));
	Assert.That(rows[0].Id, Is.EqualTo(1));
}
```

To get a better idea of the features of OrmLite lets walk through a complete example using sample tables from the Northwind database.
_ (Full source code for this example is [available here](https://github.com/ServiceStack/ServiceStack/blob/main/ServiceStack.OrmLite/tests/ServiceStack.OrmLite.Tests/ShippersExample.cs).) _

So with no other configuration using only the classes below:

```csharp
[Alias("Shippers")]
public class Shipper
	: IHasId<int>
{
	[AutoIncrement]
	[Alias("ShipperID")]
	public int Id { get; set; }

	[Required]
	[Index(Unique = true)]
	[StringLength(40)]
	public string CompanyName { get; set; }

	[StringLength(24)]
	public string Phone { get; set; }

	[References(typeof(ShipperType))]
	public int ShipperTypeId { get; set; }
}

[Alias("ShipperTypes")]
public class ShipperType
	: IHasId<int>
{
	[AutoIncrement]
	[Alias("ShipperTypeID")]
	public int Id { get; set; }

	[Required]
	[Index(Unique = true)]
	[StringLength(40)]
	public string Name { get; set; }
}

public class SubsetOfShipper
{
	public int ShipperId { get; set; }
	public string CompanyName { get; set; }
}

public class ShipperTypeCount
{
	public int ShipperTypeId { get; set; }
	public int Total { get; set; }
}
```

## Creating tables
Creating tables is a simple 1-liner:

```csharp
using (IDbConnection db = ":memory:".OpenDbConnection())
{
    db.CreateTable<ShipperType>();
    db.CreateTable<Shipper>();
}

/* In debug mode the line above prints:
DEBUG: CREATE TABLE "ShipperTypes" 
(
  "ShipperTypeID" INTEGER PRIMARY KEY AUTOINCREMENT, 
  "Name" VARCHAR(40) NOT NULL 
);
DEBUG: CREATE UNIQUE INDEX uidx_shippertypes_name ON "ShipperTypes" ("Name" ASC);
DEBUG: CREATE TABLE "Shippers" 
(
  "ShipperID" INTEGER PRIMARY KEY AUTOINCREMENT, 
  "CompanyName" VARCHAR(40) NOT NULL, 
  "Phone" VARCHAR(24) NULL, 
  "ShipperTypeId" INTEGER NOT NULL, 

  CONSTRAINT "FK_Shippers_ShipperTypes" FOREIGN KEY ("ShipperTypeId") REFERENCES "ShipperTypes" ("ShipperID") 
);
DEBUG: CREATE UNIQUE INDEX uidx_shippers_companyname ON "Shippers" ("CompanyName" ASC);
*/
```

## Transaction Support

As we have direct access to IDbCommand and friends - playing with transactions is easy:

```csharp
var trainsType = new ShipperType { Name = "Trains" };
var planesType = new ShipperType { Name = "Planes" };

//Playing with transactions
using (IDbTransaction dbTrans = db.OpenTransaction())
{
    db.Save(trainsType);
    db.Save(planesType);

    dbTrans.Commit();
}

using (IDbTransaction dbTrans = db.OpenTransaction(IsolationLevel.ReadCommitted))
{
    db.Insert(new ShipperType { Name = "Automobiles" });
    Assert.That(db.Select<ShipperType>(), Has.Count.EqualTo(3));
}
Assert.That(db.Select<ShipperType>(), Has.Count(2));
```

## CRUD Operations
No ORM is complete without the standard crud operations:

```csharp
	//Performing standard Insert's and Selects
  db.Insert(new Shipper { CompanyName = "Trains R Us", Phone = "555-TRAINS", ShipperTypeId = trainsType.Id });
  db.Insert(new Shipper { CompanyName = "Planes R Us", Phone = "555-PLANES", ShipperTypeId = planesType.Id });
  db.Insert(new Shipper { CompanyName = "We do everything!", Phone = "555-UNICORNS", ShipperTypeId = planesType.Id });

  var trainsAreUs = db.Single<Shipper>("ShipperTypeId = @Id", new { trainsType.Id });
  Assert.That(trainsAreUs.CompanyName, Is.EqualTo("Trains R Us"));
  Assert.That(db.Select<Shipper>("CompanyName = @company OR Phone = @phone", 
        new { company = "Trains R Us", phone = "555-UNICORNS" }), Has.Count.EqualTo(2));
  Assert.That(db.Select<Shipper>("ShipperTypeId = @Id", new { planesType.Id }), Has.Count.EqualTo(2));

  //Lets update a record
  trainsAreUs.Phone = "666-TRAINS";
  db.Update(trainsAreUs);
          Assert.That(db.SingleById<Shipper>(trainsAreUs.Id).Phone, Is.EqualTo("666-TRAINS"));
  
  //Then make it dissappear
  db.Delete(trainsAreUs);
          Assert.That(db.SingleById<Shipper>(trainsAreUs.Id), Is.Null);

  //And bring it back again
  db.Insert(trainsAreUs);
```

## Performing custom queries

And with access to raw sql when you need it - the database is your oyster :)

```csharp
var partialColumns = db.Select<SubsetOfShipper>(typeof(Shipper), 
    "ShipperTypeId = @Id", new { planesType.Id });
Assert.That(partialColumns, Has.Count.EqualTo(2));

//Select into another POCO class that matches sql
var rows = db.Select<ShipperTypeCount>(
    "SELECT ShipperTypeId, COUNT(*) AS Total FROM Shippers GROUP BY ShipperTypeId ORDER BY COUNT(*)");

Assert.That(rows, Has.Count.EqualTo(2));
Assert.That(rows[0].ShipperTypeId, Is.EqualTo(trainsType.Id));
Assert.That(rows[0].Total, Is.EqualTo(1));
Assert.That(rows[1].ShipperTypeId, Is.EqualTo(planesType.Id));
Assert.That(rows[1].Total, Is.EqualTo(2));


//And finally lets quickly clean up the mess we've made:
db.DeleteAll<Shipper>();
db.DeleteAll<ShipperType>();

Assert.That(db.Select<Shipper>(), Has.Count.EqualTo(0));
Assert.That(db.Select<ShipperType>(), Has.Count.EqualTo(0));
```

## Soft Deletes

Select Filters let you specify a custom `SelectFilter` that lets you modify queries that use `SqlExpression<T>` before they're executed. This could be used to make working with "Soft Deletes" Tables easier where it can be made to apply a custom `x.IsDeleted != true` condition on every `SqlExpression`.

By either using a `SelectFilter` on concrete POCO Table Types, e.g:

```csharp
SqlExpression<Table1>.SelectFilter = q => q.Where(x => x.IsDeleted != true);
SqlExpression<Table2>.SelectFilter = q => q.Where(x => x.IsDeleted != true);
```

Or alternatively using generic delegate that applies to all SqlExpressions, but you'll only have access to a
`IUntypedSqlExpression` which offers a limited API surface area but will still let you execute a custom filter
for all `SqlExpression<T>` that could be used to add a condition for all tables implementing a custom
`ISoftDelete` interface with:

```csharp
OrmLiteConfig.SqlExpressionSelectFilter = q =>
{
    if (q.ModelDef.ModelType.HasInterface(typeof(ISoftDelete)))
    {
        q.Where<ISoftDelete>(x => x.IsDeleted != true);
    }
};
```

Both solutions above will transparently add the `x.IsDeleted != true` to all `SqlExpression<T>` based queries
so it only returns results which aren't `IsDeleted` from any of queries below:

```csharp
var results = db.Select(db.From<Table>());
var result = db.Single(db.From<Table>().Where(x => x.Name == "foo"));
var result = db.Single(x => x.Name == "foo");
```

## Check Constraints

OrmLite includes support for [SQL Check Constraints](https://en.wikipedia.org/wiki/Check_constraint) which will create your Table schema with the `[CheckConstraint]` specified, e.g:

```csharp
public class Table
{
    [AutoIncrement]
    public int Id { get; set; }

    [Required]
    [CheckConstraint("Age > 1")]
    public int Age { get; set; }

    [CheckConstraint("Name IS NOT NULL")]
    public string Name { get; set; }
}
```

### Bitwise operators

The Typed SqlExpression bitwise operations support depends on the RDBMS used.

E.g. all RDBMS's support Bitwise `And` and `Or` operators:

```csharp
db.Select<Table>(x => (x.Flags | 2) == 3);
db.Select<Table>(x => (x.Flags & 2) == 2);
```

All RDBMS Except for SQL Server support bit shift operators:

```csharp
db.Select<Table>(x => (x.Flags << 1) == 4);
db.Select<Table>(x => (x.Flags >> 1) == 1);
```

Whilst only SQL Server and MySQL Support Exclusive Or:

```csharp
db.Select<Table>(x => (x.Flags ^ 2) == 3);
```


# Customer &amp; Order example
Source: https://docs.servicestack.net/ormlite/customer-orders-example

## Example

#### Code-first Customer & Order example with complex types on POCO as text blobs

Below is a complete stand-alone example. No other config or classes is required for it to run. 

:::info
These examples are also available as an executable
[stand-alone unit test](https://github.com/ServiceStack/ServiceStack/blob/main/ServiceStack.OrmLite/tests/ServiceStack.OrmLite.Tests/UseCase/CustomerOrdersUseCase.cs)
([async](https://github.com/ServiceStack/ServiceStack/blob/main/ServiceStack.OrmLite/tests/ServiceStack.OrmLite.Tests/UseCase/CustomerOrdersUseCaseAsync.cs)).
:::

```csharp
public enum PhoneType 
{
    Home,
    Work,
    Mobile,
}

public enum AddressType 
{
    Home,
    Work,
    Other,
}

public class Address 
{
    public string Line1 { get; set; }
    public string Line2 { get; set; }
    public string ZipCode { get; set; }
    public string State { get; set; }
    public string City { get; set; }
    public string Country { get; set; }
}

public class Customer 
{
    [AutoIncrement] // Creates Auto primary key
    public int Id { get; set; }
    
    public string FirstName { get; set; }
    public string LastName { get; set; }
    
    [Index(Unique = true)] // Creates Unique Index
    public string Email { get; set; }
    
    public Dictionary<PhoneType, string> PhoneNumbers { get; set; } = new();  //Blobbed
    public Dictionary<AddressType, Address> Addresses { get; set; } = new();  //Blobbed
    public DateTime CreatedAt { get; set; }
}

public class Order 
{    
    [AutoIncrement]
    public int Id { get; set; }
    
    [References(typeof(Customer))]      //Creates Foreign Key
    public int CustomerId { get; set; }
    
    [References(typeof(Employee))]      //Creates Foreign Key
    public int EmployeeId { get; set; }
    
    public Address ShippingAddress { get; set; } //Blobbed (no Address table)
    
    public DateTime? OrderDate { get; set; }
    public DateTime? RequiredDate { get; set; }
    public DateTime? ShippedDate { get; set; }
    public int? ShipVia { get; set; }
    public decimal Freight { get; set; }
    public decimal Total { get; set; }
}

public class OrderDetail 
{
    [AutoIncrement]
    public int Id { get; set; }
    
    [References(typeof(Order))] //Creates Foreign Key
    public int OrderId { get; set; }
    
    public int ProductId { get; set; }
    public decimal UnitPrice { get; set; }
    public short Quantity { get; set; }
    public decimal Discount { get; set; }
}

public class Employee 
{
    public int Id { get; set; }
    public string Name { get; set; }
}

public class Product 
{
    public int Id { get; set; }
    public string Name { get; set; }
    public decimal UnitPrice { get; set; }
}

// Setup SQL Server Connection Factory
var dbFactory = new OrmLiteConnectionFactory(connString, SqlServerDialect.Provider);

// Use in-memory Sqlite DB instead
//var dbFactory = new OrmLiteConnectionFactory(
//    ":memory:", false, SqliteDialect.Provider);

//Non-intrusive: All extension methods hang off System.Data.* interfaces
using var db = Config.OpenDbConnection();

//Re-Create all table schemas:
db.DropTable<OrderDetail>();
db.DropTable<Order>();
db.DropTable<Customer>();
db.DropTable<Product>();
db.DropTable<Employee>();

db.CreateTable<Employee>();
db.CreateTable<Product>();
db.CreateTable<Customer>();
db.CreateTable<Order>();
db.CreateTable<OrderDetail>();

db.Insert(new Employee { Id = 1, Name = "Employee 1" });
db.Insert(new Employee { Id = 2, Name = "Employee 2" });
var product1 = new Product { Id = 1, Name = "Product 1", UnitPrice = 10 };
var product2 = new Product { Id = 2, Name = "Product 2", UnitPrice = 20 };
db.Save(product1, product2);

var customer = new Customer {
    FirstName = "Orm",
    LastName = "Lite",
    Email = "ormlite@servicestack.net",
    PhoneNumbers =
    {
        { PhoneType.Home, "555-1234" },
        { PhoneType.Work, "1-800-1234" },
        { PhoneType.Mobile, "818-123-4567" },
    },
    Addresses =
    {
        { AddressType.Work, new Address { 
            Line1 = "1 Street", Country = "US", State = "NY", City = "New York", ZipCode = "10101" } 
        },
    },
    CreatedAt = DateTime.UtcNow,
};

var customerId = db.Insert(customer, selectIdentity: true); //Get Auto Inserted Id
customer = db.Single<Customer>(new { customer.Email }); //Query

//Direct access to System.Data.Transactions:
using (IDbTransaction trans = db.OpenTransaction(IsolationLevel.ReadCommitted))
{
    var order = new Order {
        CustomerId = customer.Id,
        EmployeeId = 1,
        OrderDate = DateTime.UtcNow,
        Freight = 10.50m,
        ShippingAddress = new Address { 
        Line1 = "3 Street", Country = "US", State = "NY", City = "New York", ZipCode = "12121" },
    };
    db.Save(order); //Inserts 1st time

    //order.Id populated on Save().

    var orderDetails = new[] {
        new OrderDetail {
            OrderId = order.Id,
            ProductId = product1.Id,
            Quantity = 2,
            UnitPrice = product1.UnitPrice,
        },
        new OrderDetail {
            OrderId = order.Id,
            ProductId = product2.Id,
            Quantity = 2,
            UnitPrice = product2.UnitPrice,
            Discount = .15m,
        }
    };

    db.Save(orderDetails);

    order.Total = orderDetails.Sum(x => x.UnitPrice * x.Quantity * x.Discount) + order.Freight;

    db.Save(order); //Updates 2nd Time

    trans.Commit();
}
```

## Async Example

```csharp
await db.InsertAsync(new Employee { Id = 1, Name = "Employee 1" });
await db.InsertAsync(new Employee { Id = 2, Name = "Employee 2" });
var product1 = new Product { Id = 1, Name = "Product 1", UnitPrice = 10 };
var product2 = new Product { Id = 2, Name = "Product 2", UnitPrice = 20 };
await db.SaveAsync(product1, product2);

var customer = new Customer {
    FirstName = "Orm",
    LastName = "Lite",
    Email = "ormlite@servicestack.net",
    PhoneNumbers =
    {
        { PhoneType.Home, "555-1234" },
        { PhoneType.Work, "1-800-1234" },
        { PhoneType.Mobile, "818-123-4567" },
    },
    Addresses =
    {
        { AddressType.Work, new Address { 
            Line1 = "1 Street", Country = "US", State = "NY", City = "New York", ZipCode = "10101" } 
        },
    },
    CreatedAt = DateTime.UtcNow,
};

var customerId = await db.InsertAsync(customer, selectIdentity: true); //Get Auto Inserted Id
customer = await db.SingleAsync<Customer>(new { customer.Email }); //Query

//Direct access to System.Data.Transactions:
using var trans = db.OpenTransaction(IsolationLevel.ReadCommitted);
var order = new Order {
    CustomerId = customer.Id,
    EmployeeId = 1,
    OrderDate = DateTime.UtcNow,
    Freight = 10.50m,
    ShippingAddress = new Address { 
        Line1 = "3 Street", Country = "US", State = "NY", City = "New York", ZipCode = "12121" },
};
await db.SaveAsync(order); //Inserts 1st time

//order.Id populated on Save().
var orderDetails = new[] {
    new OrderDetail {
        OrderId = order.Id,
        ProductId = product1.Id,
        Quantity = 2,
        UnitPrice = product1.UnitPrice,
    },
    new OrderDetail {
        OrderId = order.Id,
        ProductId = product2.Id,
        Quantity = 2,
        UnitPrice = product2.UnitPrice,
        Discount = .15m,
    }
};

await db.SaveAsync(orderDetails);

order.Total = orderDetails.Sum(x => x.UnitPrice * x.Quantity * x.Discount) + order.Freight;

await db.SaveAsync(order); //Updates 2nd Time

trans.Commit();
```

Running this against a SQL Server database will yield the results below:

[![SQL Server Management Studio results](/img/pages/ormlite/ormlite-example.png)](/img/pages/ormlite/ormlite-example.png)

With the blobbed POCO types stored in the [very fast](https://github.com/ServiceStackV3/mythz_blog/blob/master/pages/176.md)
and [Versatile](https://github.com/ServiceStackV3/mythz_blog/blob/master/pages/314.md)
[JSV Format](/jsv-format) - a more compact, human and parser-friendly than JSON.


# OrmLite support for AWS &amp; RDS Managed Databases
Source: https://docs.servicestack.net/ormlite/aws-rds-databases

## AWS RDS Support

OrmLite has great support AWS's managed RDS Databases, follow these getting started guides to help to get up and running quickly:

- [PostgreSQL](https://github.com/ServiceStackApps/AwsGettingStarted#getting-started-with-aws-rds-postgresql-and-ormlite)
- [Aurora](https://github.com/ServiceStackApps/AwsGettingStarted#getting-started-with-aws-rds-aurora-and-ormlite)
- [MySQL](https://github.com/ServiceStackApps/AwsGettingStarted#getting-started-with-aws-rds-mysql-and-ormlite)
- [MariaDB](https://github.com/ServiceStackApps/AwsGettingStarted#getting-started-with-aws-rds-mariadb-and-ormlite)
- [SQL Server](https://github.com/ServiceStackApps/AwsGettingStarted#getting-started-with-aws-rds-sql-server-and-ormlite)

Source code for example can be found on our [AwsGettingStarted](https://github.com/ServiceStackApps/AwsGettingStarted) repositories.


# Limitations
Source: https://docs.servicestack.net/ormlite/limitations

## Single Primary Key

For simplicity, and to be able to have the same POCO class persisted in db4o, memcached, redis or on the filesystem (i.e. providers included in ServiceStack), each model must have a single primary key, by convention OrmLite expects it
to be `Id` although you use `[Alias("DbFieldName")]` attribute it map it to a column with a different name or use
the `[PrimaryKey]` attribute to tell OrmLite to use a different property for the primary key.

If an `Id` property or `[PrimaryKey]` attribute isn't specified, a Primary Key is assigned to `[AutoIncrement]` and `[AutoId]` properties, otherwise it's assumed the first property is the tables Primary Key.

You can still `SELECT` from these tables, you will just be unable to make use of APIs that rely on it, e.g.
`Update` or `Delete` where the filter is implied (i.e. not specified), all the APIs that end with `ById`, etc.

## Optimize LIKE Searches

One of the primary goals of OrmLite is to expose and RDBMS agnostic Typed API Surface which will allow you
to easily switch databases, or access multiple databases at the same time with the same behavior.

One instance where this can have an impact is needing to use `UPPER()` in **LIKE** searches to enable
case-insensitive **LIKE** queries across all RDBMS. The drawback of this is that LIKE Queries are not able
to use any existing RDBMS indexes. We can disable this feature and return to the default RDBMS behavior with:

```csharp
OrmLiteConfig.StripUpperInLike = true;
```

Allowing all **LIKE** Searches in OrmLite or AutoQuery to use any available RDBMS Index.

## Oracle Provider Notes

By default, the Oracle provider stores Guids in the database as character strings and when generating SQL it quotes only table and column names that are reserved words in Oracle. That requires that you use the same quoting if you code your own SQL. Both of these options can be overridden, but overriding them will cause problems: the provider can store Guids as raw(16) but it cannot read them.

The Oracle provider uses Oracle sequences to implement AutoIncrement columns and it queries the sequence to get a new value in a separate database call. You can override the automatically generated sequence name with a

```
[Sequence("name")]
```

attribute on a field. The Sequence attribute implies `[AutoIncrement]`, but you can use both on the same field.

Since Oracle has a very restrictive 30 character limit on names, it is strongly suggested that you use short entity class and field names or aliases, remembering that indexes and foreign keys get compound names. If you use long names, the provider will squash them to make them compliant with the restriction. The algorithm used is to remove all vowels ("aeiouy") and if still too long then every fourth letter starting with the third one and finally if still too long to truncate the name. You must apply the same squashing algorithm if you are coding your own SQL.

The previous version of ServiceStack.OrmLite.Oracle used System.Data.OracleClient to talk to the database. Microsoft has deprecated that client, but it does still mostly work if you construct the Oracle provider like this:

```
OracleOrmLiteDialectProvider.Instance = new OracleOrmLiteDialectProvider(
compactGuid: false,
quoteNames: false,
clientProvider: OracleOrmLiteDialectProvider.MicrosoftProvider); 
```

DateTimeOffset fields and, in locales that use a comma to separate the fractional part of a floating point number, some aspects of using floating point numbers, do not work with System.Data.OracleClient.


# What is Razor Press?
Source: https://docs.servicestack.net/razor-press/what-is-razor-press

Razor Press is a Razor Pages powered Markdown alternative to Ruby's Jekyll, Vue & VitePress that's ideal for 
generating fast, static content-centric & documentation websites. Inspired by [VitePress](https://vitepress.dev), 
it's designed to effortlessly create documentation around content written in Markdown, rendered using C# Razor Pages
and beautifully styled with [tailwindcss](https://tailwindcss.com) and [@tailwindcss/typography](https://tailwindcss.com/docs/typography-plugin).

The resulting statically generated HTML pages can easily be deployed anywhere, where it can be hosted by any HTTP Server or CDN.
By default it includes GitHub Actions to deploy it your GitHub Repo's **gh-pages** branch where it's hosted for FREE
on [GitHub Pages](https://pages.github.com) CDN which can be easily configured to use your 
[Custom Domain](https://docs.github.com/en/pages/configuring-a-custom-domain-for-your-github-pages-site).

## Use Cases

Razor Press utilizes the same technology as 
[Razor SSG](https://razor-ssg.web-templates.io/posts/razor-ssg) which is the template we recommend for developing any
statically generated sites with Razor like Blogs, Portfolios, and Marketing Sites as it includes more Razor & Markdown 
features like blogs and integration with [Creator Kit](https://servicestack.net/creatorkit/) - a companion OSS project
offers the necessary tools any static website can use to reach and retain users, from managing subscriber mailing lists to 
moderating a feature-rich comments system.

Some examples built with Razor SSG include:

<div class="not-prose mt-8 grid grid-cols-2 gap-4">
    <a class="block group border dark:border-gray-800 hover:border-indigo-700 dark:hover:border-indigo-700 flex flex-col justify-between" href="https://servicestack.net">
        <img class="p-2" src="https://docs.servicestack.net/img/pages/ssg/servicestack.net-home-1440.png">
        <div class="bg-gray-50 dark:bg-gray-800 text-gray-600 dark:text-gray-300 font-semibold group-hover:bg-indigo-700 group-hover:text-white text-center py-2">servicestack.net</div>
    </a>
    <a class="block group border dark:border-gray-800 hover:border-indigo-700 dark:hover:border-indigo-700" href="https://diffusion.works">
        <div style="max-height:350px;overflow:hidden">
        <img class="p-2" src="https://servicestack.net/img/posts/vue-diffusion/vuediffusion-search.png"></div>
        <div class="bg-gray-50 dark:bg-gray-800 text-gray-600 dark:text-gray-300 font-semibold group-hover:bg-indigo-700 group-hover:text-white text-center py-2">diffusion.works</div>
    </a>
    <a class="block group border dark:border-gray-800 hover:border-indigo-700 dark:hover:border-indigo-700" href="https://jamstacks.net">
        <img class="p-2" src="https://docs.servicestack.net/img/pages/release-notes/v6.9/jamstacks-screenshot.png">
        <div class="bg-gray-50 dark:bg-gray-800 text-gray-600 dark:text-gray-300 font-semibold group-hover:bg-indigo-700 group-hover:text-white text-center py-2">jamstacks.net</div>
    </a>
    <a class="block group border dark:border-gray-800 hover:border-indigo-700 dark:hover:border-indigo-700" href="https://xkcd.netcore.io">
        <img class="p-2" src="https://docs.servicestack.net/img/pages/release-notes/v6.9/xkcd-screenshot.png">
        <div class="bg-gray-50 dark:bg-gray-800 text-gray-600 dark:text-gray-300 font-semibold group-hover:bg-indigo-700 group-hover:text-white text-center py-2">xkcd.netcore.io</div>
    </a>
</div>

## Documentation

Razor Press is instead optimized for creating documentation and content-centric websites, with built-in features useful
for documentation websites including:

 - Customizable Sidebar Menus
 - Document Maps
 - Document Page Navigation
 - Autolink Headers
 
#### Markdown Extensions
 
- Markdown Content Includes
- Tip, Info, Warning, Danger sections
- Copy and Shell command widgets

But given **Razor Press** and **Razor SSG** share the same implementation, their features are easily transferable, e.g.
The [What's New](/whatsnew) and [Videos](/videos) sections are 
[features copied](https://razor-ssg.web-templates.io/posts/razor-ssg#whats-new-feature) from Razor SSG as they can be
useful in Documentation websites.

## Customizable {#custom-anchor .custom}

The source code of all Markdown and Razor Pages features are included in the template with all Markdown extensions
implemented in the [Markdown*.cs](https://github.com/NetCoreTemplates/razor-press/tree/main/MyApp) files allowing for
easier inspection, debugging and customization.

To simplify updating Markdown features in future we recommend against modifying the included `Markdown.*` files and instead
add any Markdig pipeline extensions or custom containers using `MarkdigConfig` in `Configure.Ssg.cs`: 

```csharp
MarkdigConfig.Set(new MarkdigConfig
{
    ConfigurePipeline = pipeline =>
    {
        // Extend Markdig Pipeline
    },
    ConfigureContainers = config =>
    {
        config.AddBuiltInContainers();
        // Add Custom Block or Inline containers
    }
});
```

### Update Markdown Extensions & Dependencies

Updating to the latest JavaScript dependencies and Markdown extensions can be done by running:

:::sh
npm install
:::

Which as the template has no npm dependencies, is just an alias for running `node postinstall.js`

## Example

The largest website generated with Razor Press is currently the ServiceStack's documentation at 
[docs.servicestack.net](https://docs.servicestack.net):

<div class="not-prose mt-8 grid grid-cols-2 gap-4">
    <a class="block group border dark:border-gray-800 hover:border-indigo-700 dark:hover:border-indigo-700" href="https://docs.servicestack.net/?light">
        <img class="p-2" src="https://servicestack.net/img/posts/razor-ssg/docs.servicestack.net.png">
        <div class="bg-gray-50 dark:bg-gray-800 text-gray-600 dark:text-gray-300 font-semibold group-hover:bg-indigo-700 group-hover:text-white text-center py-2">docs.servicestack.net</div>
    </a>
    <a class="block group border dark:border-gray-800 hover:border-indigo-700 dark:hover:border-indigo-700" href="https://docs.servicestack.net/?dark">
        <img class="p-2" src="https://servicestack.net/img/posts/razor-ssg/docs.servicestack.net-dark.png">
        <div class="bg-gray-50 dark:bg-gray-800 text-gray-600 dark:text-gray-300 font-semibold group-hover:bg-indigo-700 group-hover:text-white text-center py-2">docs.servicestack.net</div>
    </a>
</div>

A **500+** pages documentation website ported from VitePress, which prompted the creation of Razor Press after
experiencing issues with VitePress's SSR/SPA model whose workaround became too time consuming to maintain.

The new Razor SSG implementation now benefits from Razor Pages flexible layouts and partials where pages can be optionally
implemented in just markdown, Razor or a hybrid mix of both. The [Vue](/vue/) splash page is an example of this implemented in a custom
[/Vue/Index.cshtml](https://github.com/NetCoreTemplates/razor-press/blob/main/MyApp/Pages/Vue/Index.cshtml) Razor Page.

<div class="not-prose mt-8 grid grid-cols-2 gap-4">
    <a class="block group border dark:border-gray-800 hover:border-indigo-700 dark:hover:border-indigo-700" href="/vue/">
        <img class="p-2" src="https://docs.servicestack.net/img/pages/ssg/razor-pages-vue.png">
        <div class="bg-gray-50 dark:bg-gray-800 text-gray-600 dark:text-gray-300 font-semibold group-hover:bg-indigo-700 group-hover:text-white text-center py-2">docs.servicestack.net</div>
    </a>
</div>

## Feedback & Feature Requests Welcome

Up to this stage [docs.servicestack.net](https://docs.servicestack.net) has been the primary driver for Razor Press 
current feature-set, re-implementing all the previous VitePress features it used with C#, Razor Pages and Markdig extensions. 

In future we'll look at expanding this template with generic Markdown features suitable for documentation or content-centric 
websites, for which we welcome any feedback or new feature requests at:

<div class="not-prose">
   <h3 class="m-0 py-8 text-3xl text-center text-blue-600"><a href="https://servicestack.net/ideas">https://servicestack.net/ideas</a></h3>
</div>


# Structure
Source: https://docs.servicestack.net/razor-press/structure

### Markdown Feature Structure

All markdown features are effectively implemented in the same way, starting with a **_folder** for maintaining its static markdown
content, a **.cs** class to load the markdown and a **.cshtml** Razor Page to render it:

| Location                                                                                             | Description                                                           |
|------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------|
| `/_{Feature}`                                                                                        | Maintains the static markdown for the feature                         |
| `Markdown.{Feature}.cs`                                                                              | Functionality to read the feature's markdown into logical collections |
| `{Feature}.cshtml`                                                                                   | Functionality to Render the feature                                   |
| [Configure.Ssg.cs](https://github.com/NetCoreTemplates/razor-press/blob/main/MyApp/Configure.Ssg.cs) | Initializes and registers the feature with ASP .NET's IOC             |

Lets see what this looks like in practice by walking through the "Pages" feature:

## Pages Feature

The pages feature simply makes all pages in the **_pages** folder, available from `/{filename}`.

Where the included pages:

<file-layout :files="{
  _pages: {
    _: ['what-is-razor-press.md','structure.md','privacy.md'],
  }
}" class="cursor-pointer" v-on:click="nav('https://github.com/NetCoreTemplates/razor-press/tree/main/MyApp/_pages')"></file-layout>

Are made available from:

- [/what-is-razor-press](/what-is-razor-press)
- [/structure](/structure)
- [/privacy](/privacy)

This is primarily where most Markdown documentation will be maintained. 

### Document Collections

Folders can be used to maintain different document collections as seen in [/vue/](/vue/) and [/creatorkit/](/creatorkit/) folders: 

<file-layout :files="{
  _pages: {
    creatorkit: { _: ['about.md','components.md','customize.md'], },
    vue:        { _: ['alerts.md','autocomplete.md','autoform.md'], },
  }
}" class="cursor-pointer" v-on:click="nav('https://github.com/NetCoreTemplates/razor-press/tree/main/MyApp/_pages')"></file-layout>

Each documentation collection needs a Razor Page to render each page in that collection, which can be configured independently
and include additional features when needed, examples of this include:

- [/Vue/Page.cshtml](https://github.com/NetCoreTemplates/razor-press/tree/main/MyApp/Pages/Vue/Page.cshtml)
- [/CreatorKit/Page.cshtml](https://github.com/NetCoreTemplates/razor-press/tree/main/MyApp/Pages/CreatorKit/Page.cshtml)

They can contain custom Razor Pages as needed, e.g. both [/vue/](/and/) and [/creatorkit/](/creatorkit/) have custom index pages:

- [/Vue/Index.cshtml](https://github.com/NetCoreTemplates/razor-press/tree/main/MyApp/Pages/Vue/Index.cshtml)
- [/CreatorKit/Index.cshtml](https://github.com/NetCoreTemplates/razor-press/tree/main/MyApp/Pages/CreatorKit/Index.cshtml)

If no custom home page is needed, a `/{slug?}` or `/{**slug}` wildcard route can be used to handle a collection's 
index and content pages, e.g:

- [/AutoQuery.cshtml](https://github.com/ServiceStack/docs.servicestack.net/blob/main/MyApp/Pages/AutoQuery.cshtml)
- [/OrmLite.cshtml](https://github.com/ServiceStack/docs.servicestack.net/blob/main/MyApp/Pages/OrmLite.cshtml)
- [/Redis.cshtml](https://github.com/ServiceStack/docs.servicestack.net/blob/main/MyApp/Pages/Redis.cshtml)

Which are used to render all pages in each documentation collection:

- [docs.servicestack.net/autoquery/](https://docs.servicestack.net/autoquery/)
- [docs.servicestack.net/ormlite/](https://docs.servicestack.net/ormlite/)
- [docs.servicestack.net/redis/](https://docs.servicestack.net/redis/)

::: tip
See [Sidebars](/razor-press/sidebars) for how to configure different Sidebar menus for each collection
:::

### Loading Markdown Pages

The code that loads the Pages feature markdown content is in [Markdown.Pages.cs](https://github.com/NetCoreTemplates/razor-press/blob/main/MyApp/Markdown.Pages.cs),
which ultimately just loads Markdown files using the configured [Markdig](https://github.com/xoofx/markdig) pipeline that 
is made available via its `VisiblePages` property which returns all documents **during development** but hides any
**Draft** or content published at a **Future Date** from **production builds**.

## What's New Feature

The [/whatsnew](https://razor-ssg.web-templates.io/whatsnew) page is an example of creating a custom Markdown feature to implement a portfolio or a product releases page
where a new folder is created per release, containing both release date and release or project name, with all features in that release
maintained markdown content sorted in alphabetical order:

<file-layout :files="{
  _whatsnew: {
    '2023-03-08_Animaginary': { _: ['feature1.md'] },
    '2023-03-18_OpenShuttle': { _: ['feature1.md'] },
    '2023-03-28_Planetaria':  { _: ['feature1.md'] },
  }
}" class="cursor-pointer" v-on:click="nav('https://github.com/NetCoreTemplates/razor-press/tree/main/MyApp/_whatsnew')"></file-layout>

What's New follows the same structure as Pages feature which is loaded in:

- [Markdown.WhatsNew.cs](https://github.com/NetCoreTemplates/razor-press/blob/main/MyApp/Markdown.WhatsNew.cs)

and rendered in:
- [WhatsNew.cshtml](https://github.com/NetCoreTemplates/razor-press/blob/main/MyApp/Pages/WhatsNew.cshtml)

## Markdown Videos Feature

Videos is another Markdown powered feature for display collections of YouTube videos populated from a Directory of Markdown Video
pages in [/_videos](https://github.com/NetCoreTemplates/razor-press/tree/main/MyApp/_videos):

<file-layout :files="{
  _videos: {
    projects: { _: ['video1.md','video2.md'] },
    vue:      { _: ['video1.md','video2.md'] },
  }
}" class="cursor-pointer" v-on:click="nav('https://github.com/NetCoreTemplates/razor-press/tree/main/MyApp/_videos')"></file-layout>

Loaded with:
 
- [Markdown.Videos.cs](https://github.com/NetCoreTemplates/razor-press/blob/main/MyApp/Markdown.Videos.cs)

and Rendered with Razor Pages:

- [Shared/VideoGroup.cshtml](https://github.com/NetCoreTemplates/razor-press/blob/main/MyApp/Pages/Shared/VideoGroup.cshtml) - Razor Partial for displaying a Video Collection
- [Videos.cshtml](https://github.com/NetCoreTemplates/razor-press/blob/main/MyApp/Pages/Videos.cshtml) - Razor Page displaying multiple Video Collections

## Metadata APIs Feature

Typically a disadvantage of statically generated websites is the lack of having APIs we can call to query website data 
in a easily readable data format like JSON. However we can also easily support this by also pre-rendering static `*.json` 
data structures along with the pre-rendered website at deployment.

This capability is provided by the new [Markdown.Meta.cs](https://github.com/NetCoreTemplates/razor-ssg/blob/main/MyApp/Markdown.Meta.cs) 
feature which generates multiple projections of the Markdown metadata for each type of content added in every year, e.g:

<file-layout :files="{
  meta: {
    2021: { _: ['all.json','posts.json','videos.json'] },
    2022: { _: ['all.json','posts.json'] },
    2023: { _: ['all.json','pages.json','posts.json','videos.json','whatsnew.json'] },
    _: ['all.json','index.json']
  }
}" class="mb-8 cursor-pointer" v-on:click="nav('https://github.com/NetCoreTemplates/razor-ssg/tree/gh-pages/meta')"></file-layout>

With this you can fetch the metadata of all the new **Blog Posts** added in **2023** from:

[/2023/posts.json](https://razor-ssg.web-templates.io/meta/2023/posts.json)

Or all the website content added in **2023** from:

[/2023/all.json](https://razor-ssg.web-templates.io/meta/2023/all.json)

Or **ALL** the website metadata content from:

[/all.json](https://razor-ssg.web-templates.io/meta/all.json)

This feature makes it possible to support use-cases like CreatorKit's
[Generating Newsletters](https://servicestack.net/creatorkit/portal-mailruns#generating-newsletters) feature which generates 
a Monthly Newsletter Email with all new content added within a specified period.

## General Features

Most unique markdown features are captured in their Markdown's frontmatter metadata, but in general these features
are broadly available for all features:

- **Live Reload** - Latest Markdown content is displayed during **Development**
- **Custom Layouts** - Render post in custom Razor Layout with `layout: _LayoutAlt`
- **Drafts** - Prevent posts being worked on from being published with `draft: true`
- **Future Dates** - Posts with a future date wont be published until that date
- **Order** - Specify custom ordering for a collection pages

### Initializing and Loading Markdown Features

All markdown features are initialized in the same way in [Configure.Ssg.cs](https://github.com/NetCoreTemplates/razor-press/blob/main/MyApp/Configure.Ssg.cs)
where they're registered in ASP.NET Core's IOC and initialized after the App's plugins are loaded
by injecting with the App's [Virtual Files provider](https://docs.servicestack.net/virtual-file-system)
before using it to read from the directory where the markdown content for each feature is maintained:

```csharp
public class ConfigureSsg : IHostingStartup
{
    public void Configure(IWebHostBuilder builder) => builder
        .ConfigureServices(services =>
        {
            context.Configuration.GetSection(nameof(AppConfig)).Bind(AppConfig.Instance);
            services.AddSingleton(AppConfig.Instance);
            services.AddSingleton<RazorPagesEngine>();
            services.AddSingleton<MarkdownPages>();
            services.AddSingleton<MarkdownWhatsNew>();
            services.AddSingleton<MarkdownVideos>();
            services.AddSingleton<MarkdownMeta>();
        })
        .ConfigureAppHost(afterPluginsLoaded: appHost => {
            MarkdigConfig.Set(new MarkdigConfig
            {
                ConfigurePipeline = pipeline =>
                {
                    // Extend Markdig Pipeline
                },
                ConfigureContainers = config =>
                {
                    config.AddBuiltInContainers();
                    // Add Custom Block or Inline containers
                }
            });

            var pages = appHost.Resolve<MarkdownPages>();
            var whatsNew = appHost.Resolve<MarkdownWhatsNew>();
            var videos = appHost.Resolve<MarkdownVideos>();
            var meta = appHost.Resolve<MarkdownMeta>();

            meta.Features = new() { pages, whatsNew, videos };
            meta.Features.ForEach(x => x.VirtualFiles = appHost.VirtualFiles);
            
            pages.LoadFrom("_pages");
            whatsNew.LoadFrom("_whatsnew");
            videos.LoadFrom("_videos");
        });
    });
    //...
}
```

These dependencies are then injected in the feature's Razor Pages to query and render the loaded markdown content.

## Custom Frontmatter

You can extend the `MarkdownFileInfo` type used to maintain the markdown content and metadata of each loaded Markdown file
by adding any additional metadata you want included as C# properties on:

```csharp
// Add additional frontmatter info to include
public class MarkdownFileInfo : MarkdownFileBase
{
}
```

Any additional properties are automatically populated using ServiceStack's
[built-in Automapping](https://docs.servicestack.net/auto-mapping) which includes rich support for converting string frontmatter
values into native .NET types.

## Updating to latest version

You can easily update all the JavaScript dependencies used in
[postinstall.js](https://github.com/NetCoreTemplates/razor-press/blob/main/MyApp/postinstall.js) by running:

:::sh
npm install
:::

This will also update the Markdown features `*.cs` implementations which is delivered as source files instead of an external
NuGet package to enable full customization, easier debugging whilst supporting easy upgrades.

If you do customize any `Markdown*.cs` files, you'll want to exclude them from being updated by removing them from:

```js
const hostFiles = [
  'Markdown.Meta.cs',
  'Markdown.Pages.cs',
  'Markdown.WhatsNew.cs',
  'Markdown.Videos.cs',
  'MarkdownPagesBase.cs',
  'MarkdownTagHelper.cs',
]
```

## Markdown Tag Helper

The included [MarkdownTagHelper.cs](https://github.com/NetCoreTemplates/razor-press/blob/main/MyApp/MarkdownTagHelper.cs) can be used
in hybrid Razor Pages like [About.cshtml](https://github.com/NetCoreTemplates/razor-ssg/blob/main/MyApp/Pages/About.cshtml)
to render the [/about](/about) page which uses the flexibility of Razor Pages and static content component maintained with inline Markdown.

The `<markdown />` tag helper renders plain HTML, which you can apply [Tailwind's @typography](https://tailwindcss.com/docs/typography-plugin)
styles by including **typography.css** and annotating it with your preferred `prose` variant, e.g:

```html
<link rel="stylesheet" href="/css/typography.css">
<markdown class="prose">
  Markdown content...
</markdown>
```


# Static Site Generation (SSG)
Source: https://docs.servicestack.net/razor-press/ssg

All features up till now describes how this template implements a Markdown powered Razor Pages .NET application, where this template
differs in its published output, where instead of a .NET App deployed to a VM or App server it generates static `*.html` files that's
bundled together with `/wwwroot` static assets in the `/dist` folder with:

:::sh
npm run prerender
:::

That can then be previewed by launching a HTTP Server from the `/dist` folder with the built-in npm script:

:::sh
npm run serve
:::

That runs **npx http-server** on `http://localhost:8080` that you can open in a browser to preview the published version of your
site as it would be when hosted on a CDN.

### Static Razor Pages

The static generation functionality works by scanning all your Razor Pages and prerendering the pages with prerendering instructions.

### Pages with Static Routes

Pages with static routes can be marked to be prerendered by annotating it with the `[RenderStatic]` attribute as done in
[About.cshtml](https://github.com/NetCoreTemplates/razor-ssg/blob/main/MyApp/Pages/About.cshtml):

```csharp
@page "/about"
@attribute [RenderStatic]
```

Which saves the pre-rendered page using the pages route with a **.html** suffix, e.g: `/{@page route}.html` whilst pages with static
routes with a trailing `/` are saved to `/{@page route}/index.html`:

```csharp
@page "/vue/"
@attribute [RenderStatic]
```

#### Explicit generated paths

To keep the generated pages in-sync with using the same routes as your Razor Pages in development it's recommended to use the implied
rendered paths, but if preferred you can specify which path the page should render to instead with:

```csharp
@page "/vue/"
@attribute [RenderStatic("/vue/index.html")]
```

### Pages with Dynamic Routes

Prerendering dynamic pages follows [Next.js getStaticProps](https://nextjs.org/docs/basic-features/data-fetching/get-static-props)
convention which you can implement using `IRenderStatic<PageModel>` by returning a Page Model for each page that should be generated
as done in [Vue/Page.cshtml](https://github.com/NetCoreTemplates/razor-press/blob/main/MyApp/Pages/Vue/Page.cshtml) and
[Page.cshtml](https://github.com/NetCoreTemplates/razor-press/blob/main/MyApp/Pages/Page.cshtml):

```csharp
@page "/{slug}"
@model MyApp.Page

@implements IRenderStatic<MyApp.Page>
@functions {
    public List<Page> GetStaticProps(RenderContext ctx)
    {
        var markdown = ctx.Resolve<MarkdownPages>();
        return markdown.GetVisiblePages().Map(page => new Page { Slug = page.Slug! });
    }
}
...
```

In this case it returns a Page Model for every **Visible** markdown page in
[/_pages](https://github.com/NetCoreTemplates/razor-ssg/tree/main/MyApp/_pages) that ends up rendering the following pages in `/dist`:

- `/what-is-razor-press.html`
- `/structure.html`
- `/privacy.html`

### Limitations

The primary limitations for developing statically generated Apps is that a **snapshot** of entire App is generated at deployment,
which prohibits being able to render different content **per request**, e.g. for Authenticated users which would instead require 
executing custom JavaScript after the page loads to dynamically alter the page's initial content.

Otherwise in practice you'll be able develop your Razor Pages utilizing Razor's full feature-set, the primary concessions stem
from Pages being executed in a static context which prohibits pages from returning dynamic content per request, instead any
**"different views"** should be maintained in separate pages.

#### No QueryString Params

As the generated pages should adopt the same routes as your Razor Pages you'll need to avoid relying on **?QueryString** params
and instead capture all required parameters for a page in its **@page route** as done for:

[Posts/Author.cshtml](https://github.com/NetCoreTemplates/razor-ssg/blob/main/MyApp/Pages/Posts/Author.cshtml)

```csharp
@page "/posts/author/{slug}"
@model AuthorModel
@inject MarkdownBlog Blog

@implements IRenderStatic<AuthorModel>
@functions {
    public List<AuthorModel> GetStaticProps(RenderContext ctx) => ctx.Resolve<MarkdownBlog>()
        .AuthorSlugMap.Keys.Map(x => new AuthorModel { Slug = x });
}
...
```

Which lists all posts by an Author, e.g: [/posts/author/lucy-bates](https://razor-ssg.web-templates.io/posts/author/lucy-bates), 
likewise required for:

[Posts/Tagged.cshtml](https://github.com/NetCoreTemplates/razor-ssg/blob/main/MyApp/Pages/Posts/Tagged.cshtml)

```csharp
@page "/posts/tagged/{slug}"
@model TaggedModel
@inject MarkdownBlog Blog

@implements IRenderStatic<TaggedModel>
@functions {
    public List<TaggedModel> GetStaticProps(RenderContext ctx) => ctx.Resolve<MarkdownBlog>()
        .TagSlugMap.Keys.Map(x => new TaggedModel { Slug = x });
}
...
```

Which lists all related posts with a specific tag, e.g: 
[/posts/tagged/markdown](https://razor-ssg.web-templates.io/posts/tagged/markdown), and for:

[Posts/Year.cshtml](https://github.com/NetCoreTemplates/razor-ssg/blob/main/MyApp/Pages/Posts/Year.cshtml)

```csharp
@page "/posts/year/{year}"
@model YearModel
@inject MarkdownBlog Blog

@implements IRenderStatic<YearModel>
@functions {
    public List<YearModel> GetStaticProps(RenderContext ctx) => ctx.Resolve<MarkdownBlog>()
        .VisiblePosts.Select(x => x.Date.GetValueOrDefault().Year)
            .Distinct().Map(x => new YearModel { Year = x });
}

...
```

Which lists all posts published in a specific year, e.g: 
[/posts/year/2023](https://razor-ssg.web-templates.io/posts/year/2023).

Conceivably these "different views" could've been implemented by the same page with different `?author`, `?tag` and `?year`
QueryString params, but need to instead be extracted into different pages to support its statically generated `*.html` outputs.

## Prerendering Task

The **prerender** [AppTask](https://docs.servicestack.net/app-tasks) that pre-renders the entire website is also registered in
[Configure.Ssg.cs](https://github.com/NetCoreTemplates/razor-press/blob/main/MyApp/Configure.Ssg.cs):

```csharp
.ConfigureAppHost(afterAppHostInit: appHost =>
{
    // prerender with: `$ npm run prerender` 
    AppTasks.Register("prerender", args =>
    {
        appHost.Resolve<MarkdownMeta>().RenderToAsync(
            metaDir: appHost.ContentRootDirectory.RealPath.CombineWith("wwwroot/meta"),
            baseUrl: HtmlHelpers.ToAbsoluteContentUrl("")).GetAwaiter().GetResult();
        
        var distDir = appHost.ContentRootDirectory.RealPath.CombineWith("dist");
        if (Directory.Exists(distDir))
            FileSystemVirtualFiles.DeleteDirectory(distDir);
        FileSystemVirtualFiles.CopyAll(
            new DirectoryInfo(appHost.ContentRootDirectory.RealPath.CombineWith("wwwroot")),
            new DirectoryInfo(distDir));
        
        // Render .html redirect files
        RazorSsg.PrerenderRedirectsAsync(appHost.ContentRootDirectory.GetFile("redirects.json"), distDir)
            .GetAwaiter().GetResult();
        
        var razorFiles = appHost.VirtualFiles.GetAllMatchingFiles("*.cshtml");
        RazorSsg.PrerenderAsync(appHost, razorFiles, distDir).GetAwaiter().GetResult();
    });
});
//...
```

Which we can see:
1. Deletes `/dist` folder
2. Copies `/wwwroot` contents into `/dist`
3. [Generates redirect](/razor-press/redirects) `.html` files for all paths in `redirects.json`
4. Passes all App's Razor `*.cshtml` files to `RazorSsg` to do the pre-rendering

Where it processes all pages with `[RenderStatic]` and `IRenderStatic<PageModel>` prerendering instructions to the
specified `/dist` folder.

### Previewing prerendered site

To preview your SSG website, run the prerendered task with:

:::sh
npm run prerender
:::

Which renders your site to `/dist` which you can run a HTTP Server from with:

:::sh
npm run serve
:::

That you can preview with your browser at `http://localhost:8080`.


# Deployments
Source: https://docs.servicestack.net/razor-press/deployments

## Enable GitHub Pages

The included [build.yml](https://github.com/NetCoreTemplates/razor-ssg/blob/main/.github/workflows/build.yml) GitHub Action
takes care of running the prerendered task and deploying it to your Repo's GitHub Pages where you'll need to enable 
GitHub Pages to be hosted from your **gh-pages** branch in your Repository settings:

![](/img/posts/razor-ssg/gh-pages.png)

## Register Custom Domains

You should then register a [Custom domain for GitHub Pages](https://docs.github.com/en/pages/configuring-a-custom-domain-for-your-github-pages-site/about-custom-domains-and-github-pages)
by registering a `CNAME` DNS entry for your preferred Custom Domain, e.g:

| Record | Type | Value | TTL|
| - | - | - | - |
| **mydomain.org** | CNAME | **org_name**.github.io | 3600 |

That you can either [configure in your Repo settings](https://docs.github.com/en/pages/configuring-a-custom-domain-for-your-github-pages-site/managing-a-custom-domain-for-your-github-pages-site#configuring-a-subdomain)
or if you prefer to maintain it with your code-base, save the domain name to `/wwwroot/CNAME`, e.g:

```
www.mydomain.org
```


# Markdown Syntax
Source: https://docs.servicestack.net/razor-press/syntax

## Configuring Markdig

Razor Press uses the high-quality [Markdig](https://github.com/xoofx/markdig) CommonMark compliant implementation 
for its Markdown parsing in .NET.

Each [Markdown*.cs](https://github.com/NetCoreTemplates/razor-press/tree/main/MyApp) feature is able to customize
which [Markdig features](https://github.com/xoofx/markdig#features) it wants to use by providing a custom
`CreatePipeline()` implementation with all the Markdig extensions it needs.

Alternatively the Markdig pipeline can be globally extended for all Markdown features by adding it to `MarkdigConfig` 
pipeline in [Configure.Ssg.cs](https://github.com/NetCoreTemplates/razor-press/blob/main/MyApp/Configure.Ssg.cs):

```csharp
MarkdigConfig.Set(new MarkdigConfig
{
    ConfigurePipeline = pipeline =>
    {
        // Extend Markdig Pipeline
    },
    ConfigureContainers = config =>
    {
        config.AddBuiltInContainers();
        // Add Custom Block or Inline containers
    }
});
```

## Header Anchors

Headers, like above, automatically get anchor links applied with an **id** that's automatically generated from the 
Header text.

### Custom Anchors {#my-anchor}

To specify a custom anchor tag for a heading instead of using the auto-generated one, add a suffix to the heading:

```markdown
### Custom Anchors {#my-anchor}
```

This allows you to link to the heading as `#my-anchor` instead of the default `#custom-anchors`.

### Custom Classes 

Custom Classes can be added to headings with the suffix:

```markdown
### Custom Classes {.my-class}
### Custom Classes {#my-anchor .my-class .my-class2}
```

However to override the default [@tailwindcss/typography](https://tailwindcss.com/docs/typography-plugin) styles applied
to headings they'll need to included within a `not-prose` class which can be done with:

```markdown
:::{.not-prose}
## Custom Class {.text-5xl .font-extrabold .tracking-tight .text-indigo-600}
:::
```

Which generates the HTML:

```html
<div class="not-prose">
    <h2 id="custom-class" class="text-5xl font-extrabold tracking-tight text-indigo-600">
        Custom Class
    </h2>
</div>
```

To render it with the custom tailwind styles we want:

:::{.not-prose}
## Custom Class {.text-5xl .font-extrabold .tracking-tight .text-indigo-600}
:::

## Document Map

A Document Map is created for each Markdown document from its **Heading 2** and **Heading 3** headings, e.g: 

```markdown
## Heading 2
### Heading 3
### Heading 3a

## Heading 2a
```

Which populates the `MarkdownFileInfo.DocumentMap` collection that renders the Document Map on the right column of
each document, that's displayed in devices with larger resolutions that can fit them.

The document map also makes use of the Auto heading anchors for its navigation, that's kept updated as you scroll.

## GitHub-Style Tables

Many [GitHub Flavored Markdown](https://github.github.com/gfm/) syntax is also supported in Markdig like their ASCII
[Tables](https://github.github.com/gfm/#tables-extension-), e.g:

#### Input

```markdown
| Tables        |      Are      |  Cool |
| ------------- | :-----------: | ----: |
| col 3 is      | right-aligned | $1600 |
| col 2 is      |   centered    |   $12 |
| zebra stripes |   are neat    |    $1 |
```

#### Output

| Tables        |      Are      |  Cool |
| ------------- | :-----------: | ----: |
| col 3 is      | right-aligned | $1600 |
| col 2 is      |   centered    |   $12 |
| zebra stripes |   are neat    |    $1 |

Which can be further styled with custom classes:

#### Input

```markdown
:::{.not-prose .table .table-striped}
| Tables        |      Are      |  Cool |
| ------------- | :-----------: | ----: |
| col 3 is      | right-aligned | $1600 |
| col 2 is      |   centered    |   $12 |
| zebra stripes |   are neat    |    $1 |
:::
```

#### Output

:::{.not-prose .table .table-striped}
| Tables        |      Are      |  Cool |
| ------------- | :-----------: | ----: |
| col 3 is      | right-aligned | $1600 |
| col 2 is      |   centered    |   $12 |
| zebra stripes |   are neat    |    $1 |
:::

## Syntax Highlighting in Code Blocks

Razor Press uses [highlight.js](https://highlightjs.org) to highlight code blocks allowing you to add syntax highlighting 
using the same syntax as 
[GitHub Code Blocks](https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/creating-and-highlighting-code-blocks), e.g:

#### Input

:::pre
```csharp
class A<T>
{
    public string? B { get; set; }
}
```
:::

#### Output

```csharp
class A<T>
{
    public string? B { get; set; }
}
```

#### Input

:::pre
```json
{ "A": 1, "B": true }
```
:::

#### Output

```json
{ "A": 1, "B": true }
```

## Markdown Fragments

Markdown fragments should be maintained in `_pages/_include` - a special folder rendered with
[Pages/Includes.cshtml](https://github.com/NetCoreTemplates/razor-press/blob/main/MyApp/Pages/Includes.cshtml) using
an Empty Layout which can be included in other Markdown and Razor Pages or fetched on demand with Ajax
from [/includes/vue/formatters](/includes/vue/formatters).

## Includes

Markdown Fragments can be included inside other markdown documents with the `::include` inline container, e.g:

:::pre
::include vue/formatters.md::
:::

Where it will be replaced with the HTML rendered markdown contents of markdown fragments maintained in `_pages/_include`, 
which in this case embeds the rendered contents of [_pages/_include/vue/formatters.md](https://github.com/NetCoreTemplates/razor-press/blob/main/MyApp/_pages/_include/vue/formatters.md).

### Include Markdown in Razor Pages

Markdown Fragments can be included in Razor Pages using the custom `MarkdownTagHelper.cs` `<markdown/>` tag: 

```html
<markdown include="vue/formatters.md"></markdown>
```

### Inline Markdown in Razor Pages

Alternatively markdown can be rendered inline with:

```html
<markdown>
## Using Formatters

Your App and custom templates can also utilize @servicestack/vue's
[built-in formatting functions](href="/vue/use-formatters).
</markdown>
```


# Custom Markdown Containers
Source: https://docs.servicestack.net/razor-press/containers

[Custom Containers](https://github.com/xoofx/markdig/blob/master/src/Markdig.Tests/Specs/CustomContainerSpecs.md) are a 
popular method for implementing Markdown Extensions for enabling rich, wrist-friendly consistent content in your Markdown documents. 

## Built-in Containers

Most of [VitePress Containers](https://vitepress.dev/guide/markdown#custom-containers) are also implemented in Razor Press, e.g:

#### Input

```markdown
::: info
This is an info box.
:::

::: tip
This is a tip.
:::

::: warning
This is a warning.
:::

::: danger
This is a dangerous warning.
:::
```

#### Output

::: info
This is an info box.
:::

::: tip
This is a tip.
:::

::: warning
This is a warning.
:::

::: danger
This is a dangerous warning.
:::

### Custom Title

You can specify a custom title by appending the text right after the container type:

#### Input

```markdown
::: danger STOP
Danger zone, do not proceed
:::
```

#### Output

::: danger STOP
Danger zone, do not proceed
:::

### Pre

The **pre** container can be used to capture its content in a `<pre>` element instead of it's default markdown rendering:

```markdown
:::pre
...
:::
```

### copy

The **copy** container is ideal for displaying text snippets in a component that allows for easy copying:

#### Input

```markdown
:::copy
Copy Me!
:::
```

#### Output

:::copy
Copy Me!
:::

HTML or XML fragments can also be copied by escaping them first:

#### Input

```markdown
:::copy
`<PackageReference Include="ServiceStack" Version="8.*" />`
:::
```

#### Output

:::copy
`<PackageReference Include="ServiceStack" Version="8.*" />`
:::

### sh

Similarly the **sh** container is ideal for displaying and copying shell commands:

#### Input

```markdown
:::sh
npm run prerender
:::
```

#### Output

:::sh
npm run prerender
:::

## Implementing Block Containers

[Markdig Containers](https://github.com/xoofx/markdig/blob/master/src/Markdig.Tests/Specs/CustomContainerSpecs.md) are a
great way to create rich widgets that can be used directly in Markdown. 

They're useful for ensuring similar content is displayed consistently across all your documentation. A good use-case for
this could be to implement a YouTube component for standardizing how YouTube videos are displayed.

For this example we want to display a YouTube video using just its YouTube **id** and a **title** for the video which we can
capture in the Custom Container: 

```markdown
:::YouTube MRQMBrXi5Sc
Using Razor SSG to Create Websites in GitHub Codespaces
:::
```

Which we can implement with a normal Markdig `HtmlObjectRenderer<CustomContainer>`:

```csharp
public class YouTubeContainer : HtmlObjectRenderer<CustomContainer>
{
    protected override void Write(HtmlRenderer renderer, CustomContainer obj)
    {
        if (obj.Arguments == null)
        {
            renderer.WriteLine($"Missing YouTube Id, Usage :::{obj.Info} <id>");
            return;
        }
        
        renderer.EnsureLine();

        var youtubeId = obj.Arguments!;
        var attrs = obj.TryGetAttributes()!;
        attrs.Classes ??= new();
        attrs.Classes.Add("not-prose text-center");
        
        renderer.Write("<div").WriteAttributes(obj).Write('>');
        renderer.WriteLine("<div class=\"text-3xl font-extrabold tracking-tight\">");
        renderer.WriteChildren(obj);
        renderer.WriteLine("</div>");
        renderer.WriteLine(@$"<div class=""mt-3 flex justify-center"">
            <lite-youtube class=""w-full mx-4 my-4"" width=""560"" height=""315"" videoid=""{youtubeId}"" 
                style=""background-image:url('https://img.youtube.com/vi/{youtubeId}/maxresdefault.jpg')"">
            </lite-youtube>
            </div>
        </div>");
    }
}
```

That should be registered in `Configure.Ssg.cs` with the name we want to use for the container:

```csharp
MarkdigConfig.Set(new MarkdigConfig
{
    ConfigureContainers = config =>
    {
        // Add Custom Block or Inline containers
        config.AddBlockContainer("YouTube", new YouTubeContainer());
    }
});
```

After which it can be used in your Markdown documentation:

#### Input

```markdown
:::YouTube MRQMBrXi5Sc
Using Razor SSG to Create Websites in GitHub Codespaces
:::
```

#### Output

:::YouTube MRQMBrXi5Sc
Using Razor SSG to Create Websites in GitHub Codespaces
:::

### Custom Attributes

Since we use `WriteAttributes(obj)` to emit any attributes we're also able to customize the widget to use a custom **id**
and classes, e.g:

#### Input

```markdown
:::YouTube MRQMBrXi5Sc {.text-indigo-600}
Using Razor SSG to Create Websites in GitHub Codespaces
:::
```

#### Output

:::YouTube MRQMBrXi5Sc {.text-indigo-600}
Using Razor SSG to Create Websites in GitHub Codespaces
:::

## Implementing Inline Containers

Custom Inline Containers are useful when you don't need a to capture a block of content, like if we just want to display
a video without a title, e.g:

```markdown
::YouTube MRQMBrXi5Sc::
```

Inline Containers can be implemented with a Markdig `HtmlObjectRenderer<CustomContainerInline>`, e.g:

```csharp
public class YouTubeInlineContainer : HtmlObjectRenderer<CustomContainerInline>
{
    protected override void Write(HtmlRenderer renderer, CustomContainerInline obj)
    {
        var youtubeId = obj.FirstChild is Markdig.Syntax.Inlines.LiteralInline literalInline
            ? literalInline.Content.AsSpan().RightPart(' ').ToString()
            : null;
        if (string.IsNullOrEmpty(youtubeId))
        {
            renderer.WriteLine($"Missing YouTube Id, Usage ::YouTube <id>::");
            return;
        }
        renderer.WriteLine(@$"<div class=""mt-3 flex justify-center"">
            <lite-youtube class=""w-full mx-4 my-4"" width=""560"" height=""315"" videoid=""{youtubeId}"" 
                style=""background-image:url('https://img.youtube.com/vi/{youtubeId}/maxresdefault.jpg')"">
            </lite-youtube>
        </div>");
    }
}
```

That can be registered in `Configure.Ssg.cs` with:

```csharp
MarkdigConfig.Set(new MarkdigConfig
{
    ConfigureContainers = config =>
    {
        // Add Custom Block or Inline containers
        config.AddInlineContainer("YouTube", new YouTubeInlineContainer());
    }
});
```

Where it can then be used in your Markdown documentation:

#### Input

```markdown
::YouTube MRQMBrXi5Sc::
```

#### Output

::YouTube MRQMBrXi5Sc::


# Using Vue in Markdown
Source: https://docs.servicestack.net/razor-press/vue-in-markdown

## Progressive Enhancement

Thanks to the Vue's elegant approach for progressively enhancing HTML content, Razor Press markdown documents can 
embed interactive reactive Vue components directly in Markdown which makes it possible to document the
[Vue Tailwind Component Library](/vue/autoquerygrid) and its interactive component examples, embedded directly in Markdown. 

## Markdown Documents are Vue Apps

We can embed Vue components directly in Markdown simply because all Markdown Documents are themselves Vue Apps, which by default 
are created with the same [/mjs/app.mjs](https://github.com/NetCoreTemplates/razor-press/blob/main/MyApp/wwwroot/mjs/app.mjs)
configuration that all Razor Pages uses. This allows using any 
[Vue DOM syntax](https://vuejs.org/guide/essentials/template-syntax.html) or global Vue components directly in Markdown, in the same
way that they're used in Vue Apps defined in Razor or HTML pages.


For example we can display the 
[GettingStarted.mjs](https://github.com/NetCoreTemplates/razor-press/blob/main/MyApp/wwwroot/mjs/components/GettingStarted.mjs) component
that's on the home page with:

#### Input

```html
<getting-started template="razor-press"></getting-started>
```

#### Output

<getting-started template="razor-press"></getting-started>

## Markdown with Custom Vue Apps

Pages that need advanced functionality beyond what's registered in the global App configuration can add additional
functionality by adding a JavaScript module with the same **path** and **filename** of the markdown page with
an `.mjs` extension:

```
/wwwroot/pages/<path>/<file>.mjs
```

This is utilized by most [/pages/vue](https://github.com/NetCoreTemplates/razor-press/tree/main/MyApp/wwwroot/pages/vue)
Markdown pages to handle the unique requirements of each page's live examples.

E.g. the [autoquerygrid.mjs](https://github.com/NetCoreTemplates/razor-press/blob/main/MyApp/wwwroot/pages/vue/autoquerygrid.mjs)
uses a custom Vue App component that registers a custom **client** dependency and **Responsive** and **CustomBooking**
components that are only used in 
[/vue/autoquerygrid.md](https://github.com/NetCoreTemplates/razor-press/blob/main/MyApp/_pages/vue/autoquerygrid.md)
page to render the interactive live examples in the [/vue/autoquerygrid](/vue/autoquerygrid) page:

```js
import { onMounted } from "vue"
import { Authenticate } from "./dtos.mjs"
import { useAuth, useClient } from '@servicestack/vue'
import { JsonServiceClient } from "@servicestack/client"
import Responsive from "./autoquerygrid/Responsive.mjs"
import CustomBooking from "./autoquerygrid/CustomBooking.mjs"

export default {
    install(app) {
        app.provide('client', new JsonServiceClient('https://blazor-gallery.jamstacks.net'))
    },
    components: {
        Responsive,
        CustomBooking,
    },
    setup() {
        const client = useClient()
        
        onMounted(async () => {
            const api = await client.api(new Authenticate({ 
                provider: 'credentials', userName:'admin@email.com', password:'p@55wOrd' }))
            if (api.succeeded) {
                const { signIn } = useAuth()
                signIn(api.response)
            }
        })
        return { }
    }
}
```

### Convert from Vue script setup

This is roughly equivalent to the sample below if coming from VitePress or other npm Vue project that uses Vue's 
compile-time syntactic [`<script setup>`](https://vuejs.org/api/sfc-script-setup.html):

```html
<script setup>
import { onMounted } from "vue"
import { Authenticate } from "./dtos.ts"
import { useAuth, useClient } from '@servicestack/vue'
import { JsonApiClient } from "@servicestack/client"
import Responsive from "./autoquerygrid/Responsive.vue"
import CustomBooking from "./autoquerygrid/CustomBooking.vue"

onMounted(async () => {
    const client = useClient()
    const api = await client.api(new Authenticate({ 
        provider: 'credentials', userName:'admin@email.com', password:'p@55wOrd' }))
    if (api.succeeded) {
        const { signIn } = useAuth()
        signIn(api.response)
    }
})
</script>
```

## Custom Styles in Markdown

If needed custom styles can also be added for individual pages by adding a `.css` file at the following location:

```
/wwwroot/pages/<path>/<file>.css
```


# Sidebars
Source: https://docs.servicestack.net/razor-press/sidebars

## Main Sidebar

The sidebar defines the main navigation for your documentation, you can configure the sidebar menu in `_pages/sidebar.json`
which adopts the same structure as [VitePress Sidebars](https://vitepress.dev/reference/default-theme-sidebar#sidebar), e.g:

```json
[
  {
    "text": "Introduction",
    "link": "/",
    "children": [
      {
        "text": "What is Razor Press?",
        "link": "/what-is-razor-press"
      },
      {
        "text": "Structure",
        "link": "/structure"
      }
    ]
  },
  {
    "text": "Markdown",
    "children": [
      {
        "text": "Sidebars",
        "link": "/sidebars"
      }
    ]
  }
]
```

## Navigation Headings

Primary navigation headings can optionally have `"links"` to make them linkable and `"icon"` to render them
with a custom icon, e.g:

```json
{
    "icon": "<svg xmlns='http://www.w3.org/2000/svg'>....</svg>", 
    "text": "Markdown",
    "link": "/markdown/",
    "children": [
    ]
}
```

## Documentation Group Sidebars

If your happy to use the same document page title for its menu item label, you can use an implicitly generated Sidebar 
navigation like [/creatorkit/](/creatorkit/about) uses for its Sidebar navigation which can be ordered with the **order**
index defined in its frontmatter, e.g:

```yaml
title: About
order: 1
```

Which can also be grouped into different navigation sections using the **group** frontmatter, e.g:

```yaml
title: Overview
order: 6
group: Portal
```

### Custom Sidebars

For more flexibility a custom sidebar can be defined for each group by defining a `sidebar.json` in its folder 
`_pages/<group>/sidebar.json` which [/vue/](/vue/install) uses for its explicit Sidebar Navigation, e.g:

```json
[
  {
    "text": "Vue",
    "link": "/vue",
    "children": [
      {
        "text": "Install",
        "link": "/vue/install"
      }
    ]
  },
  {
    "text": "Component Gallery",
    "children": [
      {
        "text": "AutoQueryGrid",
        "link": "/vue/autoquerygrid"
      }
    ]
  }
]
```


# Redirects
Source: https://docs.servicestack.net/razor-press/redirects

## Static HTML Page Redirects

The [redirects.json](https://github.com/NetCoreTemplates/razor-press/tree/main/MyApp/redirects.json) file allows you to
define a map of routes with what routes they should redirect to, e.g:

```json
{
    "/creatorkit": "/creatorkit/",
    "/vue": "/vue/"
}
```

When prerendering this will generate a `*.html` page for each mapping containing a 
[meta refresh](https://www.w3.org/TR/WCAG20-TECHS/H76.html) to perform a client-side redirect to the new route which will
work in all static file hosts and CDNs like GitHub Pages CDN.

Where it will redirect invalid routes like [/vue](https://razor-press.web-templates.io/vue) and
[/creatorkit](https://razor-press.web-templates.io/creatorkit) to their appropriate `/vue/` and `/creatorkit/` paths.

## Redirects in AWS S3

Alternatively if you deploy your static site to a smarter static file host like an AWS S3 bucket you can perform these
redirects on the server by defining them in 
[Custom Redirection Rules](https://docs.aws.amazon.com/AmazonS3/latest/userguide/how-to-page-redirect.html).


# Typesense Real-Time Search
Source: https://docs.servicestack.net/razor-press/typesense

Many popular Open Source products use [Algolia DocSearch](https://docsearch.algolia.com) to power their real-time search
features, however, it's a less appealing product for commercial products which is a paid service with a per request 
pricing model that made it difficult to determine what costs would be in the long run.

<a class="flex flex-col items-center my-8" href="https://typesense.org">
    <svg fill="none" height="56" viewBox="0 0 250 56" width="250" xmlns="http://www.w3.org/2000/svg">
        <g fill="#1035bc"><path d="m15.0736 15.8466c.1105.5522.1657 1.0859.1657 1.6013 0 .4785-.0552.9938-.1657 1.546l-7.01225-.0552v18.5521c0 1.546.71779 2.319 2.15335 2.319h4.1963c.2577.6258.3865 1.2516.3865 1.8773 0 .6258-.0368 1.0123-.1104 1.1595-1.6932.2209-3.4417.3313-5.24538.3313-3.57055 0-5.35583-1.5276-5.35583-4.5828v-19.6564l-3.920246.0552c-.1104293-.5522-.165644-1.0675-.165644-1.546 0-.5154.0552147-1.0491.165644-1.6013l3.920246.0552v-5.7975c0-.99387.14724-1.69325.44172-2.09816.29448-.44172.86503-.66258 1.71165-.66258h1.4908l.33129.33129v8.28225z"/><path d="m41.7915 16.1227-7.5644 25.8957c-1.3988 4.7485-2.8896 8.0982-4.4724 10.0491s-3.9571 2.9264-7.1227 2.9264c-1.6196 0-3.1104-.2393-4.4724-.7178-.1104-1.0307.1841-2.0246.8834-2.9816 1.1411.4049 2.3559.6073 3.6442.6073 1.9509 0 3.4417-.6625 4.4724-1.9877 1.0307-1.3251 1.9693-3.3865 2.816-6.184l.1656-.5522c-.9571-.0736-1.6932-.2945-2.2086-.6626-.4785-.3681-.8834-1.049-1.2147-2.0429l-7.7301-24.2945c1.1411-.4785 1.9509-.7178 2.4295-.7178 1.0675 0 1.7853.6442 2.1534 1.9325l4.3619 13.8589c.1473.4418.9939 3.3129 2.5399 8.6135.0736.2577.2577.3865.5521.3865l6.7362-24.4049c.4786-.1472 1.1043-.2208 1.8773-.2208.8099 0 1.4908.1104 2.043.3313z"/><path d="m52.4009 41.135v10.9325c0 .9938-.1472 1.6932-.4417 2.0981-.2945.4418-.8834.6626-1.7669.6626h-1.4908l-.3312-.3313v-38.4846l.3312-.3313h1.4356c.8835 0 1.4724.2392 1.7669.7178.3313.4417.4969 1.1779.4969 2.2086v.276c2.2086-2.4662 4.8405-3.6994 7.8957-3.6994 3.1289 0 5.4847 1.27 7.0675 3.8099 1.5828 2.503 2.3743 5.9816 2.3743 10.4356 0 2.1717-.2945 4.1226-.8835 5.8527-.5521 1.7301-1.3067 3.2025-2.2638 4.4172-.9202 1.1779-1.9877 2.0981-3.2024 2.7607-1.2148.6258-2.4663.9387-3.7546.9387-2.5399 0-4.951-.7546-7.2332-2.2638zm0-17.9448v14.1902c2.2454 1.6564 4.362 2.4846 6.3497 2.4846 1.9878 0 3.6258-.8834 4.9141-2.6503 1.2884-1.7668 1.9326-4.4356 1.9326-8.0061 0-1.7669-.1657-3.2945-.497-4.5828-.2945-1.3252-.6994-2.4111-1.2147-3.2577-.5153-.8834-1.1227-1.5276-1.8221-1.9325-.6626-.4417-1.3804-.6626-2.1534-.6626-1.4724 0-2.8711.3865-4.1963 1.1595-1.3251.773-2.4294 1.8589-3.3129 3.2577z"/><path d="m97.6973 30.6442h-17.1166c.1841 6.2576 2.5583 9.3865 7.1227 9.3865 2.5031 0 5.1718-.773 8.0061-2.319.8099.7361 1.3068 1.6748 1.4909 2.8159-3.0184 2.0614-6.405 3.092-10.1596 3.092-1.9141 0-3.5521-.3497-4.9141-1.049-1.3619-.7362-2.4846-1.7301-3.3681-2.9816-.8466-1.2884-1.4724-2.7976-1.8773-4.5277-.4049-1.73-.6073-3.6257-.6073-5.6871 0-2.0981.2392-4.0122.7178-5.7423.5153-1.7301 1.2515-3.2209 2.2085-4.4724.9571-1.2515 2.0982-2.227 3.4234-2.9264 1.3619-.6994 2.9079-1.0491 4.638-1.0491 1.6932 0 3.2025.3129 4.5276.9387 1.362.589 2.4847 1.4172 3.3681 2.4847.9203 1.0306 1.6196 2.2822 2.0982 3.7546.4785 1.4355.7178 2.9816.7178 4.638 0 .6626-.0369 1.3067-.1105 1.9325-.0368.589-.092 1.1595-.1656 1.7117zm-17.1166-3.1473h13.2516v-.7178c0-2.5398-.5338-4.5828-1.6013-6.1288s-2.6687-2.319-4.8037-2.319c-2.0981 0-3.7362.8282-4.9141 2.4847-1.1411 1.6564-1.7852 3.8834-1.9325 6.6809z"/><path d="m103.381 41.0245c.036-.8098.257-1.6932.662-2.6503.442-.9938.939-1.7668 1.491-2.319 2.908 1.5828 5.466 2.3743 7.675 2.3743 1.214 0 2.19-.2393 2.926-.7178.773-.4786 1.16-1.1227 1.16-1.9326 0-1.2883-.994-2.319-2.982-3.092l-3.092-1.1595c-4.638-1.6932-6.957-4.3988-6.957-8.1166 0-1.3251.239-2.503.718-3.5337.515-1.0675 1.214-1.9693 2.098-2.7055.92-.773 2.006-1.362 3.258-1.7669 1.251-.4049 2.65-.6074 4.196-.6074.699 0 1.472.0553 2.319.1657.883.1104 1.767.2761 2.65.4969.884.1841 1.73.4049 2.54.6626s1.509.5337 2.098.8282c0 .9203-.184 1.8773-.552 2.8712s-.865 1.73-1.491 2.2086c-2.908-1.2884-5.429-1.9325-7.564-1.9325-.957 0-1.712.2392-2.264.7178-.552.4417-.828 1.0306-.828 1.7668 0 1.1411.92 2.043 2.761 2.7055l3.368 1.2148c2.429.8466 4.233 2.0061 5.411 3.4785s1.767 3.184 1.767 5.135c0 2.6135-.976 4.7116-2.927 6.2944-1.951 1.5461-4.748 2.3191-8.392 2.3191-3.571 0-6.921-.9019-10.049-2.7056z"/><path d="m151.772 31.5828h-15.239c.111 2.0246.571 3.6258 1.38 4.8037.847 1.1411 2.301 1.7117 4.362 1.7117 2.135 0 4.583-.6258 7.344-1.8773 1.067 1.1042 1.748 2.5582 2.043 4.3619-2.945 2.0982-6.479 3.1473-10.601 3.1473-3.902 0-6.865-1.1964-8.89-3.589-1.988-2.4294-2.981-6.0184-2.981-10.7669 0-2.2086.257-4.1963.773-5.9632.515-1.8036 1.269-3.3312 2.263-4.5828.994-1.2883 2.209-2.2822 3.644-2.9816 1.436-.6994 3.074-1.0491 4.915-1.0491 1.877 0 3.533.2945 4.969.8835 1.436.5521 2.65 1.3619 3.644 2.4294.994 1.0307 1.73 2.2638 2.209 3.6994.515 1.4356.773 3 .773 4.6933 0 .9202-.056 1.8036-.166 2.6503-.11.8098-.258 1.6196-.442 2.4294zm-10.656-11.5951c-2.871 0-4.417 2.1718-4.638 6.5154h9.165v-.6626c0-1.7669-.368-3.1841-1.104-4.2515-.736-1.0675-1.877-1.6013-3.423-1.6013z"/><path d="m182.033 24.5153v12.0368c0 2.3559.386 4.1043 1.159 5.2454-1.178 1.0307-2.595 1.5461-4.251 1.5461-1.583 0-2.669-.3497-3.258-1.0491-.589-.7362-.884-1.8773-.884-3.4233v-12.8651c0-1.6564-.202-2.8159-.607-3.4785s-1.159-.9939-2.264-.9939c-1.951 0-3.773.8835-5.466 2.6504v18.773c-.552.1104-1.141.184-1.767.2208-.589.0368-1.196.0552-1.822.0552s-1.251-.0184-1.877-.0552c-.589-.0368-1.16-.1104-1.712-.2208v-27.3313l.331-.3865h2.761c2.062 0 3.35 1.1043 3.865 3.3128 2.687-2.319 5.356-3.4785 8.006-3.4785 2.651 0 4.602.8651 5.853 2.5951 1.288 1.6933 1.933 3.9755 1.933 6.8466z"/><path d="m187.825 41.0245c.036-.8098.257-1.6932.662-2.6503.442-.9938.939-1.7668 1.491-2.319 2.908 1.5828 5.466 2.3743 7.675 2.3743 1.214 0 2.19-.2393 2.926-.7178.773-.4786 1.16-1.1227 1.16-1.9326 0-1.2883-.994-2.319-2.982-3.092l-3.092-1.1595c-4.638-1.6932-6.957-4.3988-6.957-8.1166 0-1.3251.239-2.503.718-3.5337.515-1.0675 1.214-1.9693 2.098-2.7055.92-.773 2.006-1.362 3.258-1.7669 1.251-.4049 2.65-.6074 4.196-.6074.699 0 1.472.0553 2.319.1657.883.1104 1.767.2761 2.65.4969.884.1841 1.73.4049 2.54.6626s1.509.5337 2.098.8282c0 .9203-.184 1.8773-.552 2.8712s-.865 1.73-1.491 2.2086c-2.908-1.2884-5.429-1.9325-7.564-1.9325-.957 0-1.712.2392-2.264.7178-.552.4417-.828 1.0306-.828 1.7668 0 1.1411.92 2.043 2.761 2.7055l3.368 1.2148c2.429.8466 4.233 2.0061 5.411 3.4785s1.767 3.184 1.767 5.135c0 2.6135-.976 4.7116-2.927 6.2944-1.951 1.5461-4.748 2.3191-8.392 2.3191-3.571 0-6.921-.9019-10.049-2.7056z"/><path d="m236.216 31.5828h-15.239c.111 2.0246.571 3.6258 1.38 4.8037.847 1.1411 2.301 1.7117 4.362 1.7117 2.135 0 4.583-.6258 7.344-1.8773 1.067 1.1042 1.748 2.5582 2.043 4.3619-2.945 2.0982-6.479 3.1473-10.601 3.1473-3.902 0-6.865-1.1964-8.89-3.589-1.988-2.4294-2.981-6.0184-2.981-10.7669 0-2.2086.257-4.1963.773-5.9632.515-1.8036 1.269-3.3312 2.263-4.5828.994-1.2883 2.209-2.2822 3.645-2.9816 1.435-.6994 3.073-1.0491 4.914-1.0491 1.877 0 3.533.2945 4.969.8835 1.436.5521 2.65 1.3619 3.644 2.4294.994 1.0307 1.73 2.2638 2.209 3.6994.515 1.4356.773 3 .773 4.6933 0 .9202-.055 1.8036-.166 2.6503-.11.8098-.258 1.6196-.442 2.4294zm-10.656-11.5951c-2.871 0-4.417 2.1718-4.638 6.5154h9.166v-.6626c0-1.7669-.369-3.1841-1.105-4.2515-.736-1.0675-1.877-1.6013-3.423-1.6013z"/><path d="m244.777 50.6871v-50.521455c.552-.1104299 1.178-.165645 1.878-.165645.736 0 1.417.0552151 2.042.165645v50.521455c-.625.1104-1.306.1657-2.042.1657-.7 0-1.326-.0553-1.878-.1657z"/></g>
    </svg>
</a>

We discovered [Typesense](https://typesense.org) as an appealing alternative which offers [simple cost-effective cloud hosting](https://cloud.typesense.org)
but even better, they also have an easy to use open source option for self-hosting or evaluation. Given its effortless integration, 
simplicity-focus and end-user UX, it quickly became our preferred way to navigate [docs.servicestack.net](https://docs.servicestack.net). 

To make it easier to adopt Typesense's amazing OSS Search product we've documented the approach we use to create and 
deploy an index of our site automatically using GitHub Actions that you could also utilize in your Razor Press websites.

Documentation search is a common use case which Typesense caters for with their 
[typesense-docsearch-scraper](https://github.com/typesense/typesense-docsearch-scraper) - a utility designed to easily 
scrape a website and post the results to a Typesense server to create a fast searchable index.

## Self hosting option

We recommend using running their [easy to use Docker image](https://hub.docker.com/r/typesense/typesense/) to run
an instance of their Typesense server, which you can run in a **t2.small** AWS EC2 instance or in a 
[Hetzner Cloud](https://www.hetzner.com/cloud) VM for a more cost effective option.

Trying it locally, we used the following commands to spin up a local Typesense server ready to scrape out docs site.

```sh
mkdir /tmp/typesense-data
docker run -p 8108:8108 -v/tmp/data:/data typesense/typesense:0.21.0 \
    --data-dir /data --api-key=<temp-admin-api-key> --enable-cors
```

To check that the server is running, we can open a browser at `/health` and we get back 200 OK with `ok: true`.

The Typesense server has a [REST API](https://typesense.org/docs/0.21.0/api) which can be used to manage the indexes you create. 
Or if you use their cloud offering, you can use their web dashboard to monitor and manage your index data.

## Populating the index

With your local server is running, you can scrape your docs site using the 
[typesense-docsearch-scraper](https://github.com/typesense/typesense-docsearch-scraper). 
This needs some configuration to tell the scraper:

- Where the Typesense server is
- How to authenticate with the Typesense server
- Where the docs website is
- Rules for the scraper to follow extracting information from the docs website

These [pieces of configuration come from 2 sources](https://github.com/ServiceStack/docs/tree/master/search-server/typesense-scraper). 
A [.env](https://github.com/ServiceStack/docs/blob/master/search-server/typesense-scraper/typesense-scraper.env) file 
related to the Typesense server information and
a [.json](https://github.com/ServiceStack/docs/blob/master/search-server/typesense-scraper/typesense-scraper-config.json)
file related to what site will be getting scraped.

With a Typesense running locally on port **8108**, we configure the `.env` file with the following information:

```
TYPESENSE_API_KEY=${TYPESENSE_API_KEY}
TYPESENSE_HOST=localhost
TYPESENSE_PORT=8108
TYPESENSE_PROTOCOL=http
```

Next, we have to configure the `.json` config for the scraper. 
The **typesense-docsearch-scraper** has [an example of this](https://github.com/typesense/typesense-docsearch-scraper/blob/master/configs/public/typesense_docs.json)
config in their repository.

The default selectors will need to match the your websites HTML, which for Razor Press sites can start with the configuration,
updated with your website domains:

```json
{
  "index_name": "typesense_docs",
  "allowed_domains": ["docs.servicestack.net"],
  "start_urls": [
    {
      "url": "https://docs.servicestack.net/"
    }
  ],
  "selectors": {
    "default": {
      "lvl0": "h1",
      "lvl1": ".content h2",
      "lvl2": ".content h3",
      "lvl3": ".content h4",
      "lvl4": ".content h5",
      "text": ".content p, .content ul li, .content table tbody tr"
    }
  },
  "scrape_start_urls": false,
  "strip_chars": " .,;:#"
}
```

With both the configuration files ready to use, we can run the scraper itself. The scraper is also available using the 
docker image `typesense/docsearch-scraper` which we can pass our configuration to, using the following command:

```sh
docker run -it --env-file typesense-scraper.env \
    -e "CONFIG=$(cat typesense-scraper-config.json | jq -r tostring)" \
    typesense/docsearch-scraper
```

Here `-i` is used to reference a local `--env-file` and use `cat` and `jq` used to populate the `CONFIG` environment variable 
with the `.json` config file.

## Docker networking

We had a slight issue here since the scraper itself is running in Docker via WSL and `localhost` doesn't resolve to our 
host machine to find the Typesense server also running in Docker.
Instead we need to point the scraper to the Typesense server using the Docker local IP address space of `172.17.0.0/16` 
for it to resolve without additional configuration.

We can see in the output of the Typesense server that it is running using `172.17.0.2`. We can swap the `localhost` 
with this IP address after which we see the communication between the servers flowing:

```
DEBUG:typesense.api_call:Making post /collections/typesense_docs_1635392168/documents/import
DEBUG:typesense.api_call:Try 1 to node 172.17.0.2:8108 -- healthy? True
DEBUG:urllib3.connectionpool:Starting new HTTP connection (1): 172.17.0.2:8108
DEBUG:urllib3.connectionpool:http://172.17.0.2:8108 "POST /collections/typesense_docs_1635392168/documents/import HTTP/1.1" 200 None
DEBUG:typesense.api_call:172.17.0.2:8108 is healthy. Status code: 200
> DocSearch: https://docs.servicestack.net/azure 22 records)
DEBUG:typesense.api_call:Making post /collections/typesense_docs_1635392168/documents/import
DEBUG:typesense.api_call:Try 1 to node 172.17.0.2:8108 -- healthy? True
DEBUG:urllib3.connectionpool:Starting new HTTP connection (1): 172.17.0.2:8108
DEBUG:urllib3.connectionpool:http://172.17.0.2:8108 "POST /collections/typesense_docs_1635392168/documents/import HTTP/1.1" 200 None
```

The scraper crawls the docs site following all the links in the same domain to get a full picture of all the content of our docs site.
This takes a minute or so, and in the end we can see in the Typesense sever output that we now have **committed_index: 443**.

```
_index: 443, applying_index: 0, pending_index: 0, disk_index: 443, pending_queue_size: 0, local_sequence: 44671
I20211028 03:39:40.402626   328 raft_server.h:58] Peer refresh succeeded!
```

## Searching content

After you have a Typesense server with an index full of content, you'll want to be able to use it to search your docs site.
You can query the index using `curl` which needs to known 3 key pieces of information:

- Collection name, eg `typesense_docs`
- Query term, `?q=test`
- What to query, `&query_by=content`

```sh
curl -H 'x-typesense-api-key: <apikey>' \
    'http://localhost:8108/collections/typesense_docs/documents/search?q=test&query_by=content'
```

The collection name and `query_by` come from how the scraper was configured. The scraper was posting data to the
`typesense_docs` collection and populating various fields, eg `content`.

Which as it returns JSON can be easily queried in JavaScript using **fetch**:

```js
fetch('http://localhost:8108/collections/typesense_docs/documents/search?q='
    + encodeURIComponent(query) + '&query_by=content', {
    headers: {
        // Search only API key for Typesense.
        'x-typesense-api-key': 'TYPESENSE_SEARCH_ONLY_API_KEY'
    }
})
```

In the above we have also used a different name for the API key token, this is important since the `--api-key` specified to the running Typesense server is the admin API key. You don't want to expose this to a browser client since they will have the ability to create,update and delete your collections or documents.

Instead we want to generate a "Search only" API key that is safe to share on a browser client. This can be done using the Admin API key and the following REST API call to the Typesense server.

```bash
curl 'http://localhost:8108/keys' -X POST \
  -H "X-TYPESENSE-API-KEY: ${TYPESENSE_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{"description": "Search only","actions": ["documents:search"],"collections":["*"]}'
```

Now we can share this generated key safely to be used with any of our browser clients.

## Keeping the index updated

A problem that becomes apparent when running the scraper is that it increases the size of the index since it currently 
doesn't detect and update existing documents. It wasn't clear if this is possible to configure from the current scraper, 
but we needed a way to achieve the following goals:

- Update the search index automatically soon after docs have been changed
- Don't let the index grow too big to avoid manual intervention
- Have high uptime so documentation search is always available

Typesense server itself performs extremely well, so a full update from the scraper doesn't generate an amount of load. 
However, every additional scrape uses additional disk space and memory that will eventually require periodically 
resetting and repopulating the index.

One option is to switch to a new collection everytime the documentation is updated and delete the old collection,
adopting a workflow that looks something like: 

1. Docs are updated
2. Publish updated docs
3. Create new collection, store new and old names
4. Scrape updated docs
5. Update client with new collection
6. Delete old collection

However this would require orchestration across a number of GitHub Action workflows which we anticipated would be 
fragile and non-deterministic as to how long it will take to scrape, update, and deploy our changes.

## Read-only Docker container

The approach we ended up adopting was to develop and deploy read only Typesense Docker images containing an immutable copy 
of the index data in it as part of the GitHub Action deployments.

In the case of Typesense, when it starts up, it reads from its `data` directory from disk to populate the index in 
memory and since our index is small and only updates when our documentation is updated, we can simplify the management 
of the index data by **baking it into the docker image**.

This has several key advantages.

- Disaster recovery doesn't need any additional data management.
- Shipping an updated index is a normal ECS deployment.
- Zero down time deployments.
- Index is of a fixed size once deployed.

## Typesense Performance

Search on our documentation site is a very light workload for Typesense. Running as an ECS service on a 2 vCPU instance, 
the service struggled to get close to **1%** whilst serving constant typeahead searching.

![](https://servicestack.net/img/posts/typesense/typesense-cpu-utilization.png)

Since our docs site index is small (500 pages), the memory footprint is also tiny and stable at **~50MB** or **~10%** of the the 
service's soft memory limit.

![](https://servicestack.net/img/posts/typesense/typesense-memory-utilization.png)

This means we will be able to host this using a single EC2 instance among various other or the ServiceStack hosted 
example applications and use the same deployment patterns we've shared in our
[GitHub Actions templates](https://docs.servicestack.net/mix-github-actions-aws-ecs).

[![](https://raw.githubusercontent.com/ServiceStack/docs/master/docs/images/mix/cloudcraft-host-digram-release-ecr-aws.png)](https://docs.servicestack.net/mix-github-actions-aws-ecs)

Whilst this approach of shipping an index along with the Docker image isn't practical for large or 'living' indexes, 
many small to medium-sized documentation sites would likely benefit from the simplified approach of deploying readonly
Docker images.

## GitHub Actions Workflow

To create our own Docker image for our search server we need to perform the following tasks in our GitHub Action:

1. Run a local Typesense server in the GitHub Action using Docker
2. Scrape our hosted docs populating the local Typesense server
3. Copy the `data` folder of our local Typesense server during `docker build`

Which is done with:

```sh
mkdir -p ${GITHUB_WORKSPACE}/typesense-data
cp ./search-server/typesense-server/Dockerfile ${GITHUB_WORKSPACE}/typesense-data/Dockerfile
cp ./search-server/typesense-scraper/typesense-scraper-config.json typesense-scraper-config.json
envsubst < "./search-server/typesense-scraper/typesense-scraper.env" > "typesense-scraper-updated.env"
docker run -d -p 8108:8108 -v ${GITHUB_WORKSPACE}/typesense-data/data:/data \
    typesense/typesense:0.21.0 --data-dir /data --api-key=${TYPESENSE_API_KEY} --enable-cors &
# wait for typesense initialization
sleep 5
docker run -i --env-file typesense-scraper-updated.env \
    -e "CONFIG=$(cat typesense-scraper-config.json | jq -r tostring)" typesense/docsearch-scraper
```

Our `Dockerfile` then takes this data from the `data` folder during build.

```Dockerfile
FROM typesense/typesense:0.21.0

COPY ./data /data
```

To avoid updating our search client between updates we also want to use the same **search-only API Key** everytime 
a new server is created. This can be achieved by specifying `value` in the `POST` command sent to the local Typesense server:

```sh
curl 'http://172.17.0.2:8108/keys' -X POST \
  -H "X-TYPESENSE-API-KEY: ${TYPESENSE_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{"value":<search-api-key>,"description":"Search only","actions":["documents:search"],"collections":["*"]}'
```

If you're interested in adopting a similar approach you can find the whole GitHub Action workflow in our 
[search-index-update.yml](https://github.com/ServiceStack/docs/blob/master/.github/workflows/search-index-update.yml) 
workflow.

## Search UI Dialog

After docs are indexed the only thing left to do is display the results. We set out to create a comparable UX to
Algolia's doc search dialog which we've implemented in the
[Typesense.mjs](https://github.com/ServiceStack/docs.servicestack.net/blob/main/MyApp/wwwroot/mjs/components/Typesense.mjs)
Vue component which you can register as a global component in your 
[app.mjs](https://github.com/ServiceStack/docs.servicestack.net/blob/main/MyApp/wwwroot/mjs/app.mjs):


```js
import Typesense from "./components/Typesense.mjs"

const Components = {
    //...
    Typesense,
}
```

Which renders as a **Search Button** that we've added next to our **Dark Mode Toggle** button in our 
[Header.cshtml](https://github.com/ServiceStack/docs.servicestack.net/blob/main/MyApp/Pages/Shared/Header.cshtml):

```html
<div class="hidden sm:ml-6 sm:flex sm:items-center">
    <typesense></typesense>
    <dark-mode-toggle class="ml-2 w-10"></dark-mode-toggle>
</div>
```

![](https://servicestack.net/img/posts/typesense/typesense-header.png)

The button also encapsulates the dialog component which uses Typesense REST API to query to our typesense instance:

```js
fetch('https://search.docs.servicestack.net/collections/typesense_docs/documents/search?q='
  + encodeURIComponent(query.value)
  + '&query_by=content,hierarchy.lvl0,hierarchy.lvl1,hierarchy.lvl2,hierarchy.lvl3&group_by=hierarchy.lvl0', {
    headers: {
      // Search only API key for Typesense.
      'x-typesense-api-key': 'TYPESENSE_SEARCH_ONLY_API_KEY'
    }
})
```

This instructs Typesense to search through each documents content and h1-3 headings, grouping results by its page title.
Refer to the [Typesense API Search Reference](https://typesense.org/docs/0.21.0/api/documents.html#search) to learn how
to further fine-tune search results for your use-case.

## Search Results

![](https://servicestack.net/img/posts/typesense/typesense-dart.gif)

The results are **excellent**, [see for yourself](https://docs.servicestack.net) by using the search at the top right or 
using `Ctrl+K` shortcut key on [docs.servicestack.net](https://docs.servicestack.net).

It also does a great job handling typos and has quickly become the fastest way to navigate our extensive documentation
that we hope also serves useful for implementing Typesense real-time search in your own documentation websites.


# Getting Started with Redis in .NET
Source: https://docs.servicestack.net/redis/getting-started

<div class="py-8 max-w-7xl mx-auto">
    <lite-youtube class="w-full mx-4 my-4" width="560" height="315" videoid="jBdOvTvjyqY" style="background-image: url('https://img.youtube.com/vi/jBdOvTvjyqY/maxresdefault.jpg')"></lite-youtube>
</div>

## Introduction to Redis as a Technology

Redis, standing for REmote DIctionary Server, is an open-source, in-memory data structure store. It's widely used as a database, cache, and message broker. With its unique set of features and unparalleled speed, it's a crucial tool for a modern developer's toolkit.

## Key Features of Redis

Redis supports various kinds of data structures like [strings](https://redis.io/docs/data-types/strings), [hashes](https://redis.io/docs/data-types/hashes), [lists](https://redis.io/docs/data-types/lists), [sets](https://redis.io/docs/data-types/sets), [sorted sets with range queries](https://redis.io/docs/data-types/sorted-sets), [bitmaps](https://redis.io/docs/data-types/bitmaps), [hyperloglogs](https://redis.io/docs/data-types/hyperloglogs), and geospatial indexes with [radius queries](https://redis.io/docs/data-types/geospatial). This wide array of data types and its ability to perform [atomic operations](https://redis.io/docs/manual/transactions/) make Redis extremely versatile for solving a myriad of problems.

![](../img/pages/redis/getting-started/key-features.png)

## High Performance and Speed

This support for a wide array of fundamental computational storage data structures is what sets Redis apart, and enables [blazing speed](https://redis.io/topics/benchmarks) when applied correctly. As an in-memory data store, reading and writing data happens exceedingly fast. This makes Redis an excellent choice for applications that require real-time data processing.

![](../img/pages/redis/getting-started/performance.png)

## Durability and Persistence

Even though Redis is an in-memory data store, it provides mechanisms to achieve data [persistence](https://redis.io/topics/persistence). You have the flexibility to choose from options like [snapshotting](https://redis.io/docs/management/persistence/#snapshotting) and append-only files (AOF), depending on your application's needs.

## Scalability and High Availability

Redis has robust features like [replication](https://redis.io/topics/replication), [Lua scripting](https://redis.io/commands/eval), [transactions](https://redis.io/docs/manual/transactions), and different levels of [on-disk persistence](https://redis.io/topics/persistence). With the help of [Redis Sentinel](https://redis.io/topics/sentinel), it provides high availability via automatic partitioning across multiple Redis nodes. It is also widely supported on major cloud providers as a managed service, like on [AWS under the ElastiCache product](https://aws.amazon.com/elasticache/redis/).

![](../img/pages/redis/getting-started/durability.png)

## Extensible and Versatile

You can extend Redis functionality using Redis modules. It's also a good fit for job & queue management, caching, real-time analytics, and many other use-cases.

Before we dive into using the ServiceStack.Redis .NET client, we will need a locally running Redis server. The easiest way to get this working is by using the [official Redis Docker image](https://hub.docker.com/_/redis), and using [Docker Desktop](https://www.docker.com/products/docker-desktop) to run it.

## Setting Up a Local Redis Server with Docker

To follow along with this tutorial, you will need a running instance of Redis. One of the easiest ways to get this set up is through Docker, which allows you to run a Redis server within a container on your machine.

If you do not have Docker installed, you can download it from the [official Docker website](https://www.docker.com/products/docker-desktop).

Once you have Docker installed and running, you can set up a Redis instance with the following command:

```bash
docker run --name local-redis -p 6379:6379 -d redis
```

This command tells Docker to run a container with the name "local-redis", using the official Redis image from Docker Hub. The `-p` flag maps the default Redis port (6379) from the container to your local machine, and the `-d` flag tells Docker to run the container in the background.

To confirm that your Redis server is running correctly, you can use the following command:

```bash
docker ps
```

This command lists all running Docker containers. If everything is set up correctly, you should see your "local-redis" container in the list.

Now, your local Redis server is running and ready to be connected on `localhost:6379`.

For more detailed information about Docker commands, you can refer to the [official Docker documentation](https://docs.docker.com/engine/reference/commandline/cli/).

## Using the redis-cli from Docker

Another way to validate your local Redis Docker container is running and access it is by using the Redis-CLI. 
If you don't have the Redis-CLI, we can actually use it from the same `redis` Docker image using the following command.

```bash
docker run -it redis /bin/bash -c "redis-cli -h host.docker.internal"
```
> `host.docker.internal` is a way of accessing the Docker host containers, however it may only work on Windows & macOS.

## Installing and Setting Up ServiceStack.Redis in Your Project

Now that we have our local Redis server set up and running, let's move on to adding ServiceStack.Redis to your .NET project. Here we will demonstrate this process in a .NET Console application for simplicity.

To start with, make sure you have the [.NET SDK](https://dotnet.microsoft.com/download) installed on your system. Once you have the SDK, you can create a new Console application with the following command:

```bash
dotnet new console -n RedisConsoleApp
```

After creating your Console application, navigate to the project directory:

```bash
cd RedisConsoleApp
```

Then, add the ServiceStack.Redis NuGet package:

```bash
dotnet add package ServiceStack.Redis
```

Now you have successfully added the ServiceStack.Redis library to your project. In your `Program.cs`, you can import the library using:

```csharp
using ServiceStack.Redis;
```

You are now set to start using Redis in your .NET console application.

### Using the ServiceStack `x` tool

For developers working on larger projects or who want a quicker setup, ServiceStack provides a .NET tool called `x`. You can install this tool using the following command:

```bash
dotnet tool install --global x
```

This tool allows you to create new projects and add (mix in) functionality quickly and easily. To create a new web project, you can use the following command:

```bash
x new web ProjectName
```

To add Redis support to your project, navigate to your project directory and then use the `mix` command:

```bash
cd ProjectName
x mix redis
```

This automatically adds the ServiceStack.Redis library to your project and sets up a basic Redis configuration.

For further information on using the `x` tool, refer to the [ServiceStack `x` tool documentation](/dotnet-tool).


## Connecting and Using Redis Client Managers

In the previous section, we installed and set up the ServiceStack.Redis library in our .NET Console application. Now, let's learn how to use the Redis Client Managers provided by this library to interact with Redis.

ServiceStack.Redis provides a few different client managers, but for this tutorial, we will use `RedisManagerPool`. This client manager is a simple and efficient pool of Redis clients that is suitable for most use cases.

### Connecting to Redis

To start, you will first need to establish a connection to your Redis server. You can do this by passing your Redis server's connection string to the `RedisManagerPool` constructor:

```csharp
var manager = new RedisManagerPool("localhost:6379");
```

Now that you have a manager, you can get a Redis client instance from it:

```csharp
using (var redis = manager.GetClient())
{
    // You can now use `redis` to interact with your Redis server.
}
```

### Using the Client with .NET Core Dependency Injection

If you are building a web application with .NET Core, you might want to make use of .NET Core's built-in dependency injection (DI) to manage your Redis clients. Here is how you can register your `RedisManagerPool` with the DI container:

```csharp
public void ConfigureServices(IServiceCollection services)
{
    services.AddSingleton<IRedisClientsManager>(new RedisManagerPool("localhost:6379"));

    // Add other services...
}
```

Now, the DI container will manage the lifecycle of the `RedisManagerPool`, and you can inject [`IRedisClientsManager`](https://reference.servicestack.net/api/ServiceStack.Redis/IRedisClientsManager/) into your services:

```csharp
public class MyService : Service
{
    public IRedisClientsManager RedisClientsManager { get; set; }

    public void Any(Request request)
    {
        using (var redis = RedisClientsManager.GetClient())
        {
            // Use `redis` to interact with your Redis server.
        }
    }
}
```

If you are using ServiceStack, you can simply use the `base.Redis` property from the `Service` base class to resolve a Redis client:

```csharp
public class MyService : Service
{
    public void Any(Request request)
    {
        var redis = base.Redis;
        // Use `redis` to interact with your Redis server.
    }
}
```

## Leveraging the Simplicity of ICacheClient

ServiceStack's `ICacheClient` is an abstraction over caching operations, which allows you to interact with various cache implementations in a standard way. Once `IRedisClientsManager` is registered in the IoC container, ServiceStack switches the implementation of `ICacheClient` to use Redis as its backend.

In ServiceStack services, you can easily access the cache via the `base.Cache` property of the `Service` base class. Here is an example of how you can use the `Get` and `Set` methods to work with Redis cache:

```csharp
public class MyService : Service
{
    public object Any(Request request)
    {
        var cacheKey = "unique-cache-key";
        var existingValue = base.Cache.Get<string>(cacheKey);

        if (existingValue == null)
        {
            existingValue = "This is a value from some expensive operation";
            base.Cache.Set(cacheKey, existingValue);
        }

        return new { Value = existingValue };
    }
}
```

This example checks if a value is available in the cache. If the value is not present, it performs an expensive operation to get the value (in this case, we're just setting a string), then stores the value in the cache for subsequent requests.

The `ICacheClient` interface also supports asynchronous operations. If you want to use the async versions of these methods, you can use the `base.CacheAsync` property of the `Service` base class:

```csharp
public class MyService : Service
{
    public async Task<object> Any(Request request)
    {
        var cacheKey = "unique-cache-key";
        var existingValue = await base.CacheAsync.Get<string>(cacheKey);

        if (existingValue == null)
        {
            existingValue = "This is a value from some expensive operation";
            await base.CacheAsync.Set(cacheKey, existingValue);
        }

        return new { Value = existingValue };
    }
}
```

By using `ICacheClient`, you can make your application agnostic of the underlying cache implementation, which promotes loose coupling and makes your application easier to test and maintain. You can learn more about the `ICacheClient` interface and its usage in the [Caching providers documentation](/caching).

## Using the RedisClient Directly

While using `ICacheClient` provides a high-level abstraction for caching operations, there might be situations where you would need direct access to the underlying Redis client for more granular control or to perform operations not covered by the `ICacheClient` interface.

You can use `IRedisClient` to interact directly with Redis using the commands provided by the Redis server. First, let's get an instance of `IRedisClient`:

```csharp
using var redis = clientsManager.GetClient();
```

In this context, `clientsManager` is an instance of `IRedisClientsManager`, which is already registered in our .NET Core application's dependency injection container.

With an instance of `IRedisClient`, we can perform similar `Get` and `Set` operations as we did with `ICacheClient`:

```csharp
var key = "unique-key";
var existingValue = redis.Get<string>(key);

if (existingValue == null)
{
    existingValue = "This is a value from some expensive operation";
    redis.Set(key, existingValue);
}
```

These operations directly correspond to the GET and SET commands in raw Redis:

```bash
GET unique-key
SET unique-key "This is a value from some expensive operation"
```

In addition to `Get` and `Set`, `IRedisClient` also exposes other Redis commands. For instance, you can use the `Increment` method to atomically increment the value of a key:

```csharp
var counterKey = "counter";
redis.Increment(counterKey, 1);
```

The `Increment` method corresponds to the INCR command in raw Redis:

```bash
INCR counter
```

By using `IRedisClient` directly, you have access to the entire set of Redis commands and data structures, which makes it a powerful tool for more advanced use cases. To learn more about the `IRedisClient` interface and its usage, refer to the [ServiceStack reference documentation site](https://reference.servicestack.net/api/ServiceStack.Redis/IRedisClient/).

## Async Usability of ServiceStack.Redis

One of the great strengths of the ServiceStack.Redis library is its comprehensive support for asynchronous operations via the `async`/`await` paradigm in .NET. This allows developers to perform non-blocking I/O operations with Redis, freeing up system resources and improving the efficiency and scalability of your application.

To make use of asynchronous operations, you'll want to get an instance of `IRedisClientAsync`:

```csharp
using var redisAsync = await clientsManager.GetClientAsync();
```

In this context, `clientsManager` is an instance of `IRedisClientsManager`, which is already registered in our .NET Core application's dependency injection container.

Once you have an instance of `IRedisClientAsync`, you can perform async versions of the usual Redis operations. For instance:

```csharp
var key = "unique-key";
var existingValue = await redisAsync.GetAsync<string>(key);

if (existingValue == null)
{
    existingValue = "This is a value from some expensive operation";
    await redisAsync.SetAsync(key, existingValue);
}
```

These operations are non-blocking and make use of the Task-based Asynchronous Pattern (TAP) in .NET. This means you can perform other work while waiting for the Redis operations to complete, improving the responsiveness of your application. This is particularly beneficial in web applications, where efficient handling of requests is critical for performance.

ServiceStack.Redis async support makes interacting with Redis from .NET applications familiar and straightforward, aligning with the asynchronous programming model in .NET. As such, you can leverage all the benefits of async/await while interacting with Redis in a manner consistent with the rest of your .NET codebase.


## Storing Complex Objects: Strongly Typed Client API

One of the many powerful features of ServiceStack.Redis library is its support for storing complex objects using the Strongly Typed Client API. This feature provides a more natural and convenient way to work with custom Plain Old CLR Objects (POCOs) and data structures in Redis.

To use the Strongly Typed Client API, we start by obtaining an instance of the `IRedisTypedClient<T>`, which can be done using the `As<T>` method from an `IRedisClient` instance. Let's assume that we have a `Person` class defined as follows:

```csharp
public class Person
{
    public string Id { get; set; }
    public string Name { get; set; }
    public int Age { get; set; }
}
```

To store an instance of the `Person` class in Redis, we can do the following:

```csharp
using (var redis = clientsManager.GetClient())
{
    var redisPeople = redis.As<Person>();

    var person = new Person
    {
        Id = "1",
        Name = "John Doe",
        Age = 30
    };

    redisPeople.Store(person);
}
```

In this example, the `redisPeople` variable is an instance of `IRedisTypedClient<Person>`. We can use this instance to call the `Store` method and save our `Person` instance to Redis. The ServiceStack.Redis library automatically handles the serialization and deserialization of our POCO.

Retrieving our `Person` instance is just as straightforward:

```csharp
using (var redis = clientsManager.GetClient())
{
    var redisPeople = redis.As<Person>();
    var person = redisPeople.GetById("1");
    Console.WriteLine($"Name: {person.Name}, Age: {person.Age}");
}
```

Here we used the `GetById` method from our `redisPeople` instance to retrieve the person with the `Id` "1" from Redis.

This way of working with complex objects in Redis using ServiceStack.Redis makes it seamless to integrate Redis into your .NET applications, as it aligns with .NET's object-oriented approach.

In the previous examples, we used the `Store` method of `IRedisTypedClient<T>` to store an instance of `Person` into Redis, and the `GetById` method to retrieve it. One important thing to note is that these methods automatically handle the generation of the key for Redis.

The key is generated based on the namespace and the class name of the object being stored, followed by the value of the primary key. This means that when you use `Store`, ServiceStack.Redis takes care of creating a key like `urn:Person:1` for a `Person` instance with an `Id` of "1". This pattern also applies when retrieving data with `GetById`; ServiceStack.Redis knows to look for a key following this pattern.

This feature is particularly useful when used in combination with ServiceStack's OrmLite, a convention-based, configuration-free lightweight ORM. With OrmLite, you can use the same POCO classes for both your database and Redis operations. The automatic key generation from ServiceStack.Redis aligns with OrmLite's conventions, providing a consistent and intuitive pattern for data storage and retrieval across both systems. This alleviates the need to manually manage keys, allowing developers to focus on working with their data in a more natural, object-oriented manner.

For more information about ServiceStack's OrmLite, check the [ServiceStack.OrmLite documentation](/ormlite/).

## Working with Redis Data Structures

In Redis, one of the powerful features is its support for different types of data structures. While key-value storage is fundamental, Redis goes beyond this and provides the ability to manipulate lists, sets, sorted sets, and hashes as well.

ServiceStack.Redis library provides an intuitive interface to work with these data structures in a way that feels familiar to .NET developers. This is achieved through properties exposed on the `IRedisClient` interface, each corresponding to one of Redis's data structures.

Here are examples of how to interact with Lists, Sets, and SortedSets using ServiceStack.Redis:

### Lists
A Redis list is a simple list of strings, sorted by insertion order. You can work with lists in ServiceStack.Redis through the `Lists` property.

```csharp
var redis = redisManager.GetClient();

// Add new elements to a Redis list
redis.Lists["urn:mylist"].Add("item1");
redis.Lists["urn:mylist"].Add("item2");

// Fetch all elements in the list
var myList = redis.Lists["urn:mylist"].GetAll();
```

### Sets
A Redis set is an unordered collection of unique strings. In ServiceStack.Redis, you can work with sets through the `Sets` property.

```csharp
var redis = redisManager.GetClient();

// Add new elements to a Redis set
redis.Sets["urn:myset"].Add("item1");
redis.Sets["urn:myset"].Add("item2");

// Check if an item exists in the set
bool exists = redis.Sets["urn:myset"].Contains("item1");
```

### Sorted Sets
A Redis sorted set is similar to a regular set, but each value is associated with a score, which is used to sort the set. It's through the `SortedSets` property that ServiceStack.Redis allows interaction with sorted sets.

```csharp
var redis = redisManager.GetClient();

// Works with TypedClients as well.
var typedClient = redis.As<MyClass>();

// Add new elements to a Redis sorted set
typedClient.SortedSets["urn:mysortedset"].Add(new MyClass(), 1);
typedClient.SortedSets["urn:mysortedset"].Add(new MyClass(), 2);

// Fetch all elements in the sorted set
var mySortedSet = typedClient.SortedSets["urn:mysortedset"].GetAll();
```

As you can see, ServiceStack.Redis makes it easy to work with Redis data structures in a manner that's familiar to .NET developers. With these powerful features at your disposal, you can implement complex data storage and retrieval operations with ease. For a deeper dive into these data structures and their usage, please refer to the [Redis data types documentation](https://redis.io/docs/data-types/tutorial/).

## Conclusion: The Power of Redis and ServiceStack.Redis

Throughout this tutorial, we've explored the basics of Redis as a technology and have seen how the ServiceStack.Redis library can make interacting with Redis from a .NET environment feel natural and intuitive. However, what we've covered just scratches the surface of what can be achieved with this powerful combination.

With Redis, we have at our disposal a high-performance, feature-rich in-memory database that supports various data structures. Combined with the real-time data replication, persistence options, and high availability features, Redis is a versatile tool that can suit a wide array of application needs.

On the other hand, ServiceStack.Redis bridges the gap between the .NET ecosystem and Redis. Its ability to leverage .NET's async/await syntax, work with complex POCO objects, manage connections efficiently, and provide an idiomatic interface to Redis's data structures, truly makes it a powerful tool for any .NET developer looking to utilize Redis.

If you have suggestions, corrections, or ideas to improve this content, please do share them. Your insights will help us refine this tutorial and better serve readers like you. You can reach out to us via Discord, GitHub Discussions or our Customer Forums.


# Managing connections
Source: https://docs.servicestack.net/redis/client-managers

## Redis Connection Strings

Redis Connection strings have been expanded to support the more versatile URI format which is now able to capture most of Redis Client
settings in a single connection string (akin to DB Connection strings).

Redis Connection Strings supports multiple URI-like formats, from a simple **hostname** or **IP Address and port** pair to a
fully-qualified **URI** with multiple options specified on the QueryString.

Some examples of supported formats:

```
localhost
127.0.0.1:6379
redis://localhost:6379
password@localhost:6379
clientid:password@localhost:6379
redis://clientid:password@localhost:6380?ssl=true&db=1
```

::: info
More examples can be seen in [ConfigTests.cs](https://github.com/ServiceStack/ServiceStack.Redis/blob/master/tests/ServiceStack.Redis.Tests/ConfigTests.cs)
:::

Any additional configuration can be specified as QueryString parameters. The full list of options that can be specified include:

<table>
    <tr>
        <td><b>Ssl</b></td>
        <td>bool</td>
        <td>If this is an SSL connection</td>
    </tr>
    <tr>
        <td><b>Db</b></td>
        <td>int</td>
        <td>The Redis DB this connection should be set to</td>
    </tr>
    <tr>
        <td><b>Client</b></td>
        <td>string</td>
        <td>A text alias to specify for this connection for analytic purposes</td>
    </tr>
    <tr>
        <td><b>Username</b></td>
        <td>string</td>
        <td>Redis Username when using ACLs</td>
    </tr>
    <tr>
        <td><b>Password</b></td>
        <td>string</td>
        <td>UrlEncoded version of the Password for this connection</td>
    </tr>
    <tr>
        <td><b>ConnectTimeout</b></td>
        <td>int</td>
        <td>Timeout in ms for making a TCP Socket connection</td>
    </tr>
    <tr>
        <td><b>SendTimeout</b></td>
        <td>int</td>
        <td>Timeout in ms for making a synchronous TCP Socket Send</td>
    </tr>
    <tr>
        <td><b>ReceiveTimeout</b></td>
        <td>int</td>
        <td>Timeout in ms for waiting for a synchronous TCP Socket Receive</td>
    </tr>
    <tr>
        <td><b>IdleTimeOutSecs</b></td>
        <td>int</td>
        <td>Timeout in Seconds for an Idle connection to be considered active</td>
    </tr>
    <tr>
        <td><b>NamespacePrefix</b></td>
        <td>string</td>
        <td>Use a custom prefix for ServiceStack.Redis internal index colletions</td>
    </tr>
</table>

When using [Redis ACLs](https://redis.io/docs/manual/security/acl/) the Username needs to specified on the QueryString, e.g:

```csharp
var connString = $"redis://{Host}?ssl=true&username={Username}&password={Password.UrlEncode()}";
var redisManager = new RedisManagerPool(connString);
```

### [Connecting to Azure Redis](/ssl-redis-azure)

As connecting to [Azure Redis Cache](http://azure.microsoft.com/en-us/services/cache/) via SSL was the primary use-case for this feature,
we've added a new
[Getting connected to Azure Redis via SSL](/ssl-redis-azure) to help you get started.

## Redis Client Managers

The recommended way to access `RedisClient` instances is to use one of the available Thread-Safe Client Managers below. Client Managers are connection factories which should be registered as a Singleton either in your IOC or static class.

### RedisManagerPool

With the enhanced Redis URI Connection Strings we've been able to simplify and streamline the existing `PooledRedisClientManager` implementation and have extracted it out into a new clients manager called `RedisManagerPool`.

In addition to removing all above options on the Client Manager itself, readonly connection strings have also been removed so the configuration ends up much simpler and more aligned with the common use-case:

```csharp
container.Register<IRedisClientsManager>(c => 
    new RedisManagerPool(redisConnectionString));
```

**Pooling Behavior**

Any connections required after the maximum Pool size has been reached will be created and disposed outside of the Pool. By not being restricted to a maximum pool size, the pooling behavior in `RedisManagerPool` can maintain a smaller connection pool size at the cost of potentially having a higher opened/closed connection count.

### PooledRedisClientManager

If you prefer to define options on the Client Manager itself or you want to provide separate Read/Write and ReadOnly
(i.e. Master and Replica) redis-servers, use the `PooledRedisClientManager` instead:

```csharp
container.Register<IRedisClientsManager>(c => 
    new PooledRedisClientManager(redisReadWriteHosts, redisReadOnlyHosts) { 
        ConnectTimeout = 100,
        //...
    });
```

**Pooling Behavior**

The `PooledRedisClientManager` imposes a maximum connection limit and when its maximum pool size has been reached will instead block on any new connection requests until the next `RedisClient` is released back into the pool. If no client became available within `PoolTimeout`, a Pool `TimeoutException` will be thrown.

## Redis Configuration

In addition to configuring Redis Client Managers directly, management and behavior of Redis connections can also configured using the static [RedisConfig.cs](https://github.com/ServiceStack/ServiceStack/blob/main/ServiceStack.Redis/src/ServiceStack.Redis/RedisConfig.cs) class, e.g:

#### Configure Pool Size of Redis Client Managers

```csharp
RedisConfig.DefaultMaxPoolSize = 100;
```

Available Redis Client Configuration options and their defaults:

| Property | Default | Description |
| - | - | - |
| `DefaultConnectTimeout`         | **-1** (none)     | The default RedisClient Socket ConnectTimeout |
| `DefaultSendTimeout`            | **-1** (none)     | The default RedisClient Socket SendTimeout |
| `DefaultReceiveTimeout`         | **-1** (none)     | The default RedisClient Socket ReceiveTimeout |
| `DefaultIdleTimeOutSecs`        | **240** seconds   | Default Idle TimeOut before a connection is considered to be stale |
| `DefaultRetryTimeout`           | **10000** ms      | The default RetryTimeout for auto retry of failed operations |
| `DefaultMaxPoolSize`            | **null** (none)   | Max Pool Size for Pooled Redis Client Managers (overrides DefaultPoolSizeMultiplier) |
| `DefaultPoolSizeMultiplier`     | **50**            | The default pool size multiplier if no pool size is specified |
| `BackOffMultiplier`             | **10** ms         | The BackOff multiplier failed Auto Retries starts from |
| `CommandKeysBatchSize`          | **10000** keys    | Batch size of keys to include in a single Redis Command (e.g. DEL k1 k2...) |
| `VerifyMasterConnections`       | **true**          | Whether Connections to Master hosts should be verified they're still a master |
| `RetryReconnectOnFailedMasters` | **true**          | Whether to retry re-connecting on same connection if not a master instance |
| `HostLookupTimeoutMs`           | **200** ms        | The ConnectTimeout on clients used to find the next available host |
| `AssumeServerVersion`           | **null** (none)   | Skip ServerVersion Checks by specifying Min Version number |
| `DeactivatedClientsExpiry`      | **0** seconds     | How long to hold deactivated clients for before disposing their connection |
| `EnableVerboseLogging`          | **false**         | Whether Debug Logging should log detailed Redis operations |
| `AssertAccessOnlyOnSameThread`  | **false**         | Assert all access using pooled RedisClient instance is limited to same thread |


### [ServiceStack.Redis SSL Support](/ssl-redis-azure)

ServiceStack.Redis supports **SSL connections** making it suitable for accessing remote Redis server instances over a
**secure SSL connection**.

![Azure Redis Cache](https://github.com/ServiceStack/Assets/raw/master/img/wikis/redis/azure-redis-instance.png)

#### Specify SSL Protocol

Support for changing the Ssl Protocols used for encrypted SSL connections can be set on the connection string using the `sslprotocols` modifier, e.g:

```csharp
var connString = $"redis://{Host}?ssl=true&sslprotocols=Tls12&password={Password.UrlEncode()}";
var redisManager = new RedisManagerPool(connString);
using var client = redisManager.GetClient();
//...
```

If needed the `RedisConfig` Certificate selecation and validation callbacks can be used to [Validate SSL Certificates](http://msdn.microsoft.com/en-us/library/office/dd633677(v=exchg.80).aspx):

```csharp
RedisConfig.CertificateSelectionCallback = (object sender, 
    string targetHost, 
    X509CertificateCollection localCertificates,
    X509Certificate remoteCertificate, 
    string[] acceptableIssuers) => ...

RedisConfig.CertificateValidationCallback = (object sender,
    X509Certificate certificate,
    X509Chain chain,
    SslPolicyErrors sslPolicyErrors) => ...
```

### Read Only Clients

By default resolving a RedisClient with `GetRedisClient()` or `GetRedisClientAsync()` will return a client connected to the configured primary (master) host, if you also have replica (slave) hosts configured, you can access it with the `GetReadOnlyClient()` or `GetReadOnlyClientAsync()` APIs, e.g:

```csharp
using var redisReadOnly = clientsManager.GetReadOnlyClient();
```

### BasicRedisClientManager

If don't want to use connection pooling (i.e. you're accessing a local redis-server instance) you can use a basic (non-pooled) Clients Manager which creates a new `RedisClient` instance each time:

```csharp
container.Register<IRedisClientsManager>(c => 
    new BasicRedisClientManager(redisConnectionString));
```

### Accessing the Redis Client

Once registered, accessing the RedisClient is the same in all Client Managers, e.g:

```csharp
var clientsManager = container.Resolve<IRedisClientsManager>();
using var redis = clientsManager.GetClient();

redis.IncrementValue("counter");
List<string> days = redis.GetAllItemsFromList("days");

//Access Typed API
var redisTodos = redis.As<Todo>();

redisTodos.Store(new Todo {
    Id = redisTodos.GetNextSequence(),
    Content = "Learn Redis",
});

var todo = redisTodos.GetById(1);

//Access Native Client
var redisNative = (IRedisNativeClient)redis;

redisNative.Incr("counter");
List<string> days = redisNative.LRange("days", 0, -1);
```

A more detailed list of the available RedisClient APIs used in the example can be seen in the C# interfaces below:

- [IRedisClientsManager](https://github.com/ServiceStack/ServiceStack/blob/master/src/ServiceStack.Interfaces/Redis/IRedisClientsManager.cs)
- [IRedisClient](https://github.com/ServiceStack/ServiceStack/blob/master/src/ServiceStack.Interfaces/Redis/IRedisClient.cs)
- [IRedisNativeClient](https://github.com/ServiceStack/ServiceStack/blob/master/src/ServiceStack.Interfaces/Redis/IRedisNativeClient.cs)
- [IRedisSubscription](https://github.com/ServiceStack/ServiceStack/blob/master/src/ServiceStack.Interfaces/Redis/IRedisSubscription.cs)

#### Pipeline & Transaction APIs

- [IRedisTransaction](https://github.com/ServiceStack/ServiceStack/blob/master/src/ServiceStack.Interfaces/Redis/IRedisTransaction.cs)
- [IRedisPipelineShared](https://github.com/ServiceStack/ServiceStack/blob/master/src/ServiceStack.Interfaces/Redis/Pipeline/IRedisPipelineShared.cs)
- [IRedisQueueableOperation](https://github.com/ServiceStack/ServiceStack/blob/master/src/ServiceStack.Interfaces/Redis/Pipeline/IRedisQueueableOperation.cs)
- [IRedisQueueCompletableOperation](https://github.com/ServiceStack/ServiceStack/blob/master/src/ServiceStack.Interfaces/Redis/Pipeline/IRedisQueueCompletableOperation.cs)

#### Generic Client APIs

- [IRedisTypedClient](https://github.com/ServiceStack/ServiceStack/blob/master/src/ServiceStack.Interfaces/Redis/Generic/IRedisTypedClient.cs)
- [IRedisHash](https://github.com/ServiceStack/ServiceStack/blob/master/src/ServiceStack.Interfaces/Redis/Generic/IRedisHash.Generic.cs)
- [IRedisList](https://github.com/ServiceStack/ServiceStack/blob/master/src/ServiceStack.Interfaces/Redis/Generic/IRedisList.Generic.cs)
- [IRedisSet](https://github.com/ServiceStack/ServiceStack/blob/master/src/ServiceStack.Interfaces/Redis/Generic/IRedisSet.Generic.cs)
- [IRedisSortedSet](https://github.com/ServiceStack/ServiceStack/blob/master/src/ServiceStack.Interfaces/Redis/Generic/IRedisSortedSet.Generic.cs)
- [IRedisTypedQueueableOperation](https://github.com/ServiceStack/ServiceStack/blob/master/src/ServiceStack.Interfaces/Redis/Generic/IRedisTypedQueueableOperation.cs)

#### Server Collection APIs

- [IRedisHash](https://github.com/ServiceStack/ServiceStack/blob/master/src/ServiceStack.Interfaces/Redis/IRedisHash.cs)
- [IRedisList](https://github.com/ServiceStack/ServiceStack/blob/master/src/ServiceStack.Interfaces/Redis/IRedisList.cs)
- [IRedisSet](https://github.com/ServiceStack/ServiceStack/blob/master/src/ServiceStack.Interfaces/Redis/IRedisSet.cs)
- [IRedisSortedSet](https://github.com/ServiceStack/ServiceStack/blob/master/src/ServiceStack.Interfaces/Redis/IRedisSortedSet.cs)

### Async Redis

The async support in ServiceStack.Redis is designed for optimal efficiency and uses `ValueTask` & other modern Async APIs only available in **.NET Standard 2.0** and **.NET Framework v4.7.2+** projects where there's async API equivalents for most sync APIs as contained within the Async Redis interfaces below:

- [IRedisClientsManagerAsync](https://github.com/ServiceStack/ServiceStack/blob/master/src/ServiceStack.Interfaces/Redis/IRedisClientsManagerAsync.cs)
- [IRedisClientAsync](https://github.com/ServiceStack/ServiceStack/blob/master/src/ServiceStack.Interfaces/Redis/IRedisClientAsync.cs)
- [IRedisNativeClientAsync](https://github.com/ServiceStack/ServiceStack/blob/master/src/ServiceStack.Interfaces/Redis/IRedisNativeClientAsync.cs)
- [IRedisSubscriptionAsync](https://github.com/ServiceStack/ServiceStack/blob/master/src/ServiceStack.Interfaces/Redis/IRedisSubscriptionAsync.cs)

#### Async Pipeline & Transaction APIs

- [IRedisTransactionAsync](https://github.com/ServiceStack/ServiceStack/blob/master/src/ServiceStack.Interfaces/Redis/IRedisTransactionAsync.cs)
- [IRedisPipelineSharedAsync](https://github.com/ServiceStack/ServiceStack/blob/master/src/ServiceStack.Interfaces/Redis/Pipeline/IRedisPipelineSharedAsync.cs)
- [IRedisQueueableOperationAsync](https://github.com/ServiceStack/ServiceStack/blob/master/src/ServiceStack.Interfaces/Redis/Pipeline/IRedisQueueableOperationAsync.cs)
- [IRedisQueueCompletableOperationAsync](https://github.com/ServiceStack/ServiceStack/blob/master/src/ServiceStack.Interfaces/Redis/Pipeline/IRedisQueueCompletableOperationAsync.cs)

#### Async Generic Client APIs

- [IRedisTypedClientAsync](https://github.com/ServiceStack/ServiceStack/blob/master/src/ServiceStack.Interfaces/Redis/Generic/IRedisTypedClientAsync.cs)
- [IRedisHashAsync](https://github.com/ServiceStack/ServiceStack/blob/master/src/ServiceStack.Interfaces/Redis/Generic/IRedisHash.Generic.Async.cs)
- [IRedisListAsync](https://github.com/ServiceStack/ServiceStack/blob/master/src/ServiceStack.Interfaces/Redis/Generic/IRedisList.Generic.Async.cs)
- [IRedisSetAsync](https://github.com/ServiceStack/ServiceStack/blob/master/src/ServiceStack.Interfaces/Redis/Generic/IRedisSet.Generic.Async.cs)
- [IRedisSortedSetAsync](https://github.com/ServiceStack/ServiceStack/blob/master/src/ServiceStack.Interfaces/Redis/Generic/IRedisSortedSet.Generic.Async.cs)
- [IRedisTypedTransactionAsync](https://github.com/ServiceStack/ServiceStack/blob/master/src/ServiceStack.Interfaces/Redis/Generic/IRedisTypedTransactionAsync.cs)
- [IRedisTypedQueueableOperationAsync](https://github.com/ServiceStack/ServiceStack/blob/master/src/ServiceStack.Interfaces/Redis/Generic/IRedisTypedQueueableOperationAsync.cs)

#### Async Server Collection APIs

- [IRedisHashAsync](https://github.com/ServiceStack/ServiceStack/blob/master/src/ServiceStack.Interfaces/Redis/IRedisHashAsync.cs)
- [IRedisListAsync](https://github.com/ServiceStack/ServiceStack/blob/master/src/ServiceStack.Interfaces/Redis/IRedisListAsync.cs)
- [IRedisSetAsync](https://github.com/ServiceStack/ServiceStack/blob/master/src/ServiceStack.Interfaces/Redis/IRedisSetAsync.cs)
- [IRedisSortedSetAsync](https://github.com/ServiceStack/ServiceStack/blob/master/src/ServiceStack.Interfaces/Redis/IRedisSortedSetAsync.cs)

## [Redis GEO](https://github.com/ServiceStackApps/redis-geo)

The [release of Redis 3.2.0](http://antirez.com/news/104) brings [GEO capabilities](http://redis.io/commands/geoadd) 
which will let you store Lat/Long coordinates in Redis and query locations within a specified radius. 
To demonstrate this functionality we've created a new
[Redis GEO Live Demo](https://github.com/ServiceStackApps/redis-geo) which lets you click on anywhere in
the U.S. to find the list of nearest cities within a given radius, Live Demo at: https://redis.netcore.io


# Getting Started with Redis Client APIs
Source: https://docs.servicestack.net/redis/client-usage

Below is a simple example to give you a flavour of how easy it is to use some of Redis's advanced data structures - in this case Redis Lists:
_Full source code of this example is [viewable online](https://github.com/ServiceStack/ServiceStack.Redis/blob/master/tests/ServiceStack.Redis.Tests/ShippersExample.cs)_

```csharp
using var redisClient = new RedisClient();
//Create a 'strongly-typed' API that makes all Redis Value operations to apply against Shippers
IRedisTypedClient<Shipper> redis = redisClient.As<Shipper>();

//Redis lists implement IList<T> while Redis sets implement ICollection<T>
var currentShippers = redis.Lists["urn:shippers:current"];
var prospectiveShippers = redis.Lists["urn:shippers:prospective"];

currentShippers.Add(
    new Shipper {
        Id = redis.GetNextSequence(),
        CompanyName = "Trains R Us",
        DateCreated = DateTime.UtcNow,
        ShipperType = ShipperType.Trains,
        UniqueRef = Guid.NewGuid()
    });

currentShippers.Add(
    new Shipper {
        Id = redis.GetNextSequence(),
        CompanyName = "Planes R Us",
        DateCreated = DateTime.UtcNow,
        ShipperType = ShipperType.Planes,
        UniqueRef = Guid.NewGuid()
    });

var lameShipper = new Shipper {
    Id = redis.GetNextSequence(),
    CompanyName = "We do everything!",
    DateCreated = DateTime.UtcNow,
    ShipperType = ShipperType.All,
    UniqueRef = Guid.NewGuid()
};

currentShippers.Add(lameShipper);

Dump("ADDED 3 SHIPPERS:", currentShippers);

currentShippers.Remove(lameShipper);

Dump("REMOVED 1:", currentShippers);

prospectiveShippers.Add(
    new Shipper {
        Id = redis.GetNextSequence(),
        CompanyName = "Trucks R Us",
        DateCreated = DateTime.UtcNow,
        ShipperType = ShipperType.Automobiles,
        UniqueRef = Guid.NewGuid()
    });

Dump("ADDED A PROSPECTIVE SHIPPER:", prospectiveShippers);

redis.PopAndPushBetweenLists(prospectiveShippers, currentShippers);

Dump("CURRENT SHIPPERS AFTER POP n' PUSH:", currentShippers);
Dump("PROSPECTIVE SHIPPERS AFTER POP n' PUSH:", prospectiveShippers);

var poppedShipper = redis.PopFromList(currentShippers);
Dump("POPPED a SHIPPER:", poppedShipper);
Dump("CURRENT SHIPPERS AFTER POP:", currentShippers);

//reset sequence and delete all lists
redis.SetSequence(0);
redis.Remove(currentShippers, prospectiveShippers);
Dump("DELETING CURRENT AND PROSPECTIVE SHIPPERS:", currentShippers);
```

EXAMPLE OUTPUT:

```
ADDED 3 SHIPPERS:
Id:1,CompanyName:Trains R Us,ShipperType:Trains,DateCreated:2010-01-31T11:53:37.7169323Z,UniqueRef:d17c5db0415b44b2ac5da7b6ebd780f5
Id:2,CompanyName:Planes R Us,ShipperType:Planes,DateCreated:2010-01-31T11:53:37.799937Z,UniqueRef:e02a73191f4b4e7a9c44eef5b5965d06
Id:3,CompanyName:We do everything!,ShipperType:All,DateCreated:2010-01-31T11:53:37.8009371Z,UniqueRef:d0c249bbbaf84da39fc4afde1b34e332

REMOVED 1:
Id:1,CompanyName:Trains R Us,ShipperType:Trains,DateCreated:2010-01-31T11:53:37.7169323Z,UniqueRef:d17c5db0415b44b2ac5da7b6ebd780f5
Id:2,CompanyName:Planes R Us,ShipperType:Planes,DateCreated:2010-01-31T11:53:37.799937Z,UniqueRef:e02a73191f4b4e7a9c44eef5b5965d06

ADDED A PROSPECTIVE SHIPPER:
Id:4,CompanyName:Trucks R Us,ShipperType:Automobiles,DateCreated:2010-01-31T11:53:37.8539401Z,UniqueRef:67d7d4947ebc4b0ba5c4d42f5d903bec

CURRENT SHIPPERS AFTER POP n' PUSH:
Id:4,CompanyName:Trucks R Us,ShipperType:Automobiles,DateCreated:2010-01-31T11:53:37.8539401Z,UniqueRef:67d7d4947ebc4b0ba5c4d42f5d903bec
Id:1,CompanyName:Trains R Us,ShipperType:Trains,DateCreated:2010-01-31T11:53:37.7169323Z,UniqueRef:d17c5db0415b44b2ac5da7b6ebd780f5
Id:2,CompanyName:Planes R Us,ShipperType:Planes,DateCreated:2010-01-31T11:53:37.799937Z,UniqueRef:e02a73191f4b4e7a9c44eef5b5965d06

PROSPECTIVE SHIPPERS AFTER POP n' PUSH:

POPPED a SHIPPER:
Id:2,CompanyName:Planes R Us,ShipperType:Planes,DateCreated:2010-01-31T11:53:37.799937Z,UniqueRef:e02a73191f4b4e7a9c44eef5b5965d06

CURRENT SHIPPERS AFTER POP:
Id:4,CompanyName:Trucks R Us,ShipperType:Automobiles,DateCreated:2010-01-31T11:53:37.8539401Z,UniqueRef:67d7d4947ebc4b0ba5c4d42f5d903bec
Id:1,CompanyName:Trains R Us,ShipperType:Trains,DateCreated:2010-01-31T11:53:37.7169323Z,UniqueRef:d17c5db0415b44b2ac5da7b6ebd780f5

DELETING CURRENT AND PROSPECTIVE SHIPPERS:
```

More examples are available in the [RedisExamples Redis examples page] and in the comprehensive
[test suite](https://github.com/ServiceStack/ServiceStack.Redis/tree/master/tests/ServiceStack.Redis.Tests)


## Speed
One of the best things about Redis is the speed - it is quick.

[This example](https://github.com/ServiceStack/ServiceStack.Redis/blob/master/tests/ServiceStack.Redis.Tests/RedisClientTests.cs)
below stores and gets the entire [Northwind database](http://code.google.com/p/servicestack/source/browse/trunk/Common/Northwind.Benchmarks/Northwind.Common/DataModel/NorthwindData.cs) (3202 records) in less *1.2 secs* - we've never had it so quick!

_(Running inside a VS.NET/R# unit test on a 3 year old iMac)_

```csharp
using var client = new RedisClient();

var before = DateTime.Now;
client.StoreAll(NorthwindData.Categories);
client.StoreAll(NorthwindData.Customers);
client.StoreAll(NorthwindData.Employees);
client.StoreAll(NorthwindData.Shippers);
client.StoreAll(NorthwindData.Orders);
client.StoreAll(NorthwindData.Products);
client.StoreAll(NorthwindData.OrderDetails);
client.StoreAll(NorthwindData.CustomerCustomerDemos);
client.StoreAll(NorthwindData.Regions);
client.StoreAll(NorthwindData.Territories);
client.StoreAll(NorthwindData.EmployeeTerritories);

Console.WriteLine("Took {0}ms to store the entire Northwind database ({1} records)",
    (DateTime.Now - before).TotalMilliseconds, totalRecords);

before = DateTime.Now;
var categories = client.GetAll<Category>();
var customers = client.GetAll<Customer>();
var employees = client.GetAll<Employee>();
var shippers = client.GetAll<Shipper>();
var orders = client.GetAll<Order>();
var products = client.GetAll<Product>();
var orderDetails = client.GetAll<OrderDetail>();
var customerCustomerDemos = client.GetAll<CustomerCustomerDemo>();
var regions = client.GetAll<Region>();
var territories = client.GetAll<Territory>();
var employeeTerritories = client.GetAll<EmployeeTerritory>();

Console.WriteLine("Took {0}ms to get the entire Northwind database ({1} records)",
    (DateTime.Now - before).TotalMilliseconds, totalRecords);
/*
== EXAMPLE OUTPUT ==

Took 1020.0583ms to store the entire Northwind database (3202 records)
Took 132.0076ms to get the entire Northwind database (3202 records)
*/
```


Note: The total time taken includes an extra Redis operation for each record to store the id in a Redis set for each
type as well as serializing and de-serializing each record using Service Stack's TypeSerializer.

## Lex Operations

The new [ZRANGEBYLEX](http://redis.io/commands/zrangebylex) sorted set operations allowing you to query a sorted set lexically have been added.
A good showcase for this is available on [autocomplete.redis.io](http://autocomplete.redis.io/).

These new operations are available as a 1:1 mapping with redis-server on `IRedisNativeClient`:

```csharp
public interface IRedisNativeClient
{
    ...
    byte[][] ZRangeByLex(string setId, string min, string max, int? skip, int? take);
    long ZLexCount(string setId, string min, string max);
    long ZRemRangeByLex(string setId, string min, string max);
}
```

And the more user-friendly APIs under `IRedisClient`:

```csharp
public interface IRedisClient
{
    ...
    List<string> SearchSortedSet(string setId, string start=null, string end=null);
    long SearchSortedSetCount(string setId, string start=null, string end=null);
    long RemoveRangeFromSortedSetBySearch(string setId, string start=null, string end=null);
}
```

Just like NuGet version matchers, Redis uses `[` char to express inclusiveness and `(` char for exclusiveness.
Since the `IRedisClient` APIs defaults to inclusive searches, these two APIs are the same:

```csharp
Redis.SearchSortedSetCount("zset", "a", "c")
Redis.SearchSortedSetCount("zset", "[a", "[c")
```

Alternatively you can specify one or both bounds to be exclusive by using the `(` prefix, e.g:

```csharp
Redis.SearchSortedSetCount("zset", "a", "(c")
Redis.SearchSortedSetCount("zset", "(a", "(c")
```

More API examples are available in [LexTests.cs](https://github.com/ServiceStack/ServiceStack.Redis/blob/master/tests/ServiceStack.Redis.Tests/LexTests.cs).

## HyperLog API

The development branch of Redis server (available when v3.0 is released) includes an ingenious algorithm to approximate the unique elements in a set with maximum space and time efficiency. For details about how it works see Redis's creator Salvatore's blog who [explains it in great detail](http://antirez.com/news/75). Essentially it lets you maintain an efficient way to count and merge unique elements in a set without having to store its elements.
A Simple example of it in action:

```csharp
redis.AddToHyperLog("set1", "a", "b", "c");
redis.AddToHyperLog("set1", "c", "d");
var count = redis.CountHyperLog("set1"); //4

redis.AddToHyperLog("set2", "c", "d", "e", "f");

redis.MergeHyperLogs("mergedset", "set1", "set2");

var mergeCount = redis.CountHyperLog("mergedset"); //6
```

## Scan APIs

Redis v2.8 introduced a beautiful new [SCAN](http://redis.io/commands/scan) operation that provides an optimal strategy for traversing a redis instance entire keyset in managable-size chunks utilizing only a client-side cursor and without introducing any server state. It's a higher performance alternative and should be used instead of [KEYS](http://redis.io/commands/keys) in application code. SCAN and its related operations for traversing members of Sets, Sorted Sets and Hashes are now available in the Redis Client in the following APIs:

```csharp
public interface IRedisClient
{
    ...
    IEnumerable<string> ScanAllKeys(string pattern = null, int pageSize = 1000);
    IEnumerable<string> ScanAllSetItems(string setId, string pattern = null, int pageSize = 1000);
    IEnumerable<KeyValuePair<string, double>> ScanAllSortedSetItems(string setId, string pattern = null, int pageSize = 1000);
    IEnumerable<KeyValuePair<string, string>> ScanAllHashEntries(string hashId, string pattern = null, int pageSize = 1000);    
}

public interface IRedisClientAsync
{
    IAsyncEnumerable<string> ScanAllKeysAsync(string pattern = null, int pageSize, CancellationToken ct);
    IAsyncEnumerable<string> ScanAllSetItemsAsync(string setId, string pattern = null, int pageSize, CancellationToken ct);
    IAsyncEnumerable<KeyValuePair<string, double>> ScanAllSortedSetItemsAsync(string setId, string pattern = null, int pageSize, ct);
    IAsyncEnumerable<KeyValuePair<string, string>> ScanAllHashEntriesAsync(string hashId, string pattern = null, int pageSize, ct);
}

//Low-level API
public interface IRedisNativeClient
{
    ...
    ScanResult Scan(ulong cursor, int count = 10, string match = null);
    ScanResult SScan(string setId, ulong cursor, int count = 10, string match = null);
    ScanResult ZScan(string setId, ulong cursor, int count = 10, string match = null);
    ScanResult HScan(string hashId, ulong cursor, int count = 10, string match = null);
}

public interface IRedisNativeClientAsync 
{
    ValueTask<ScanResult> ScanAsync(ulong cursor, int count = 10, string match = null, CancellationToken ct);
    ValueTask<ScanResult> SScanAsync(string setId, ulong cursor, int count = 10, string match = null, CancellationToken ct);
    ValueTask<ScanResult> ZScanAsync(string setId, ulong cursor, int count = 10, string match = null, CancellationToken ct);
    ValueTask<ScanResult> HScanAsync(string hashId, ulong cursor, int count = 10, string match = null, CancellationToken ct);
}
```

The `IRedisClient` provides a higher-level API that abstracts away the client cursor to expose a lazy Enumerable sequence to provide an optimal way to stream scanned results that integrates nicely with LINQ, e.g:

```csharp
var scanUsers = Redis.ScanAllKeys("urn:User:*");
var sampleUsers = scanUsers.Take(10000).ToList(); //Stop after retrieving 10000 user keys 
```


# Redis Async APIs
Source: https://docs.servicestack.net/redis/async

All Redis Client Managers implement both `IRedisClientsManager` and `IRedisClientsManagerAsync` so IOC registrations remain the same which can continue to register against the existing `IRedisClientsManager` interface, e.g:

```csharp
container.Register<IRedisClientsManager>(c => 
    new RedisManagerPool(redisConnectionString));
```

Where it can be used to resolve both sync `IRedisClient` and async `IRedisClientAsync` clients, e.g:

```csharp
using var syncRedis = container.Resolve<IRedisClientsManager>().GetClient();
await using var asyncRedis = await container.Resolve<IRedisClientsManager>().GetClientAsync();
```

If you want to force async-only API usage could choose to just register `IRedisClientsManagerAsync` where it only lets you resolve async only `IRedisClientAsync` and `ICacheClientAsync` clients, e.g:

```csharp
public void ConfigureServices(IServiceCollection services)
{
    services.AddSingleton<IRedisClientsManagerAsync>(c => new RedisManagerPool());
}

//... 

public class MyDep(IRedisClientsManagerAsync manager)
{
    public async Task<long> Incr(string key, uint value)
    {
        await using var redis = await manager.GetClientAsync();
        return await redis.IncrementAsync(key, value);
    }
}
```

## Usage in ServiceStack

Inside ServiceStack Services & Controllers we recommend using `GetRedisAsync()` to resolve an `IRedisClientAsync`:

```csharp
public class MyService : Service
{
    public async Task<object> Any(MyRequest request)
    {
        await using var redis = await GetRedisAsync();
        await redis.IncrementAsync(nameof(MyRequest), 1);
    }
}

public class HomeController : ServiceStackController
{
    public async Task<ActionResult> Index()
    {
        await using var redis = await GetRedisAsync();
        await redis.IncrementAsync(nameof(HomeController), 1);
    }
}
```


# Redis Custom Commands
Source: https://docs.servicestack.net/redis/custom-commands

Most of the time when waiting to use a new [Redis Command](http://redis.io/commands) you'll need to wait for an updated version of
**ServiceStack.Redis** to add support for the new commands likewise there are times when the Redis Client doesn't offer every permutation
that redis-server supports.

## API

With the new `Custom` and `RawCommand` APIs on `IRedisClient` and `IRedisNativeClient` you can now use the RedisClient to send your own
custom commands that can call adhoc Redis commands:

```csharp
public interface IRedisClient
{
    ...
    RedisText Custom(params object[] cmdWithArgs);
}

public interface IRedisNativeClient
{
    ...
    RedisData RawCommand(params object[] cmdWithArgs);
    RedisData RawCommand(params byte[][] cmdWithBinaryArgs);
}
```

## Examples

These Custom APIs take a flexible `object[]` arguments which accepts any serializable value e.g.
`byte[]`, `string`, `int` as well as any user-defined Complex Types which are transparently serialized
as JSON and send across the wire as UTF-8 bytes.

```csharp
var ret = Redis.Custom("SET", "foo", 1);          // ret.Text = "OK"

byte[] cmdSet = Commands.Set;
ret = Redis.Custom(cmdSet, "bar", "b");           // ret.Text = "OK"

ret = Redis.Custom("GET", "foo");                 // ret.Text = "1"
```

There are also
[convenient extension methods](https://github.com/ServiceStack/ServiceStack.Redis/blob/master/src/ServiceStack.Redis/RedisDataExtensions.cs)
on `RedisData` and `RedisText` that make it easy to access structured data, e.g:

```csharp
var ret = Redis.Custom(Commands.Keys, "*");
var keys = ret.GetResults();                      // keys = ["foo", "bar"]

ret = Redis.Custom(Commands.MGet, "foo", "bar");
var values = ret.GetResults();                    // values = ["1", "b"]

Enum.GetNames(typeof(DayOfWeek)).ToList()
    .ForEach(x => Redis.Custom(Commands.RPush, "DaysOfWeek", x));
ret = Redis.Custom(Commands.LRange, "DaysOfWeek", 1, -2);
var weekDays = ret.GetResults();      

weekDays.PrintDump(); // ["Monday", "Tuesday", "Wednesday", "Thursday", "Friday"]
```

and some more examples using Complex Types with the Custom APIs:

```csharp
var ret = Redis.Custom(Commands.Set, "foo", new Poco { Name = "Bar" }); // ret.Text = "OK"

ret = Redis.Custom(Commands.Get, "foo");          // ret.Text =  {"Name":"Bar"}
Poco dto = ret.GetResult<Poco>();

dto.Name.Print(); // Bar
```

This API is used in most of Redis React UI's
[redis.js](https://github.com/ServiceStackApps/RedisReact/blob/master/src/RedisReact/RedisReact/js/redis.js)
JavaScript client library where Redis server commands are made available via the
[single ServiceStack Service](https://github.com/ServiceStackApps/RedisReact/blob/a1b66603d52d2f18b96227fc455ecb5323e424c8/src/RedisReact/RedisReact.ServiceInterface/RedisServices.cs#L73):

```csharp
public object Any(CallRedis request)
{
    var args = request.Args.ToArray();
    var response = new CallRedisResponse { Result = Redis.Custom(args) };
    return response;
}
```


# Redis Managed Pub/Sub Server
Source: https://docs.servicestack.net/redis/pubsub

The Pub/Sub engine powering
[Redis ServerEvents](/redis-server-events) and [Redis MQ](/redis-mq) has been extracted
and encapsulated it into a re-usable class that can be used independently for handling messages
published to specific [Redis Pub/Sub](http://redis.io/commands#pubsub) channels.

`RedisPubSubServer` processes messages in a managed background thread that **automatically reconnects**
when the redis-server connection fails and works like an independent background Service that can be
stopped and started on command.

## API

The public API is captured in the [IRedisPubSubServer](https://github.com/ServiceStack/ServiceStack/blob/master/src/ServiceStack.Interfaces/Redis/IRedisPubSubServer.cs) interface:

```csharp
public interface IRedisPubSubServer : IDisposable
{
    IRedisClientsManager ClientsManager { get; }
    // What Channels it's subscribed to
    string[] Channels { get; }

    // Run once on initial StartUp
    Action OnInit { get; set; }
    // Called each time a new Connection is Started
    Action OnStart { get; set; }
    // Invoked when Connection is broken or Stopped
    Action OnStop { get; set; }
    // Invoked after Dispose()
    Action OnDispose { get; set; }

    // Fired when each message is received
    Action<string, string> OnMessage { get; set; }
    // Fired after successfully subscribing to the specified channels
    Action<string> OnUnSubscribe { get; set; }
    // Called when an exception occurs 
    Action<Exception> OnError { get; set; }
    // Called before attempting to Failover to a new redis master
    Action<IRedisPubSubServer> OnFailover { get; set; }

    int? KeepAliveRetryAfterMs { get; set; }
    // The Current Time for RedisServer
    DateTime CurrentServerTime { get; }

    // Current Status: Starting, Started, Stopping, Stopped, Disposed
    string GetStatus();
    // Different life-cycle stats
    string GetStatsDescription();
    
    // Subscribe to specified Channels and listening for new messages
    IRedisPubSubServer Start();
    // Close active Connection and stop running background thread
    void Stop();
    // Stop than Start
    void Restart();
}
```

## Usage

To use `RedisPubSubServer`, initialize it with the channels you want to subscribe to and assign handlers
for each of the events you want to handle. At a minimum you'll want to handle `OnMessage`:

```csharp
var clientsManager = new PooledRedisClientManager();
var redisPubSub = new RedisPubSubServer(clientsManager, "channel-1", "channel-2") {
        OnMessage = (channel, msg) => "Received '{0}' from '{1}'".Print(msg, channel)
    }.Start();
```

Calling `Start()` after it's initialized will get it to start listening and processing any messages
published to the subscribed channels.


# Redis Sentinel
Source: https://docs.servicestack.net/redis/sentinel

[Redis Sentinel](http://redis.io/topics/sentinel) is the official recommendation for running a highly
available Redis configuration by running a number of additional redis sentinel processes to actively monitor
existing redis master and slave instances ensuring they're each working as expected. If by consensus it's
determined that the master is no longer available it will automatically failover and promote one of the
replicated slaves as the new master. The sentinels also maintain an authoritative list of available
redis instances providing clients a centeral repositorty to discover available instances they can connect to.

Support for Redis Sentinel is available with the `RedisSentinel` class which listens to the available
Sentinels to source its list of available master, slave and other sentinel redis instances which it uses
to configure and maintain the Redis Client Managers, initiating any failovers as they're reported.

## Usage

To use the new Sentinel support, instead of populating the Redis Client Managers with the connection string
of the master and slave instances you would create a single `RedisSentinel` instance configured with
the connection string of the running Redis Sentinels:

```csharp
var sentinelHosts = new[]{ "sentinel1", "sentinel2:6390", "sentinel3" };
var sentinel = new RedisSentinel(sentinelHosts, masterName: "mymaster");
```

This shows a typical example of configuring a `RedisSentinel` which references 3 sentinel hosts (i.e.
the minimum number for a highly available setup which can survive any node failing).
It's also configured to look at the `mymaster` configuration set (the default master group).

::: info
Redis Sentinels can monitor more than 1 master / slave group, each with a different master group name.
:::

The default port for sentinels is **26379** (when unspecified) and as RedisSentinel can auto-discover
other sentinels, the minimum configuration required is just:

```csharp
var sentinel = new RedisSentinel("sentinel1");
```

::: info
Scanning and auto discovering of other Sentinels can be disabled with `ScanForOtherSentinels=false`
:::

### Advanced Configuration

More advanced configuration of the internal RedisManager used by `RedisSentinel` can be done by overriding
the `RedisManagerFactory` where you can specify the RedisManager it should use along with fine-grained configuration
such as configuring individual **master** and **replica** pool sizes, e.g:

```csharp
var sentinel = new RedisSentinel(sentinelHost, masterName)
{
    RedisManagerFactory = (masters, replicas) => new PooledRedisClientManager(masters, replicas,
        new RedisClientManagerConfig {
            MaxWritePoolSize = 100,
            MaxReadPoolSize = 200,
        })
};
```

## Start monitoring Sentinels

Once configured, you can start monitoring the Redis Sentinel servers and access the pre-configured
client manager with:

```csharp
IRedisClientsManager redisManager = sentinel.Start();
```

Which as before, can be registered in your preferred IOC as a **singleton** instance:

```csharp
container.Register<IRedisClientsManager>(c => sentinel.Start());
```

## Advanced Sentinel Configuration

RedisSentinel by default manages a configured `PooledRedisClientManager` instance which resolves both master
Redis clients for read/write `GetClient()` and slaves for readonly `GetReadOnlyClient()` API's.

This can be changed to use the newer `RedisManagerPool` with:

```csharp
sentinel.RedisManagerFactory = (master,slaves) => new RedisManagerPool(master);
```

## Custom Redis Connection String

The host the RedisSentinel is configured with only applies to that Sentinel Host, you can still use the flexibility of
[Redis Connection Strings](https://github.com/ServiceStack/ServiceStack.Redis#redis-connection-strings)
to configure the individual Redis Clients by specifying a custom `HostFilter`:

```csharp
sentinel.HostFilter = host => "{0}?db=1&RetryTimeout=5000".Fmt(host);
```

This will return clients configured to use Database 1 and a Retry Timeout of 5 seconds (used in new
Auto Retry feature).

## Other RedisSentinel Configuration

Whilst the above covers the popular Sentinel configuration that would typically be used, nearly every aspect
of `RedisSentinel` behavior is customizable with the configuration below:

<table>
    <tr>
        <td><b>OnSentinelMessageReceived</b></td><td>Fired when the Sentinel worker receives a message from the Sentinel Subscription</td>
    </tr>
    <tr>
        <td><b>OnFailover</b></td><td>Fired when Sentinel fails over the Redis Client Manager to a new master</td>
    </tr>
    <tr>
        <td><b>OnWorkerError</b></td><td>Fired when the Redis Sentinel Worker connection fails</td>
    </tr>
    <tr>
        <td><b>IpAddressMap</b></td><td>Map internal redis host IP's returned by Sentinels to its external IP</td>
    </tr>
    <tr>
        <td><b>ScanForOtherSentinels</b></td><td>Whether to routinely scan for other sentinel hosts (default true)</td>
    </tr>
    <tr>
        <td><b>RefreshSentinelHostsAfter</b></td><td>What interval to scan for other sentinel hosts (default 10 mins)</td>
    </tr>
    <tr>
        <td><b>WaitBetweenFailedHosts</b></td><td>How long to wait after failing before connecting to next redis instance (default 250ms)</td>
    </tr>
    <tr>
        <td><b>MaxWaitBetweenFailedHosts</b></td><td>How long to retry connecting to hosts before throwing (default 60s)</td>
    </tr>
    <tr>
        <td><b>WaitBeforeForcingMasterFailover</b></td><td>How long after consecutive failed attempts to force failover (default 60s)</td>
    </tr>
    <tr>
        <td><b>ResetWhenSubjectivelyDown</b></td><td>Reset clients when Sentinel reports redis is subjectively down (default true)</td>
    </tr>
    <tr>
        <td><b>ResetWhenObjectivelyDown</b></td><td>Reset clients when Sentinel reports redis is objectively down (default true)</td>
    </tr>
    <tr>
        <td><b>SentinelWorkerConnectTimeoutMs</b></td><td>The Max Connection time for Sentinel Worker (default 100ms)</td>
    </tr>
    <tr>
        <td><b>SentinelWorkerSendTimeoutMs</b></td><td>Max TCP Socket Send time for Sentinel Worker (default 100ms)</td>
    </tr>
    <tr>
        <td><b>SentinelWorkerReceiveTimeoutMs</b></td><td>Max TCP Socket Receive time for Sentinel Worker (default 100ms)</td>
    </tr>
</table>

## [Configure Redis Sentinel Servers](https://github.com/ServiceStack/redis-config)

[![Instant Redis Setup](https://raw.githubusercontent.com/ServiceStack/Assets/master/img/redis/instant-sentinel-setup.png)](https://github.com/ServiceStack/redis-config)

The
[redis config project](https://github.com/ServiceStack/redis-config) simplifies setting up and running a highly-available multi-node Redis Sentinel configuration including
start/stop scripts for instantly setting up the minimal
[highly available Redis Sentinel configuration](https://github.com/ServiceStack/redis-config/blob/master/README.md#3x-sentinels-monitoring-1x-master-and-2x-slaves)
on a single (or multiple) Windows, OSX or Linux servers. This single-server/multi-process configuration
is ideal for setting up a working sentinel configuration on a single dev workstation or remote server.

The redis-config repository also includes the
[MS OpenTech Windows redis binaries](https://github.com/ServiceStack/redis-windows#running-microsofts-native-port-of-redis)
and doesn't require any software installation.

## Windows Usage

To run the included Sentinel configuration, clone the redis-config repo on the server you want to run it on:

```
git clone https://github.com/ServiceStack/redis-config.git
```

Then Start 1x Master, 2x Slaves and 3x Sentinel redis-servers with:

```
cd redis-config\sentinel3\windows
start-all.cmd
```

Shutdown started instances:

```
stop-all.cmd
```

If you're running the redis processes locally on your dev workstation the minimal configuration to connect
to the running instances is just:

```csharp
var sentinel = new RedisSentinel("127.0.0.1:26380");
container.Register(c => sentinel.Start());
```

## Localhost vs Network IP's

The sentinel configuration assumes all redis instances are running locally on **127.0.0.1**.
If you're instead running it on a remote server that you want all developers in your network to be
able to access, you'll need to either change the IP Address in the `*.conf` files to use the servers
Network IP. Otherwise you can leave the defaults and use the `RedisSentinel` IP Address Map feature
to transparently map localhost IP's to the Network IP that each pc on your network can connect to.

E.g. if this is running on a remote server with a **10.0.0.9** Network IP, it can be configured with:

```csharp
var sentinel = new RedisSentinel("10.0.0.9:26380") {
    IpAddressMap = {
        {"127.0.0.1", "10.0.0.9"},
    }
};
container.Register(c => sentinel.Start());
```

## Google Cloud - [Click to Deploy Redis](https://github.com/ServiceStack/redis-config/blob/master/README.md#google-cloud---click-to-deploy-redis)

The easiest Cloud Service we've found that can instantly set up a multi node-Redis Sentinel Configuration
is using Google Cloud's
[click to deploy Redis feature](https://cloud.google.com/solutions/redis/click-to-deploy)
available from the Google Cloud Console under **Deploy & Manage**:

![](https://raw.githubusercontent.com/ServiceStack/Assets/master/img/redis/sentinel3-gcloud-01.png)

Clicking **Deploy** button will let you configure the type, size and location where you want to deploy the
Redis VM's. See the
[full Click to Deploy Redis guide](https://github.com/ServiceStack/redis-config/blob/master/README.md#google-cloud---click-to-deploy-redis)
for a walk-through on setting up and inspecting a highly-available redis configuration on Google Cloud.

## Change to use RedisManagerPool

By default, RedisSentinel uses a `PooledRedisClientManager`, this can be changed to use the
newer `RedisManagerPool` with:

```csharp
sentinel.RedisManagerFactory = (master,replicas) => new RedisManagerPool(master);
```

## Start monitoring Sentinels

Once configured, you can start monitoring the Redis Sentinel servers and access the pre-configured
client manager with:

```csharp
IRedisClientsManager redisManager = sentinel.Start();
```

Which as before, can be registered in your preferred IOC as a **singleton** instance:

```csharp
container.Register<IRedisClientsManager>(c => sentinel.Start());
```

## [Configure Redis Sentinel Servers](https://github.com/ServiceStack/redis-config)

[![Instant Redis Setup](https://raw.githubusercontent.com/ServiceStack/Assets/master/img/redis/instant-sentinel-setup.png)](https://github.com/ServiceStack/redis-config)

See the
[redis config project](https://github.com/ServiceStack/redis-config) for a quick way to setup up
the minimal
[highly available Redis Sentinel configuration](https://github.com/ServiceStack/redis-config/blob/master/README.md#3x-sentinels-monitoring-1x-master-and-2x-slaves)
including start/stop scripts for instantly running multiple redis instances on a single (or multiple)
Windows, OSX or Linux servers.

## Redis Stats

You can use the `RedisStats` class for visibility and introspection into your running instances.
The [Redis Stats](/redis/stats) lists the stats available.

## Automatic Retries

The built-in [Automatic Retries](/redis/automatic-retries) support improves the resilience of client connections, 
`RedisClient` will transparently retry failed Redis operations due to Socket and I/O Exceptions in an exponential 
backoff starting from **10ms** up until the `RetryTimeout` of **10000ms**. These defaults can be tweaked with:

```csharp
RedisConfig.DefaultRetryTimeout = 10000;
RedisConfig.BackOffMultiplier = 10;
```


# RedisClient LUA APIs
Source: https://docs.servicestack.net/redis/lua

The `IRedisClient` APIs for [redis server-side LUA support](http://redis.io/commands/eval) have been re-factored into the more user-friendly APIs below:

## API

```csharp
public interface IRedisClient 
{
    //Eval/Lua operations 
    T ExecCachedLua<T>(string scriptBody, Func<string, T> scriptSha1);

    RedisText ExecLua(string body, params string[] args);
    RedisText ExecLua(string luaBody, string[] keys, string[] args);
    RedisText ExecLuaSha(string sha1, params string[] args);
    RedisText ExecLuaSha(string sha1, string[] keys, string[] args);

    string ExecLuaAsString(string luaBody, params string[] args);
    string ExecLuaAsString(string luaBody, string[] keys, string[] args);
    string ExecLuaShaAsString(string sha1, params string[] args);
    string ExecLuaShaAsString(string sha1, string[] keys, string[] args);
    
    int ExecLuaAsInt(string luaBody, params string[] args);
    int ExecLuaAsInt(string luaBody, string[] keys, string[] args);
    int ExecLuaShaAsInt(string sha1, params string[] args);
    int ExecLuaShaAsInt(string sha1, string[] keys, string[] args);

    List<string> ExecLuaAsList(string luaBody, params string[] args);
    List<string> ExecLuaAsList(string luaBody, string[] keys, string[] args);
    List<string> ExecLuaShaAsList(string sha1, params string[] args);
    List<string> ExecLuaShaAsList(string sha1, string[] keys, string[] args);

    string CalculateSha1(string luaBody);
    
    bool HasLuaScript(string sha1Ref);
    Dictionary<string, bool> WhichLuaScriptsExists(params string[] sha1Refs);
    void RemoveAllLuaScripts();
    void KillRunningLuaScript();
    string LoadLuaScript(string body);
}
```

## Efficient SCAN in LUA

The C# API below returns the first 10 results matching the `key:*` pattern:

```csharp
var keys = Redis.ScanAllKeys(pattern: "key:*", pageSize: 10)
    .Take(10).ToList();
```

However the C# Streaming API above requires an unknown number of Redis Operations (bounded to the number of keys in Redis)
to complete the request. The number of SCAN calls can be reduced by choosing a higher `pageSize` to tell Redis to scan more keys
each time the SCAN operation is called.

As the number of API calls has the potential to result in a large number of Redis Operations, it can end up yielding an unacceptable
delay due to the latency of multiple dependent remote network calls. An easy solution is to instead have the multiple SCAN calls
performed in-process on the Redis Server, eliminating the network latency of multiple SCAN calls, e.g:

```csharp
const string FastScanScript = @"
local limit = tonumber(ARGV[2])
local pattern = ARGV[1]
local cursor = 0
local len = 0
local results = {}
repeat
    local r = redis.call('scan', cursor, 'MATCH', pattern, 'COUNT', limit)
    cursor = tonumber(r[1])
    for k,v in ipairs(r[2]) do
        table.insert(results, v)
        len = len + 1
        if len == limit then break end
    end
until cursor == 0 or len == limit
return results";

RedisText r = redis.ExecLua(FastScanScript, "key:*", "10");
r.Children.Count.Print() //= 10
```

The `ExecLua` API returns this complex LUA table response in the `Children` collection of the `RedisText` Response.

### Alternative Complex API Response

Another way to return complex data structures in a LUA operation is to serialize the result as JSON

```lua
return cjson.encode(results)
```

Which you can access as raw JSON by parsing the response as a String with:

```csharp
string json = redis.ExecLuaAsString(FastScanScript, "key:*", "10");
```

::: info
This is also the approach used in Redis React's [RedisServices](https://github.com/ServiceStackApps/RedisReact/blob/a1b66603d52d2f18b96227fc455ecb5323e424c8/src/RedisReact/RedisReact.ServiceInterface/RedisServices.cs#L60).
:::

## ExecCachedLua

ExecCachedLua is a convenient high-level API that eliminates the bookkeeping required for executing high-performance server LUA
Scripts which suffers from many of the problems that RDBMS stored procedures have which depends on pre-existing state in the RDBMS
that needs to be updated with the latest version of the Stored Procedure.

With Redis LUA you either have the option to send, parse, load then execute the entire LUA script each time it's called or
alternatively you could pre-load the LUA Script into Redis once on StartUp and then execute it using the Script's SHA1 hash.
The issue with this is that if the Redis server is accidentally flushed you're left with a broken application relying on a
pre-existing script that's no longer there. The new `ExecCachedLua` API provides the best of both worlds where it will always
execute the compiled SHA1 script, saving bandwidth and CPU but will also re-create the LUA Script if it no longer exists.

You can instead execute the compiled LUA script above by its SHA1 identifier, which continues to work regardless if it never existed
or was removed at runtime, e.g:

```csharp
// #1: Loads LUA script and caches SHA1 hash in Redis Client
r = redis.ExecCachedLua(FastScanScript, sha1 =>
    redis.ExecLuaSha(sha1, "key:*", "10"));

// #2: Executes using cached SHA1 hash
r = redis.ExecCachedLua(FastScanScript, sha1 =>
    redis.ExecLuaSha(sha1, "key:*", "10"));

// Deletes all existing compiled LUA scripts 
redis.ScriptFlush();

// #3: Executes using cached SHA1 hash, gets NOSCRIPT Error, 
//     re-creates then re-executes the LUA script using its SHA1 hash
r = redis.ExecCachedLua(FastScanScript, sha1 =>
    redis.ExecLuaSha(sha1, "key:*", "10"));
```

## Usage Examples

Here's how you can implement a **ZPOP** in Lua to remove the items with the lowest rank from a sorted set:

```csharp
var luaBody = @"
    local val = redis.call('zrange', KEYS[1], 0, ARGV[1]-1)
    if val then redis.call('zremrangebyrank', KEYS[1], 0, ARGV[1]-1) end
    return val";

var i = 0;
var alphabet = 26.Times(c => ((char)('A' + c)).ToString());
alphabet.ForEach(x => Redis.AddItemToSortedSet("zalphabet", x, i++));

//Remove the letters with the lowest rank from the sorted set 'zalphabet'
var letters = Redis.ExecLuaAsList(luaBody, keys: new[] { "zalphabet" }, args: new[] { "3" });
letters.PrintDump(); //[A, B, C]
```

And how to implement **ZREVPOP** to remove items with the highest rank from a sorted set:

```csharp
var luaBody = @"
    local val = redis.call('zrange', KEYS[1], -ARGV[1], -1)
    if val then redis.call('zremrangebyrank', KEYS[1], -ARGV[1], -1) end
    return val";

var i = 0;
var alphabet = 26.Times(c => ((char)('A' + c)).ToString());
alphabet.ForEach(x => Redis.AddItemToSortedSet("zalphabet", x, i++));

//Remove the letters with the highest rank from the sorted set 'zalphabet'
List<string> letters = Redis.ExecLuaAsList(luaBody, 
    keys: new[] { "zalphabet" }, args: new[] { "3" });

letters.PrintDump(); //[X, Y, Z]
```

## Other examples

Returning an `int`:

```csharp
int intVal = Redis.ExecLuaAsInt("return 123"); //123
int intVal = Redis.ExecLuaAsInt("return ARGV[1] + ARGV[2]", "10", "20"); //30
```

Returning an `string`:

```csharp
//Hello, Redis Lua!
var strVal = Redis.ExecLuaAsString(@"return 'Hello, ' .. ARGV[1] .. '!'", "Redis Lua");
```

Returning a `List` of strings:

```csharp
Enum.GetNames(typeof(DayOfWeek)).ToList()
    .ForEach(x => Redis.AddItemToList("DaysOfWeek", x));

var daysOfWeek = Redis.ExecLuaAsList("return redis.call('LRANGE', 'DaysOfWeek', 0, -1)");
daysOfWeek.PrintDump(); //[Sunday, Monday, Tuesday, ...]
```

More examples can be found in the [Redis Eval Lua tests](https://github.com/ServiceStack/ServiceStack.Redis/blob/master/tests/ServiceStack.Redis.Tests/RedisClientEvalTests.cs)


# Redis Distributed Locking
Source: https://docs.servicestack.net/redis/distributed-locking

This page shows how to take advantage of Redis's fast atomic server operations to enable high-performance [distributed locks](https://redis.io/docs/reference/patterns/distributed-locks/) that can span across multiple app servers.

## Achieving High Performance, Distributed Locking with Redis 

When you have a high-performance, scalable network data structure server like Redis accessible to your back end systems, a whole range of technical possibilities open up that were previously difficult to achieve. Something like multi-server-wide application-level locks were previously only achievable using dedicated, centralized infrastructure and the crafting of some carefully custom concurrent programming logic. 

With Redis this becomes a trivial task as you get simplified access to rich atomic server operations that complete within a fraction of a millisecond. So the same normally CPU-intensive load generated by distributed locking when using a remote filesystem or RDBMS is barely noticeable on a Redis server.

[ServiceStack's C# Redis Client](https://github.com/ServiceStack/ServiceStack.Redis) takes advantage of the convenience and safety offered by .NET's IDisposable interface and Redis's [SETNX operation](https://redis.io/commands/setnx) to provide a simple API to implement your own **custom distributed locks**, ensuring at all times that only 1 client at a time can execute the protected logic. While one of the Redis clients obtains the lock, the other clients enter into an 'exponential retry back-off multiplier state' continually retrying to obtain the lock at random intervals until they are finally successful.

## Simple API Usage 

The locking functionality is available on the [IRedisClient](/redis/client) and [IRedisTypedClient](/redis/typed-client) interfaces, the relevant portion of which is displayed below.

```csharp
public interface IRedisClient
{
    ...
    IDisposable AcquireLock(string key);
    IDisposable AcquireLock(string key, TimeSpan timeOut);
}
```

::: tip
The above implementation does not include the ability to auto-recover from a crashed client, power or network failure, so under rare conditions it is possible for all clients to be deadlocked indefinitely waiting on a lock that is never released. In these cases it's wise to supply a `TimeOut` or manually recover from 'zombie locks' by clearing them all on server restarts, etc.
:::

To reiterate: if you specify a `TimeOut`, the client will treat the lock as invalid once the timeout expires, and thus grab the lock.

Below are a couple examples showing how to use the API in some typical usage scenarios. The full runnable source code of the following examples are 
[available here](https://github.com/ServiceStack/ServiceStack/blob/main/ServiceStack.Redis/tests/ServiceStack.Redis.Tests/Examples/SimpleLocks.cs).

## Example: Multiple clients acquiring the same lock 

The example below shows the behaviour of running 5 concurrent clients trying to acquire the same lock at the same time.
An artificial delay is added inside the lock to simulate a cpu-intensive workload.

```csharp
//The number of concurrent clients to run
const int noOfClients = 5;
var asyncResults = new List<IAsyncResult>(noOfClients);
for (var i = 1; i <= noOfClients; i++)
{
    var clientNo = i;
    var actionFn = (Action)delegate
    {
        var redisClient = new RedisClient(TestConfig.SingleHost);
        using (redisClient.AcquireLock("testlock"))
        {
            Console.WriteLine("client {0} acquired lock", clientNo);
            var counter = redisClient.Get<int>("atomic-counter");

            //Add an artificial delay to demonstrate locking behaviour
            Thread.Sleep(100);

            redisClient.Set("atomic-counter", counter + 1);
            Console.WriteLine("client {0} released lock", clientNo);
        }
    };

    //Asynchronously invoke the above delegate in a background thread
    asyncResults.Add(actionFn.BeginInvoke(null, null));
}

//Wait at most 1 second for all the threads to complete
asyncResults.WaitAll(TimeSpan.FromSeconds(1));

//Print out the 'atomic-counter' result
using (var redisClient = new RedisClient(TestConfig.SingleHost))
{
    var counter = redisClient.Get<int>("atomic-counter");
    Console.WriteLine("atomic-counter after 1sec: {0}", counter);
}

/*Output:
client 1 acquired lock
client 1 released lock
client 3 acquired lock
client 3 released lock
client 4 acquired lock
client 4 released lock
client 5 acquired lock
client 5 released lock
client 2 acquired lock
client 2 released lock
atomic-counter after 1sec: 5
*/
```

When you acquire a lock without specifying a `TimeOut` as seen in the above example, each waiting client goes into an indefinite loop retrying to acquire the lock until its successful. 
If by some chance you had some rogue code not following convention and implementing logic within the disposable scope or worse short circuiting execution using `Thread.Abort`, 
you could potentially run into a deadlock situation. This is why it is generally a good idea to specify a `TimeOut` whenever you make a blocking call. So like all good blocking API's 
the client lets you specify an optional `TimeOut` parameter as seen in the following example:

## Example: Acquiring a lock with Time Out 

```csharp
var redisClient = new RedisClient(TestConfig.SingleHost);

//Initialize and set counter to '1'
redisClient.Increment("atomic-counter"); 

//Acquire lock and never release it
redisClient.AcquireLock("testlock");

var waitFor = TimeSpan.FromSeconds(2);
var now = DateTime.Now;

try
{
    using (var newClient = new RedisClient(TestConfig.SingleHost))
    {
        //Attempt to acquire a lock with a 2 second timeout
        using (newClient.AcquireLock("testlock", waitFor))
        {
            //If lock was acquired this would be incremented to '2'
            redisClient.Increment("atomic-counter"); 
        }
    }
}
catch (TimeoutException tex)
{
    var timeTaken = DateTime.Now - now;
    Console.WriteLine("After '{0}', Received TimeoutException: '{1}'", timeTaken, tex.Message);

    var counter = redisClient.Get<int>("atomic-counter");
    Console.WriteLine("atomic-counter remains at '{0}'", counter);
}
/*Output:
After '00:00:02.3321334', Received TimeoutException: 'Exceeded timeout of 00:00:02'
atomic-counter remains at '1'
*/
```


# Troubleshooting issues
Source: https://docs.servicestack.net/redis/troubleshooting

## Debugging Data Corruption Issues

An issue that can be hard to debug is if the same `RedisClient` instance is shared across multiple threads which can result in returning corrupted data.
Typically, this is a result of using `IRedisClient` field in a singleton instance or sharing it as a static instance. To prevent this, each Thread that
uses Redis should retrieve the redis client within a using statement, e.g:

```csharp
using var redis = redisManager.GetClient();
//...
```

Unfortunately the call-site which returns the corrupted response or runtime Exception doesn't identify where else the Redis client instance was being used.
To help identify where client instances are being used you can assert that the client is only used in the Thread that resolved it from the pool with:

```csharp
RedisConfig.AssertAccessOnlyOnSameThread = true;
```

This captures the Thread's StackTrace each time the client is resolved from the pool which as it adds a lot of overhead, should only be enabled when debugging connection issues.

If it does detect the client is being accessed from a different thread it will throw a `InvalidAccessException` with the message containing the different **Thread Ids** and the **original StackTrace** where the client was resolved from the pool. You can compare this with the StackTrace of the Exception to hopefully identify where the client is being improperly used.

## Avoiding Concurrent Usage issues

What to look out for in your code-base to prevent against multiple concurrent usage of a `IRedisClient` instance:

- Use `IRedisClient` redis instance client within a `using` statement
- Never use a client instance after it has been disposed
- Never use (or return) a "server collection or resource" (e.g. [Redis.Lists](#simple-example-using-redis-lists), lock) after the client has been disposed
- Never keep a Singleton or `static` instance to a redis client (just the `IRedisClientsManager` factory)
- Never use the same redis client in multiple threads, i.e. have each thread resolve their own client from the factory


# Redis Client
Source: https://docs.servicestack.net/redis/client

Details of the IRedisClient API implemented by the [ServiceStack.Redis client](https://github.com/ServiceStack/ServiceStack.Redis)

## Introduction

This is a friendly, more descriptive API implemented by the [ServiceStack.Redis client](https://github.com/ServiceStack/ServiceStack.Redis)
that provides access to key values as strings (or collection of strings for Redis lists and sets).

Use this API if you just need to access values as strings or you want to have control over your own text serialization format.

## API

```csharp
public interface IRedisClient
    : IEntityStore, ICacheClient
{
    //Basic Redis Connection operations
    long Db { get; set; }
    long DbSize { get; }
    Dictionary<string, string> Info { get; }
    DateTime LastSave { get; }
    string Host { get; }
    int Port { get; }
    int ConnectTimeout { get; set; }
    int RetryTimeout { get; set; }
    int RetryCount { get; set; }
    int SendTimeout { get; set; }
    string Password { get; set; }
    bool HadExceptions { get; }

    void Save();
    void SaveAsync();
    void Shutdown();
    void RewriteAppendOnlyFileAsync();
    void FlushDb();

    //Basic Redis Connection Info
    string this[string key] { get; set; }

    List<string> GetAllKeys();
    void SetEntry(string key, string value);
    void SetEntry(string key, string value, TimeSpan expireIn);
    bool SetEntryIfNotExists(string key, string value);
    void SetAll(IEnumerable<string> keys, IEnumerable<string> values);
    void SetAll(Dictionary<string, string> map);
    string GetEntry(string key);
    string GetValue(string key);
    string GetAndSetEntry(string key, string value);
    List<string> GetValues(List<string> keys);
    List<T> GetValues<T>(List<string> keys);
    Dictionary<string, string> GetValuesMap(List<string> keys);
    Dictionary<string, T> GetValuesMap<T>(List<string> keys);
    long AppendToValue(string key, string value);
    void RenameKey(string fromName, string toName);

    //store POCOs as hash
    T GetFromHash<T>(object id);
    void StoreAsHash<T>(T entity);

    object StoreObject(object entity);

    bool ContainsKey(string key);
    bool RemoveEntry(params string[] args);
    long IncrementValue(string key);
    long IncrementValueBy(string key, int count);
    long IncrementValueBy(string key, long count);
    double IncrementValueBy(string key, double count);
    long DecrementValue(string key);
    long DecrementValueBy(string key, int count);
    List<string> SearchKeys(string pattern);

    RedisKeyType GetEntryType(string key);
    string GetRandomKey();
    bool ExpireEntryIn(string key, TimeSpan expireIn);
    bool ExpireEntryAt(string key, DateTime expireAt);
    TimeSpan GetTimeToLive(string key);
    List<string> GetSortedEntryValues(string key, int startingFrom, int endingAt);

    //Store entities without registering entity ids
    void WriteAll<TEntity>(IEnumerable<TEntity> entities);

    //Scan APIs
    IEnumerable<string> ScanAllKeys(string pattern = null, int pageSize = 1000);
    IEnumerable<string> ScanAllSetItems(string setId, string pattern = null, int pageSize = 1000);
    IEnumerable<KeyValuePair<string, double>> ScanAllSortedSetItems(string setId, string pattern = null, int pageSize = 1000);
    IEnumerable<KeyValuePair<string, string>> ScanAllHashEntries(string hashId, string pattern = null, int pageSize = 1000);

    //Hyperlog APIs
    bool AddToHyperLog(string key, params string[] elements);
    long CountHyperLog(string key);
    void MergeHyperLogs(string toKey, params string[] fromKeys);

    /// <summary>
    /// Returns a high-level typed client API
    /// </summary>
    /// <typeparam name="T"></typeparam>
    IRedisTypedClient<T> As<T>();

    IHasNamed<IRedisList> Lists { get; set; }
    IHasNamed<IRedisSet> Sets { get; set; }
    IHasNamed<IRedisSortedSet> SortedSets { get; set; }
    IHasNamed<IRedisHash> Hashes { get; set; }

    IRedisTransaction CreateTransaction();
    IRedisPipeline CreatePipeline();

    IDisposable AcquireLock(string key);
    IDisposable AcquireLock(string key, TimeSpan timeOut);

    #region Redis pubsub

    void Watch(params string[] keys);
    void UnWatch();
    IRedisSubscription CreateSubscription();
    long PublishMessage(string toChannel, string message);

    #endregion


    #region Set operations

    HashSet<string> GetAllItemsFromSet(string setId);
    void AddItemToSet(string setId, string item);
    void AddRangeToSet(string setId, List<string> items);
    void RemoveItemFromSet(string setId, string item);
    string PopItemFromSet(string setId);
    void MoveBetweenSets(string fromSetId, string toSetId, string item);
    long GetSetCount(string setId);
    bool SetContainsItem(string setId, string item);
    HashSet<string> GetIntersectFromSets(params string[] setIds);
    void StoreIntersectFromSets(string intoSetId, params string[] setIds);
    HashSet<string> GetUnionFromSets(params string[] setIds);
    void StoreUnionFromSets(string intoSetId, params string[] setIds);
    HashSet<string> GetDifferencesFromSet(string fromSetId, params string[] withSetIds);
    void StoreDifferencesFromSet(string intoSetId, string fromSetId, params string[] withSetIds);
    string GetRandomItemFromSet(string setId);

    #endregion


    #region List operations

    List<string> GetAllItemsFromList(string listId);
    List<string> GetRangeFromList(string listId, int startingFrom, int endingAt);
    List<string> GetRangeFromSortedList(string listId, int startingFrom, int endingAt);
    List<string> GetSortedItemsFromList(string listId, SortOptions sortOptions);
    void AddItemToList(string listId, string value);
    void AddRangeToList(string listId, List<string> values);
    void PrependItemToList(string listId, string value);
    void PrependRangeToList(string listId, List<string> values);

    void RemoveAllFromList(string listId);
    string RemoveStartFromList(string listId);
    string BlockingRemoveStartFromList(string listId, TimeSpan? timeOut);
    ItemRef BlockingRemoveStartFromLists(string[] listIds, TimeSpan? timeOut);
    string RemoveEndFromList(string listId);
    void TrimList(string listId, int keepStartingFrom, int keepEndingAt);
    long RemoveItemFromList(string listId, string value);
    long RemoveItemFromList(string listId, string value, int noOfMatches);
    long GetListCount(string listId);
    string GetItemFromList(string listId, int listIndex);
    void SetItemInList(string listId, int listIndex, string value);

    //Queue operations
    void EnqueueItemOnList(string listId, string value);
    string DequeueItemFromList(string listId);
    string BlockingDequeueItemFromList(string listId, TimeSpan? timeOut);
    ItemRef BlockingDequeueItemFromLists(string[] listIds, TimeSpan? timeOut);

    //Stack operations
    void PushItemToList(string listId, string value);
    string PopItemFromList(string listId);
    string BlockingPopItemFromList(string listId, TimeSpan? timeOut);
    ItemRef BlockingPopItemFromLists(string[] listIds, TimeSpan? timeOut);
    string PopAndPushItemBetweenLists(string fromListId, string toListId);
    string BlockingPopAndPushItemBetweenLists(string fromListId, string toListId, TimeSpan? timeOut);

    #endregion


    #region Sorted Set operations

    bool AddItemToSortedSet(string setId, string value);
    bool AddItemToSortedSet(string setId, string value, double score);
    bool AddRangeToSortedSet(string setId, List<string> values, double score);
    bool AddRangeToSortedSet(string setId, List<string> values, long score);
    bool RemoveItemFromSortedSet(string setId, string value);
    string PopItemWithLowestScoreFromSortedSet(string setId);
    string PopItemWithHighestScoreFromSortedSet(string setId);
    bool SortedSetContainsItem(string setId, string value);
    double IncrementItemInSortedSet(string setId, string value, double incrementBy);
    double IncrementItemInSortedSet(string setId, string value, long incrementBy);
    long GetItemIndexInSortedSet(string setId, string value);
    long GetItemIndexInSortedSetDesc(string setId, string value);
    List<string> GetAllItemsFromSortedSet(string setId);
    List<string> GetAllItemsFromSortedSetDesc(string setId);
    List<string> GetRangeFromSortedSet(string setId, int fromRank, int toRank);
    List<string> GetRangeFromSortedSetDesc(string setId, int fromRank, int toRank);
    IDictionary<string, double> GetAllWithScoresFromSortedSet(string setId);
    IDictionary<string, double> GetRangeWithScoresFromSortedSet(string setId, int fromRank, int toRank);
    IDictionary<string, double> GetRangeWithScoresFromSortedSetDesc(string setId, int fromRank, int toRank);
    List<string> GetRangeFromSortedSetByLowestScore(string setId, string fromStringScore, string toStringScore);
    List<string> GetRangeFromSortedSetByLowestScore(string setId, string fromStringScore, string toStringScore, int? skip, int? take);
    List<string> GetRangeFromSortedSetByLowestScore(string setId, double fromScore, double toScore);
    List<string> GetRangeFromSortedSetByLowestScore(string setId, long fromScore, long toScore);
    List<string> GetRangeFromSortedSetByLowestScore(string setId, double fromScore, double toScore, int? skip, int? take);
    List<string> GetRangeFromSortedSetByLowestScore(string setId, long fromScore, long toScore, int? skip, int? take);
    IDictionary<string, double> GetRangeWithScoresFromSortedSetByLowestScore(string setId, string fromStringScore, string toStringScore);
    IDictionary<string, double> GetRangeWithScoresFromSortedSetByLowestScore(string setId, string fromStringScore, string toStringScore, int? skip, int? take);
    IDictionary<string, double> GetRangeWithScoresFromSortedSetByLowestScore(string setId, double fromScore, double toScore);
    IDictionary<string, double> GetRangeWithScoresFromSortedSetByLowestScore(string setId, long fromScore, long toScore);
    IDictionary<string, double> GetRangeWithScoresFromSortedSetByLowestScore(string setId, double fromScore, double toScore, int? skip, int? take);
    IDictionary<string, double> GetRangeWithScoresFromSortedSetByLowestScore(string setId, long fromScore, long toScore, int? skip, int? take);
    List<string> GetRangeFromSortedSetByHighestScore(string setId, string fromStringScore, string toStringScore);
    List<string> GetRangeFromSortedSetByHighestScore(string setId, string fromStringScore, string toStringScore, int? skip, int? take);
    List<string> GetRangeFromSortedSetByHighestScore(string setId, double fromScore, double toScore);
    List<string> GetRangeFromSortedSetByHighestScore(string setId, long fromScore, long toScore);
    List<string> GetRangeFromSortedSetByHighestScore(string setId, double fromScore, double toScore, int? skip, int? take);
    List<string> GetRangeFromSortedSetByHighestScore(string setId, long fromScore, long toScore, int? skip, int? take);
    IDictionary<string, double> GetRangeWithScoresFromSortedSetByHighestScore(string setId, string fromStringScore, string toStringScore);
    IDictionary<string, double> GetRangeWithScoresFromSortedSetByHighestScore(string setId, string fromStringScore, string toStringScore, int? skip, int? take);
    IDictionary<string, double> GetRangeWithScoresFromSortedSetByHighestScore(string setId, double fromScore, double toScore);
    IDictionary<string, double> GetRangeWithScoresFromSortedSetByHighestScore(string setId, long fromScore, long toScore);
    IDictionary<string, double> GetRangeWithScoresFromSortedSetByHighestScore(string setId, double fromScore, double toScore, int? skip, int? take);
    IDictionary<string, double> GetRangeWithScoresFromSortedSetByHighestScore(string setId, long fromScore, long toScore, int? skip, int? take);
    long RemoveRangeFromSortedSet(string setId, int minRank, int maxRank);
    long RemoveRangeFromSortedSetByScore(string setId, double fromScore, double toScore);
    long RemoveRangeFromSortedSetByScore(string setId, long fromScore, long toScore);
    long GetSortedSetCount(string setId);
    long GetSortedSetCount(string setId, string fromStringScore, string toStringScore);
    long GetSortedSetCount(string setId, long fromScore, long toScore);
    long GetSortedSetCount(string setId, double fromScore, double toScore);
    double GetItemScoreInSortedSet(string setId, string value);
    long StoreIntersectFromSortedSets(string intoSetId, params string[] setIds);
    long StoreUnionFromSortedSets(string intoSetId, params string[] setIds);
    List<string> SearchSortedSet(string setId, string start = null, string end = null, int? skip = null, int? take = null);
    long SearchSortedSetCount(string setId, string start = null, string end = null);
    long RemoveRangeFromSortedSetBySearch(string setId, string start = null, string end = null);

    #endregion


    #region Hash operations

    bool HashContainsEntry(string hashId, string key);
    bool SetEntryInHash(string hashId, string key, string value);
    bool SetEntryInHashIfNotExists(string hashId, string key, string value);
    void SetRangeInHash(string hashId, IEnumerable<KeyValuePair<string, string>> keyValuePairs);
    long IncrementValueInHash(string hashId, string key, int incrementBy);
    double IncrementValueInHash(string hashId, string key, double incrementBy);
    string GetValueFromHash(string hashId, string key);
    List<string> GetValuesFromHash(string hashId, params string[] keys);
    bool RemoveEntryFromHash(string hashId, string key);
    long GetHashCount(string hashId);
    List<string> GetHashKeys(string hashId);
    List<string> GetHashValues(string hashId);
    Dictionary<string, string> GetAllEntriesFromHash(string hashId);

    #endregion


    #region Eval/Lua operations

    string ExecLuaAsString(string luaBody, params string[] args);
    string ExecLuaAsString(string luaBody, string[] keys, string[] args);
    string ExecLuaShaAsString(string sha1, params string[] args);
    string ExecLuaShaAsString(string sha1, string[] keys, string[] args);

    long ExecLuaAsInt(string luaBody, params string[] args);
    long ExecLuaAsInt(string luaBody, string[] keys, string[] args);
    long ExecLuaShaAsInt(string sha1, params string[] args);
    long ExecLuaShaAsInt(string sha1, string[] keys, string[] args);

    List<string> ExecLuaAsList(string luaBody, params string[] args);
    List<string> ExecLuaAsList(string luaBody, string[] keys, string[] args);
    List<string> ExecLuaShaAsList(string sha1, params string[] args);
    List<string> ExecLuaShaAsList(string sha1, string[] keys, string[] args);

    string CalculateSha1(string luaBody);

    bool HasLuaScript(string sha1Ref);
    Dictionary<string, bool> WhichLuaScriptsExists(params string[] sha1Refs);
    void RemoveAllLuaScripts();
    void KillRunningLuaScript();
    string LoadLuaScript(string body);

    #endregion

}
```

Generally, if you only have basic persistence needs I would recommend developing against the above common data access API as it is easier for
other persistence providers to implement and increases the likely-hood that your existing library can be reused as-is to have your POCO types
persist against other data stores i.e. against an RDBMS with OrmLite, etc.


# Redis Typed Client
Source: https://docs.servicestack.net/redis/typed-client

A 'strongly-typed' API available on [Service Stack's C# Redis Client](https://github.com/ServiceStack/ServiceStack.Redis) to make all Redis Value operations to apply against any c# type

## Strongly typed Generic Client API

Below is the strongly-typed API that you have access to after you call `IRedisClient.As<T>()` e.g.:

```csharp
using (var redisClient = new RedisClient())
{
    var redis = redisClient.As<MyPocoType>();
}
```

The redis variable now holds a strongly-typed generic client that allows Redis value operations to apply against `MyPocoType`.
The interface below lists all available operations:

## API

```csharp
public interface IRedisTypedClient<T>
    : IBasicPersistenceProvider<T>
{
    IHasNamed<IRedisList<T>> Lists { get; set; }
    IHasNamed<IRedisSet<T>> Sets { get; set; }
    IHasNamed<IRedisSortedSet<T>> SortedSets { get; set; }
    IRedisHash<TKey, T> GetHash<TKey>(string hashId);

    IRedisTypedTransaction<T> CreateTransaction();

    IDisposable AcquireLock();
    IDisposable AcquireLock(TimeSpan timeOut);

    int Db { get; set; }
    List<string> GetAllKeys();

    T this[string key] { get; set; }

    string SequenceKey { get; set; }
    void SetSequence(int value);
    int GetNextSequence();
    RedisKeyType GetEntryType(string key);
    string GetRandomKey();

    void SetEntry(string key, T value);
    void SetEntry(string key, T value, TimeSpan expireIn);
    bool SetEntryIfNotExists(string key, T value);
    T GetValue(string key);
    T GetAndSetValue(string key, T value);
    bool ContainsKey(string key);
    bool RemoveEntry(string key);
    bool RemoveEntry(params string[] args);
    bool RemoveEntry(params IHasStringId[] entities);
    int IncrementValue(string key);
    int IncrementValueBy(string key, int count);
    int DecrementValue(string key);
    int DecrementValueBy(string key, int count);
    bool ExpireEntryIn(string key, TimeSpan expiresAt);
    bool ExpireEntryAt(string key, DateTime dateTime);
    TimeSpan GetTimeToLive(string key);
    void Save();
    void SaveAsync();
    void FlushDb();
    void FlushAll();
    T[] SearchKeys(string pattern);
    List<T> GetValues(List<string> keys);
    List<T> GetSortedEntryValues(IRedisSet<T> fromSet, int startingFrom, int endingAt);

    HashSet<T> GetAllItemsFromSet(IRedisSet<T> fromSet);
    void AddItemToSet(IRedisSet<T> toSet, T item);
    void RemoveItemFromSet(IRedisSet<T> fromSet, T item);
    T PopItemFromSet(IRedisSet<T> fromSet);
    void MoveBetweenSets(IRedisSet<T> fromSet, IRedisSet<T> toSet, T item);
    int GetSetCount(IRedisSet<T> set);
    bool SetContainsItem(IRedisSet<T> set, T item);
    HashSet<T> GetIntersectFromSets(params IRedisSet<T>[] sets);
    void StoreIntersectFromSets(IRedisSet<T> intoSet, params IRedisSet<T>[] sets);
    HashSet<T> GetUnionFromSets(params IRedisSet<T>[] sets);
    void StoreUnionFromSets(IRedisSet<T> intoSet, params IRedisSet<T>[] sets);
    HashSet<T> GetDifferencesFromSet(IRedisSet<T> fromSet, params IRedisSet<T>[] withSets);
    void StoreDifferencesFromSet(IRedisSet<T> intoSet, IRedisSet<T> fromSet, params IRedisSet<T>[] withSets);
    T GetRandomItemFromSet(IRedisSet<T> fromSet);

    List<T> GetAllItemsFromList(IRedisList<T> fromList);
    List<T> GetRangeFromList(IRedisList<T> fromList, int startingFrom, int endingAt);
    List<T> SortList(IRedisList<T> fromList, int startingFrom, int endingAt);
    void AddItemToList(IRedisList<T> fromList, T value);
    void PrependItemToList(IRedisList<T> fromList, T value);
    T RemoveStartFromList(IRedisList<T> fromList);
    T BlockingRemoveStartFromList(IRedisList<T> fromList, TimeSpan? timeOut);
    T RemoveEndFromList(IRedisList<T> fromList);
    void RemoveAllFromList(IRedisList<T> fromList);
    void TrimList(IRedisList<T> fromList, int keepStartingFrom, int keepEndingAt);
    int RemoveItemFromList(IRedisList<T> fromList, T value);
    int RemoveItemFromList(IRedisList<T> fromList, T value, int noOfMatches);
    int GetListCount(IRedisList<T> fromList);
    T GetItemFromList(IRedisList<T> fromList, int listIndex);
    void SetItemInList(IRedisList<T> toList, int listIndex, T value);

    //Queue operations
    void EnqueueItemOnList(IRedisList<T> fromList, T item);
    T DequeueItemFromList(IRedisList<T> fromList);
    T BlockingDequeueItemFromList(IRedisList<T> fromList, TimeSpan? timeOut);

    //Stack operations
    void PushItemToList(IRedisList<T> fromList, T item);
    T PopItemFromList(IRedisList<T> fromList);
    T BlockingPopItemFromList(IRedisList<T> fromList, TimeSpan? timeOut);
    T PopAndPushItemBetweenLists(IRedisList<T> fromList, IRedisList<T> toList);

    void AddItemToSortedSet(IRedisSortedSet<T> toSet, T value);
    void AddItemToSortedSet(IRedisSortedSet<T> toSet, T value, double score);
    bool RemoveItemFromSortedSet(IRedisSortedSet<T> fromSet, T value);
    T PopItemWithLowestScoreFromSortedSet(IRedisSortedSet<T> fromSet);
    T PopItemWithHighestScoreFromSortedSet(IRedisSortedSet<T> fromSet);
    bool SortedSetContainsItem(IRedisSortedSet<T> set, T value);
    double IncrementItemInSortedSet(IRedisSortedSet<T> set, T value, double incrementBy);
    int GetItemIndexInSortedSet(IRedisSortedSet<T> set, T value);
    int GetItemIndexInSortedSetDesc(IRedisSortedSet<T> set, T value);
    List<T> GetAllItemsFromSortedSet(IRedisSortedSet<T> set);
    List<T> GetAllItemsFromSortedSetDesc(IRedisSortedSet<T> set);
    List<T> GetRangeFromSortedSet(IRedisSortedSet<T> set, int fromRank, int toRank);
    List<T> GetRangeFromSortedSetDesc(IRedisSortedSet<T> set, int fromRank, int toRank);
    IDictionary<T, double> GetAllWithScoresFromSortedSet(IRedisSortedSet<T> set);
    IDictionary<T, double> GetRangeWithScoresFromSortedSet(IRedisSortedSet<T> set, int fromRank, int toRank);
    IDictionary<T, double> GetRangeWithScoresFromSortedSetDesc(IRedisSortedSet<T> set, int fromRank, int toRank);
    List<T> GetRangeFromSortedSetByLowestScore(IRedisSortedSet<T> set, string fromStringScore, string toStringScore);
    List<T> GetRangeFromSortedSetByLowestScore(IRedisSortedSet<T> set, string fromStringScore, string toStringScore, int? skip, int? take);
    List<T> GetRangeFromSortedSetByLowestScore(IRedisSortedSet<T> set, double fromScore, double toScore);
    List<T> GetRangeFromSortedSetByLowestScore(IRedisSortedSet<T> set, double fromScore, double toScore, int? skip, int? take);
    IDictionary<T, double> GetRangeWithScoresFromSortedSetByLowestScore(IRedisSortedSet<T> set, string fromStringScore, string toStringScore);
    IDictionary<T, double> GetRangeWithScoresFromSortedSetByLowestScore(IRedisSortedSet<T> set, string fromStringScore, string toStringScore, int? skip, int? take);
    IDictionary<T, double> GetRangeWithScoresFromSortedSetByLowestScore(IRedisSortedSet<T> set, double fromScore, double toScore);
    IDictionary<T, double> GetRangeWithScoresFromSortedSetByLowestScore(IRedisSortedSet<T> set, double fromScore, double toScore, int? skip, int? take);
    List<T> GetRangeFromSortedSetByHighestScore(IRedisSortedSet<T> set, string fromStringScore, string toStringScore);
    List<T> GetRangeFromSortedSetByHighestScore(IRedisSortedSet<T> set, string fromStringScore, string toStringScore, int? skip, int? take);
    List<T> GetRangeFromSortedSetByHighestScore(IRedisSortedSet<T> set, double fromScore, double toScore);
    List<T> GetRangeFromSortedSetByHighestScore(IRedisSortedSet<T> set, double fromScore, double toScore, int? skip, int? take);
    IDictionary<T, double> GetRangeWithScoresFromSortedSetByHighestScore(IRedisSortedSet<T> set, string fromStringScore, string toStringScore);
    IDictionary<T, double> GetRangeWithScoresFromSortedSetByHighestScore(IRedisSortedSet<T> set, string fromStringScore, string toStringScore, int? skip, int? take);
    IDictionary<T, double> GetRangeWithScoresFromSortedSetByHighestScore(IRedisSortedSet<T> set, double fromScore, double toScore);
    IDictionary<T, double> GetRangeWithScoresFromSortedSetByHighestScore(IRedisSortedSet<T> set, double fromScore, double toScore, int? skip, int? take);
    int RemoveRangeFromSortedSet(IRedisSortedSet<T> set, int minRank, int maxRank);
    int RemoveRangeFromSortedSetByScore(IRedisSortedSet<T> set, double fromScore, double toScore);
    int GetSortedSetCount(IRedisSortedSet<T> set);
    double GetItemScoreInSortedSet(IRedisSortedSet<T> set, T value);
    int StoreIntersectFromSortedSets(IRedisSortedSet<T> intoSetId, params IRedisSortedSet<T>[] setIds);
    int StoreUnionFromSortedSets(IRedisSortedSet<T> intoSetId, params IRedisSortedSet<T>[] setIds);

    bool HashContainsEntry<TKey>(IRedisHash<TKey, T> hash, TKey key);
    bool SetEntryInHash<TKey>(IRedisHash<TKey, T> hash, TKey key, T value);
    bool SetEntryInHashIfNotExists<TKey>(IRedisHash<TKey, T> hash, TKey key, T value);
    void SetRangeInHash<TKey>(IRedisHash<TKey, T> hash, IEnumerable<KeyValuePair<TKey, T>> keyValuePairs);
    T GetValueFromHash<TKey>(IRedisHash<TKey, T> hash, TKey key);
    bool RemoveEntryFromHash<TKey>(IRedisHash<TKey, T> hash, TKey key);
    int GetHashCount<TKey>(IRedisHash<TKey, T> hash);
    List<TKey> GetHashKeys<TKey>(IRedisHash<TKey, T> hash);
    List<T> GetHashValues<TKey>(IRedisHash<TKey, T> hash);
    Dictionary<TKey, T> GetAllEntriesFromHash<TKey>(IRedisHash<TKey, T> hash);
}
```


## Common data access interface

Including the above methods, the Generic client also implements Redis non-specific
common data access operations that can be easily implemented by other data persistence providers should you want to swap providers in future.

```csharp
public interface IBasicPersistenceProvider<T>
    : IDisposable
{
    T GetById(string id);

    IList<T> GetByIds(ICollection<string> ids);

    IList<T> GetAll();

    T Store(T entity);

    void StoreAll(IEnumerable<T> entities);

    void Delete(T entity);

    void DeleteById(string id);

    void DeleteByIds(ICollection<string> ids);

    void DeleteAll();
}
```

Generally, if you only have basic persistence needs I would recommend developing against the above common data access API as it is easier for other
persistence providers to implement and increases the likely hood that your library can be reused as-is to persist against other data stores i.e. against an RDBMS with OrmLite, etc.


# Redis Transactions
Source: https://docs.servicestack.net/redis/transactions

This page provides examples on how to create atomic Redis transactions with [ServiceStackRedis Service Stack's C# Redis Client](https://github.com/ServiceStack/ServiceStack.Redis)

## How to create custom atomic operations in Redis

One of the main features of Redis is the ability to construct custom atomic operations. This is achieved by utilizing Redis's
[MULTI/EXEC/DISCARD](https://redis.io/commands/multi) operations.

[ServiceStack's C# Redis Client](https://github.com/ServiceStack/ServiceStack.Redis) makes it easy to utilize Redis transactions by providing a strongly-typed [IRedisTransaction](./transactions.md)
(for strings) and [IRedisTypedTransaction&lt;T&gt;](./typed-transactions.md) (for POCO types) APIs with convenience methods to allow you to combine any [IRedisClient](./client.md) operation within a single transaction.

Creating a transaction is done by calling `IRedisClient.CreateTransaction()`.
From there you 'Queue' up all operations you want to be a part of the transaction by using one of the `IRedisTransaction.QueueCommand()` overloads. After that you can execute all the operations by calling `IRedisTransaction.Commit()` which will send the 'EXEC' command to the Redis server executing all the Queued commands and processing their callbacks.

If you don't call the `Commit()` before the end of the using block, `Dispose()` method will automatically invokes `Rollback()` that will send the 'DISCARD' command disposing of the current transaction and resetting the Redis client connection back to its previous state.

## Redis Transaction Examples

Below is a simple example showing how to queue up Redis operations with and without a callback.

```csharp
int callbackResult;
using (var trans = redis.CreateTransaction())
{
  trans.QueueCommand(r => r.Increment("key"));  
  trans.QueueCommand(r => r.Increment("key"), i => callbackResult = i);  

  trans.Commit();
}
//The value of "key" is incremented twice. The latest value of which is also stored in 'callbackResult'.

```

## Other common examples
The full-source code and other common examples can be found on the
[common transaction tests page](https://github.com/ServiceStack/ServiceStack.Redis/blob/master/tests/ServiceStack.Redis.Tests/RedisTransactionCommonTests.cs).

```csharp
[Test]
public void Can_Set_and_Expire_key_in_atomic_transaction()
{
    var oneSec = TimeSpan.FromSeconds(1);

    Assert.That(Redis.GetString("key"), Is.Null);
    using (var trans = Redis.CreateTransaction())                  //Calls 'MULTI'
    {
        trans.QueueCommand(r => r.SetString("key", "a"));      //Queues 'SET key a'
        trans.QueueCommand(r => r.ExpireKeyIn("key", oneSec)); //Queues 'EXPIRE key 1'

        trans.Commit();                                        //Calls 'EXEC'

    }                                                              //Calls 'DISCARD' if 'EXEC' wasn't called

    Assert.That(Redis.GetString("key"), Is.EqualTo("a"));
    Thread.Sleep(TimeSpan.FromSeconds(2));
    Assert.That(Redis.GetString("key"), Is.Null);
}

[Test]
public void Can_Pop_priority_message_from_SortedSet_and_Add_to_workq_in_atomic_transaction()
{
    var messages = new List<string> { "message4", "message3", "message2" };

    Redis.AddToList("workq", "message1");

    var priority = 1;
    messages.ForEach(x => Redis.AddToSortedSet("prioritymsgs", x, priority++));

    var highestPriorityMessage = Redis.PopFromSortedSetItemWithHighestScore("prioritymsgs");

    using (var trans = Redis.CreateTransaction())
    {
        trans.QueueCommand(r => r.RemoveFromSortedSet("prioritymsgs", highestPriorityMessage));
        trans.QueueCommand(r => r.AddToList("workq", highestPriorityMessage));	

        trans.Commit();											
    }

    Assert.That(Redis.GetAllFromList("workq"), 
        Is.EquivalentTo(new List<string> { "message1", "message2" }));
    Assert.That(Redis.GetAllFromSortedSet("prioritymsgs"), 
        Is.EquivalentTo(new List<string> { "message3", "message4" }));
}
```

## All-in-one example
This and other examples can be found by looking at the
[RedisTransactionTests.cs test suite](https://github.com/ServiceStack/ServiceStack.Redis/blob/master/tests/ServiceStack.Redis.Tests/RedisTransactionTests.cs).

Here is an all-in-one examples combining different Redis operations within a single transaction:

```csharp
[Test]
public void Supports_different_operation_types_in_same_transaction()
{
    var incrementResults = new List<int>();
    var collectionCounts = new List<int>();
    var containsItem = false;

    Assert.That(Redis.GetString(Key), Is.Null);
    using (var trans = Redis.CreateTransaction())
    {
        trans.QueueCommand(r => r.Increment(Key), intResult => incrementResults.Add(intResult));
        trans.QueueCommand(r => r.AddToList(ListKey, "listitem1"));
        trans.QueueCommand(r => r.AddToList(ListKey, "listitem2"));
        trans.QueueCommand(r => r.AddToSet(SetKey, "setitem"));
        trans.QueueCommand(r => r.SetContainsValue(SetKey, "setitem"), b => containsItem = b);
        trans.QueueCommand(r => r.AddToSortedSet(SortedSetKey, "sortedsetitem1"));
        trans.QueueCommand(r => r.AddToSortedSet(SortedSetKey, "sortedsetitem2"));
        trans.QueueCommand(r => r.AddToSortedSet(SortedSetKey, "sortedsetitem3"));
        trans.QueueCommand(r => r.GetListCount(ListKey), intResult => collectionCounts.Add(intResult));
        trans.QueueCommand(r => r.GetSetCount(SetKey), intResult => collectionCounts.Add(intResult));
        trans.QueueCommand(r => r.GetSortedSetCount(SortedSetKey), intResult => collectionCounts.Add(intResult));
        trans.QueueCommand(r => r.Increment(Key), intResult => incrementResults.Add(intResult));

        trans.Commit();
    }

    Assert.That(containsItem, Is.True);
    Assert.That(Redis.GetString(Key), Is.EqualTo("2"));
    Assert.That(incrementResults, Is.EquivalentTo(new List<int> { 1, 2 }));
    Assert.That(collectionCounts, Is.EquivalentTo(new List<int> { 2, 1, 3 }));
    Assert.That(Redis.GetAllFromList(ListKey), Is.EquivalentTo(new List<string> { "listitem1", "listitem2" }));
    Assert.That(Redis.GetAllFromSet(SetKey), Is.EquivalentTo(new List<string> { "setitem" }));
    Assert.That(Redis.GetAllFromSortedSet(SortedSetKey), Is.EquivalentTo(new List<string> { "sortedsetitem1", "sortedsetitem2", "sortedsetitem3" }));
}
```


# Redis Typed Transactions
Source: https://docs.servicestack.net/redis/typed-transactions

The [Redis Transactions](./transactions.md) interface implemented by [ServiceStack's C# Redis Client](https://github.com/ServiceStack/ServiceStack.Redis).

## Introduction

Redis transaction interface provides useful overloads that let you Queue-up any [IRedisTypedClient](./typed-client.md) operation within a single transaction.
The API provides support for a callback so you also have access to any return values returned as part of the transaction as well.

## Usage

Below is a simple example showing how to access, use and commit the transaction.

```csharp
var typedClient = Redis.GetTypedClient<MyPocoType>();			
using (var trans = typedClient.CreateTransaction())
{
    trans.QueueCommand(r => r.Set("nosqldbs", new MyPocoType {Id = 1, Name = "Redis"));

    trans.Commit();
}
```

For a transaction that operates on string values see [IRedisTransaction](./transactions.md).

## Details

```csharp
public interface IRedisTypedTransaction<T> 
    : IDisposable
{
    void QueueCommand(Action<IRedisTypedClient<T>> command);
    void QueueCommand(Action<IRedisTypedClient<T>> command, Action onSuccessCallback);
    void QueueCommand(Action<IRedisTypedClient<T>> command, Action onSuccessCallback, Action<Exception> onErrorCallback);

    void QueueCommand(Func<IRedisTypedClient<T>, int> command);
    void QueueCommand(Func<IRedisTypedClient<T>, int> command, Action<int> onSuccessCallback);
    void QueueCommand(Func<IRedisTypedClient<T>, int> command, Action<int> onSuccessCallback, Action<Exception> onErrorCallback);

    void QueueCommand(Func<IRedisTypedClient<T>, bool> command);
    void QueueCommand(Func<IRedisTypedClient<T>, bool> command, Action<bool> onSuccessCallback);
    void QueueCommand(Func<IRedisTypedClient<T>, bool> command, Action<bool> onSuccessCallback, Action<Exception> onErrorCallback);

    void QueueCommand(Func<IRedisTypedClient<T>, double> command);
    void QueueCommand(Func<IRedisTypedClient<T>, double> command, Action<double> onSuccessCallback);
    void QueueCommand(Func<IRedisTypedClient<T>, double> command, Action<double> onSuccessCallback, Action<Exception> onErrorCallback);

    void QueueCommand(Func<IRedisTypedClient<T>, byte[]> command);
    void QueueCommand(Func<IRedisTypedClient<T>, byte[]> command, Action<byte[]> onSuccessCallback);
    void QueueCommand(Func<IRedisTypedClient<T>, byte[]> command, Action<byte[]> onSuccessCallback, Action<Exception> onErrorCallback);

    void QueueCommand(Func<IRedisTypedClient<T>, string> command);
    void QueueCommand(Func<IRedisTypedClient<T>, string> command, Action<string> onSuccessCallback);
    void QueueCommand(Func<IRedisTypedClient<T>, string> command, Action<string> onSuccessCallback, Action<Exception> onErrorCallback);

    void QueueCommand(Func<IRedisTypedClient<T>, T> command);
    void QueueCommand(Func<IRedisTypedClient<T>, T> command, Action<T> onSuccessCallback);
    void QueueCommand(Func<IRedisTypedClient<T>, T> command, Action<T> onSuccessCallback, Action<Exception> onErrorCallback);

    void QueueCommand(Func<IRedisTypedClient<T>, List<string>> command);
    void QueueCommand(Func<IRedisTypedClient<T>, List<string>> command, Action<List<string>> onSuccessCallback);
    void QueueCommand(Func<IRedisTypedClient<T>, List<string>> command, Action<List<string>> onSuccessCallback, Action<Exception> onErrorCallback);

    void QueueCommand(Func<IRedisTypedClient<T>, List<T>> command);
    void QueueCommand(Func<IRedisTypedClient<T>, List<T>> command, Action<List<T>> onSuccessCallback);
    void QueueCommand(Func<IRedisTypedClient<T>, List<T>> command, Action<List<T>> onSuccessCallback, Action<Exception> onErrorCallback);

    void Commit();
    void Rollback();
}
```


# Redis Stats
Source: https://docs.servicestack.net/redis/stats

The [RedisStats](https://github.com/ServiceStack/ServiceStack.Redis/blob/master/src/ServiceStack.Redis/RedisStats.cs)
class provides better visibility and introspection into your running instances:

<table>
    <tr>
        <td><b>TotalCommandsSent</b></td> <td>Total number of commands sent</td>
    </tr>
    <tr>
        <td><b>TotalFailovers</b></td> <td>Number of times the Redis Client Managers have FailoverTo() either by sentinel or manually</td>
    </tr>
    <tr>
        <td><b>TotalDeactivatedClients</b></td> <td>Number of times a Client was deactivated from the pool, either by FailoverTo() or exceptions on client</td>
    </tr>
    <tr>
        <td><b>TotalFailedSentinelWorkers</b></td> <td>Number of times connecting to a Sentinel has failed</td>
    </tr>
    <tr>
        <td><b>TotalForcedMasterFailovers</b></td> <td>Number of times we've forced Sentinel to failover to another master due to consecutive errors</td>
    </tr>
    <tr>
        <td><b>TotalInvalidMasters</b></td> <td>Number of times a connecting to a reported Master wasn't actually a Master</td>
    </tr>
    <tr>
        <td><b>TotalNoMastersFound</b></td> <td>Number of times no Masters could be found in any of the configured hosts</td>
    </tr>
    <tr>
        <td><b>TotalClientsCreated</b></td> <td>Number of Redis Client instances created with RedisConfig.ClientFactory</td>
    </tr>
    <tr>
        <td><b>TotalClientsCreatedOutsidePool</b></td> <td>Number of times a Redis Client was created outside of pool, either due to overflow or reserved slot was overridden</td>
    </tr>
    <tr>
        <td><b>TotalSubjectiveServersDown</b></td> <td>Number of times Redis Sentinel reported a Subjective Down (sdown)</td>
    </tr>
    <tr>
        <td><b>TotalObjectiveServersDown</b></td> <td>Number of times Redis Sentinel reported an Objective Down (odown)</td>
    </tr>
    <tr>
        <td><b>TotalRetryCount</b></td> <td>Number of times a Redis Request was retried due to Socket or Retryable exception</td>
    </tr>
    <tr>
        <td><b>TotalRetrySuccess</b></td> <td>Number of times a Request succeeded after it was retried</td>
    </tr>
    <tr>
        <td><b>TotalRetryTimedout</b></td> <td>Number of times a Retry Request failed after exceeding RetryTimeout</td>
    </tr>
    <tr>
        <td><b>TotalPendingDeactivatedClients</b></td> <td>Total number of deactivated clients that are pending being disposed</td>
    </tr>
</table>

## Redis Stats in Admin UI Dashboard

These Stats are displayed in the [Admin UI Dashboard](/admin-ui-redis#redis-stats-on-dashboard)

[![](/img/pages/admin-ui/admin-ui-redis-stats.png)](/admin-ui-redis#redis-stats-on-dashboard)

## Log to Console

Alternatively you can get and print a dump of all the stats at anytime with:

```csharp
RedisStats.ToDictionary().PrintDump();
```

And Reset all Stats back to `0` with `RedisStats.Reset()`.


# Redis Profiling
Source: https://docs.servicestack.net/redis/profiling

## Redis Profiler

The easiest way to view your App's executed Redis commands is by enabling the [Admin Profiling UI](/admin-ui-features#request-logging-profiling) where it's built-in [Redis Profiling](/admin-ui-profiling#redis-profiling) will show generated queries in context with your other App events:

<a href="/admin-ui-profiling#redis-profiling" class="block flex justify-center items-center">
    <img class="max-w-screen-md" src="/img/pages/admin-ui/profiling-redis-CommandAfter.png">
</a>

## Logging Executed Redis Commands

Alternatively you can see what commands Redis Client executes by configuring it to log verbose debug info with:

```csharp
RedisConfig.EnableVerboseLogging = true;
LogManager.LogFactory = new ConsoleLogFactory(debugEnabled:true);
```

Where it will log verbose commands Redis clients executes to the Console.


# Redis Admin Desktop App
Source: https://docs.servicestack.net/redis/redis-desktop

::include redis-admin.md::


# Automatic Retries
Source: https://docs.servicestack.net/redis/automatic-retries

One feature that improves the resilience of `RedisClient` connections is Auto Retry where the RedisClient will transparently retry failed Redis operations due to Socket and I/O Exceptions in an exponential backoff starting from
**10ms** up until the `RetryTimeout` of **10000ms**. These defaults can be tweaked with:

## Usage

```csharp
RedisConfig.DefaultRetryTimeout = 10000;
RedisConfig.BackOffMultiplier = 10;
```

The `RetryTimeout` can also be configured on the connection string with `?RetryTimeout=10000`.


# Design a Blog with Redis
Source: https://docs.servicestack.net/redis/design-nosql

This page illustrates a good solution on how to design a simple Blog application with [Redis](http://redis.io) using advanced features of
[ServiceStack's C# Redis Client](https://github.com/ServiceStack/ServiceStack.Redis) to provide fast, simple and elegant solutions to real world scenarios.

#### All Redis Blog application pages
* Designing a NoSQL Database using Redis
* [Painless data migrations using Redis and other schema-less NoSQL datastores](./schemaless-migration.md)

## Designing a NoSQL Database using Redis

Oren Eini from the popular .NET blog http://ayende.com/Blog/, is putting together a
[series of blog posts](http://ayende.com/Blog/archive/2010/04/20/that-no-sql-thing-the-relational-modeling-anti-pattern-in.aspx) explaining how to go about designing a
simple blog application using a NoSQL database. Although he's using his RavenDB as a reference implementation, this example applies equally well to Redis and other
NoSQL variants. Some solutions will vary based on the advanced features of each NoSQL solution but the 'core data models' should remain the same.

I will try to add my own thoughts on and where possible show how you can use the advanced features in Redis the C# Client to provide simple, fast and effective solutions.
The entire source code for this example is available in its simplest form at:
[BlogPostExample.cs](https://github.com/ServiceStack/ServiceStack.Redis/blob/master/tests/ServiceStack.Redis.Tests/Examples/BlogPostExample.cs).
I will be re-factoring this solution in what I consider a 'best practices approach' for large applications where I will shove all Redis access behind a repository
(so the client doesn't know it's even being used) which I will be maintaining at:
[BlogPostBestPractice.cs](https://github.com/ServiceStack/ServiceStack.Redis/blob/master/tests/ServiceStack.Redis.Tests/Examples/BestPractice/BlogPostBestPractice.cs)

## Modeling Entities in a NoSQL Database

If you've spent a lot of time building solutions with an RDBMS back-end it can be hard to know which part of your schema is due to the problem domain and which part is the result of an implementation constraint trying to map your ideal domain model onto a relational tabular structure.

My approach before designing any system is to map out the ideal domain model we need to build in order before I reach for an IDE or a db gui schema creator. Unfortunately creating POCO types is just so damn quick in VS.NET/C#/R# that I've ditched the pencil and paper a long time ago and jump right into using C# automatic properties like a kind of light-weight DSL ripping out entities quicker than I can draw crows feet :)

If you are like me and prefer to design your domain models from POCO types rather than creating RDBMS tables than you're in good shape in implementing a NoSQL solution as the time when you usually morph your pristine domain models into a tabular structure peppering it with Primary and Foreign keys can now saved and put towards a longer lunch break as most of the times you can skip this step entirely.

The schema-less nature of NoSQL databases means you can pretty much store your domain models as-is. You will still need to identify your distinct entities from your Key Value Objects. A good guide I use to help with this is whether the Model only makes sense in the context its parent and whether it is 'co-owned' or referenced by another entity. This is where we start pulling the domain model apart, basically you just replace the collection of strongly-typed entities to a collection of entity ids. Effectively you can think of this like foreign-keys but at a much higher level as you only pull it apart of the domain model when you want to manage the entities independently of each other, not as dictated by your schema.

Taking the User model in it's most simplest form. A User has many blogs, now as you may want to view a list of blogs outside the context of a User (e.g. view a list of newly created blogs, most popular blogs for a category, etc). It becomes a good candidate to being promoted a first class entity.

```csharp
//Before
public class User
{
    public int Id { get; set; }
    public string Name { get; set; }
    public List<Blog> Blogs { get; set; }
}

//After
public class User
{
    public int Id { get; set; }
    public string Name { get; set; }
    public List<int> BlogIds { get; set; }
}
```

With only a running redis-server instance running and the C# client, the full source to persist and retrieve a list of users is only:

```csharp
var redis = new RedisClient();
var redisUsers = redis.As<User>();
redisUsers.Store(new User { Id = redisUsers.GetNextSequence(), Name = "ayende" });
redisUsers.Store(new User { Id = redisUsers.GetNextSequence(), Name = "mythz" });

var allUsers = redisUsers.GetAll();

//Recursively print the values of the POCO
allUsers.PrintDump();
/*Output
[
    {
        Id: 1,
        Name: ayende,
        BlogIds: []
    },
    {
        Id: 2,
        Name: mythz,
        BlogIds: []
    }
]
    */
```

_Note: [You can also use the generic T.Dump() Extension method yourself](http://www.servicestack.net/mythz_blog/?p=202)._

Ayende has outlined a few scenarios that the Blog application should support.

* Main page: show list of blogs
* Main page: show list of recent posts
* Main page: show list of recent comments
* Main page: show tag cloud for posts
* Main page: show categories
* Post page: show post and all comments
* Post page: add comment to post
* Tag page: show all posts for tag
* Categories page: show all posts for category

The full source code for the Redis solution for each of these scenarios is [available here](https://github.com/ServiceStack/ServiceStack.Redis/blob/master/tests/ServiceStack.Redis.Tests/Examples/BlogPostExample.cs). Although I will go through each solution in a little more detail below.

### Main page: show list of blogs
Before we can show a list of blogs, we need to add some first.
Here I make effective use of the Redis client's unique sequence that is maintained for each type.

In identifying my entities I have a general preference for 'automated ids' which are either
sequential integer ids or Guids - if the entities are going to be distributed across multiple data stores.

Apart from that persisting an object is just a straight forward process of serializing the object graph into a text-serialization format.
By default, the Redis Client uses [Service Stack's JsonSerializer](https://github.com/ServiceStack/ServiceStack/tree/main/ServiceStack.Text/src/ServiceStack.Text) as it's the fastest and JSON Serializer for .NET.

```csharp
//Retrieve strongly-typed Redis clients that let's you natively persist POCO's
var redisUsers = redis.As<User>();
var redisBlogs = redis.As<Blog>();
//Create the user, getting a unique User Id from the User sequence.
var mythz = new User { Id = redisUsers.GetNextSequence(), Name = "Demis Bellot" };

//create some blogs using unique Ids from the Blog sequence. Also adding references
var mythzBlogs = new List<Blog>
{
    new Blog
    {
        Id = redisBlogs.GetNextSequence(),
        UserId = mythz.Id,
        UserName = mythz.Name,
        Tags = new List<string> { "Architecture", ".NET", "Redis" },
    },
    new Blog
    {
        Id = redisBlogs.GetNextSequence(),
        UserId = mythz.Id,
        UserName = mythz.Name,
        Tags = new List<string> { "Music", "Twitter", "Life" },
    },
};
//Add the blog references
mythzBlogs.ForEach(x => mythz.BlogIds.Add(x.Id));

//Store the user and their blogs
redisUsers.Store(mythz);
redisBlogs.StoreAll(mythzBlogs);

//retrieve all blogs
var blogs = redisBlogs.GetAll();

blogs.PrintDump();
/*Output
[
    {
        Id: 1,
        UserId: 1,
        UserName: Demis Bellot,
        Tags: 
        [
            Architecture,
            .NET,
            Redis
        ],
        BlogPostIds: []
    },
    {
        Id: 2,
        UserId: 1,
        UserName: Demis Bellot,
        Tags: 
        [
            Music,
            Twitter,
            Life
        ],
        BlogPostIds: []
    }
]
*/
```

### Main page: show list of recent comments

For this scenario we can take advantage of Redis's LTRIM'ing operation to maintain custom rolling lists.
The richness of [Redis list operations](http://redis.io/commands/rpush) also allow us to prepend or append at either end of the list which we take advantage of in this example.


```csharp
//Get strongly-typed clients
var redisBlogPosts = redis.As<BlogPost>();
var redisComments = redis.As<BlogPostComment>();
//To keep this example let's pretend this is a new list of blog posts
var newIncomingBlogPosts = redisBlogPosts.GetAll();

//Let's get back an IList<BlogPost> wrapper around a Redis server-side List.
var recentPosts = redisBlogPosts.Lists["urn:BlogPost:RecentPosts"];
var recentComments = redisComments.Lists["urn:BlogPostComment:RecentComments"];

foreach (var newBlogPost in newIncomingBlogPosts)
{
    //Prepend the new blog posts to the start of the 'RecentPosts' list
    recentPosts.Prepend(newBlogPost);

    //Prepend all the new blog post comments to the start of the 'RecentComments' list
    newBlogPost.Comments.ForEach(recentComments.Prepend);
}

//Make this a Rolling list by only keep the latest 3 posts and comments
recentPosts.Trim(0, 2);
recentComments.Trim(0, 2);

//Print out the last 3 posts:
recentPosts.GetAll().PrintDump();
/* Output: 
[
    {
        Id: 2,
        BlogId: 2,
        Title: Redis,
        Categories: 
        [
            NoSQL,
            Cache
        ],
        Tags: 
        [
            Redis,
            NoSQL,
            Scalability,
            Performance
        ],
        Comments: 
        [
            {
                Content: First Comment!,
                CreatedDate: 2010-04-20T22:14:02.755878Z
            }
        ]
    },
    {
        Id: 1,
        BlogId: 1,
        Title: RavenDB,
        Categories: 
        [
            NoSQL,
            DocumentDB
        ],
        Tags: 
        [
            Raven,
            NoSQL,
            JSON,
            .NET
        ],
        Comments: 
        [
            {
                Content: First Comment!,
                CreatedDate: 2010-04-20T22:14:02.755878Z
            },
            {
                Content: Second Comment!,
                CreatedDate: 2010-04-20T22:14:02.755878Z
            }
        ]
    },
    {
        Id: 4,
        BlogId: 2,
        Title: Couch Db,
        Categories: 
        [
            NoSQL,
            DocumentDB
        ],
        Tags: 
        [
            CouchDb,
            NoSQL,
            JSON
        ],
        Comments: 
        [
            {
                Content: First Comment!,
                CreatedDate: 2010-04-20T22:14:02.755878Z
            }
        ]
    }
]
*/

recentComments.GetAll().PrintDump();
/* Output:
[
    {
        Content: First Comment!,
        CreatedDate: 2010-04-20T20:32:42.2970956Z
    },
    {
        Content: First Comment!,
        CreatedDate: 2010-04-20T20:32:42.2970956Z
    },
    {
        Content: First Comment!,
        CreatedDate: 2010-04-20T20:32:42.2970956Z
    }
]
*/
```


### Main page: show tag cloud for posts

Redis Sorted Sets provide the perfect data structure to maintain a Tag cloud of all tags.
It's very fast, elegant structure which provides custom-specific operations to maintain and sort the data.


```csharp
//Get strongly-typed clients
var redisBlogPosts = redis.As<BlogPost>();
var newIncomingBlogPosts = redisBlogPosts.GetAll();

foreach (var newBlogPost in newIncomingBlogPosts)
{
    //For every tag in each new blog post, increment the number of times each Tag has occurred 
    newBlogPost.Tags.ForEach(x =>
        redis.IncrementItemInSortedSet("urn:TagCloud", x, 1));
}

//Show top 5 most popular tags with their scores
var tagCloud = redis.GetRangeWithScoresFromSortedSetDesc("urn:TagCloud", 0, 4);
tagCloud.PrintDump();
/* Output:
[
    [
        NoSQL,
            4
    ],
    [
        Scalability,
            2
    ],
    [
        JSON,
            2
    ],
    [
        Redis,
            1
    ],
    [
        Raven,
            1
    ],
]
*/
```

### Main page: show categories

To keep a unique list of categories the right structure to use is a Set.
This allows you to freely add a value multiple times and there will never be any
duplicates as only one of each value is stored.


```csharp
var redisBlogPosts = redis.As<BlogPost>();
var blogPosts = redisBlogPosts.GetAll();

foreach (var blogPost in blogPosts)
{
    blogPost.Categories.ForEach(x =>
            redis.AddToSet("urn:Categories", x));
}

var uniqueCategories = redis.GetAllFromSet("urn:Categories");
uniqueCategories.PrintDump();
/* Output:
[
    DocumentDB,
    NoSQL,
    Cluster,
    Cache
]
*/
```


### Post page: show post and all comments

There is nothing special to do here since comments are Key Value Objects they are
stored and retrieved with the post, so retrieving the post retrieves it's comments as well.

```csharp
var postId = 1;
var redisBlogPosts = redis.As<BlogPost>();
var selectedBlogPost = redisBlogPosts.GetById(postId.ToString());

selectedBlogPost.PrintDump();
/* Output:
{
    Id: 1,
    BlogId: 1,
    Title: RavenDB,
    Categories: 
    [
        NoSQL,
        DocumentDB
    ],
    Tags: 
    [
        Raven,
        NoSQL,
        JSON,
        .NET
    ],
    Comments: 
    [
        {
            Content: First Comment!,
            CreatedDate: 2010-04-20T21:26:31.9918236Z
        },
        {
            Content: Second Comment!,
            CreatedDate: 2010-04-20T21:26:31.9918236Z
        }
    ]
}
*/
```


### Post page: add comment to post

Modifying an entity are one of the strengths of a schema-less data store.
Adding a comment is as simple as
* retrieving it's parent post
* modifying the POCO entity in memory by adding a comment to the existing list
* then saving the entity.

```csharp
var postId = 1;
var redisBlogPosts = redis.As<BlogPost>();
var blogPost = redisBlogPosts.GetById(postId.ToString());
blogPost.Comments.Add(
    new BlogPostComment { Content = "Third Post!", CreatedDate = DateTime.UtcNow });
redisBlogPosts.Store(blogPost);

var refreshBlogPost = redisBlogPosts.GetById(postId.ToString());
refreshBlogPost.PrintDump();
/* Output:
{
    Id: 1,
    BlogId: 1,
    Title: RavenDB,
    Categories: 
    [
        NoSQL,
        DocumentDB
    ],
    Tags: 
    [
        Raven,
        NoSQL,
        JSON,
        .NET
    ],
    Comments: 
    [
        {
            Content: First Comment!,
            CreatedDate: 2010-04-20T21:32:39.9688707Z
        },
        {
            Content: Second Comment!,
            CreatedDate: 2010-04-20T21:32:39.9688707Z
        },
        {
            Content: Third Post!,
            CreatedDate: 2010-04-20T21:32:40.2688879Z
        }
    ]
}
*/
```


### Tag page: show all posts for tag

Basically in order to view all the posts for a particular category we'll need to provide
a reverse-index by adding all matching post ids into a 'Category > Post Id' Set.

From there it's just a matter of performing a batch request fetching all the Posts with the supplied Ids:


```csharp
var redisBlogPosts = redis.As<BlogPost>();
var newIncomingBlogPosts = redisBlogPosts.GetAll();

foreach (var newBlogPost in newIncomingBlogPosts)
{
    //For each post add it's Id into each of it's 'Cateogry > Posts' index
    newBlogPost.Categories.ForEach(x =>
            redis.AddToSet("urn:Category:" + x, newBlogPost.Id.ToString()));
}

//Retrieve all the post ids for the category you want to view
var documentDbPostIds = redis.GetAllFromSet("urn:Category:DocumentDB");

//Make a batch call to retrieve all the posts containing the matching ids 
//(i.e. the DocumentDB Category posts)
var documentDbPosts = redisBlogPosts.GetByIds(documentDbPostIds);

documentDbPosts.PrintDump();
/* Output:
[
    {
        Id: 4,
        BlogId: 2,
        Title: Couch Db,
        Categories: 
        [
            NoSQL,
            DocumentDB
        ],
        Tags: 
        [
            CouchDb,
            NoSQL,
            JSON
        ],
        Comments: 
        [
            {
                Content: First Comment!,
                CreatedDate: 2010-04-20T21:38:24.6305842Z
            }
        ]
    },
    {
        Id: 1,
        BlogId: 1,
        Title: RavenDB,
        Categories: 
        [
            NoSQL,
            DocumentDB
        ],
        Tags: 
        [
            Raven,
            NoSQL,
            JSON,
            .NET
        ],
        Comments: 
        [
            {
                Content: First Comment!,
                CreatedDate: 2010-04-20T21:38:24.6295842Z
            },
            {
                Content: Second Comment!,
                CreatedDate: 2010-04-20T21:38:24.6295842Z
            }
        ]
    }
]
*/
```


# Data migrations with Redis
Source: https://docs.servicestack.net/redis/schemaless-migration

This page runs through a typical example to show how painless typical data migrations can be when using Redis and other NoSQL schema-less data stores.

#### All Redis Blog application pages
* [Designing a NoSQL Database using Redis](./design-nosql.md)
* Painless data migrations using Redis and other schema-less NoSQL datastores

## Painless data migrations with schema-less NoSQL datastores and Redis

Developing *new* greenfield database systems utilizing a RDBMS back-end is mostly a trouble-free experience. Before the system is live, you're able to easily modify a schema by nuking the entire application database, and re-creating it with automated DDL scripts that will create and populate it with test data that fits your new schema.

The real troubles in your IT life happens after your first deployment and your system goes live. At that point you no longer have the option to nuke the database and re-create it from scratch. If you're lucky, you have a script in place that can automatically infer the required DDL statements to migrate from your old schema to your new one. However any significant changes to your schema are likely to involve late nights, downtime, and a non-trivial amount of effort to ensure a successful migration to the new db schema.

This process is much less painful with schema-less data stores. In fact in most cases when you're just adding and removing fields it doesn't exist at all. By not having your datastore understand intrinsic details of your schema, it means it's no longer an infrastructure-level issue and can easily be handled by application logic if needed.

Being maintenance-free, schema-less and non-intrusive are fundamental design qualities baked into Redis and its operations. For example querying a list of recent BlogPosts returns the same result for an *empty list* as it would in an *empty Redis database* - 0 results. As values in Redis are binary-safe strings you're able to store anything you want in them and most importantly by extension this means that all Redis operations can support all of your application types without needing an 'intermediate language' like DDL to provide a rigid schema of what to expect. Without any prior initialization your code can talk directly to a Redis datastore naturally as if it was an in-memory collection.

To illustrate what can be achieved in practice, I will run through two different strategies of handling schema changes.

* The do-nothing approach - where adding, removing fields and non-destructive change of field types are automatically handled.
* Using a custom translation - using application level logic to customize the translation between the old and new types.

The full runnable source code for this example are [available here](https://github.com/ServiceStack/ServiceStack.Redis/blob/master/tests/ServiceStack.Redis.Tests/Examples/BestPractice/BlogPostMigrations.cs).

## Example Code
To demonstrate a typical migration scenario, I'm using the `BlogPost` type defined on the previous page to project it to a fundamentally different `New.BlogPost` type. The full definition of the old and new types are shown below:

### The old schema

```csharp
public class BlogPost
{
    public BlogPost()
    {
        this.Categories = new List<string>();
        this.Tags = new List<string>();
        this.Comments = new List<BlogPostComment>();
    }

    public int Id { get; set; }
    public int BlogId { get; set; }
    public string Title { get; set; }
    public string Content { get; set; }
    public List<string> Categories { get; set; }
    public List<string> Tags { get; set; }
    public List<BlogPostComment> Comments { get; set; }
}

public class BlogPostComment
{
    public string Content { get; set; }
    public DateTime CreatedDate { get; set; }
}
```

### The new schema
The 'new version' contains most changes you are likely to encounter in normal app development:
* Added, removed and renamed fields
* Non-destructive change of `int` into `long` and `double` fields
* Changed Tag collection type from a `List` to a `HashSet`
* Changed a strongly-typed `BlogPostComment` type into a loosely-typed string `Dictionary`
* Introduced a new `enum` type
* Added a nullable calculated field

### New schema types

```csharp
public class BlogPost
{
    public BlogPost()
    {
        this.Labels = new List<string>();
        this.Tags = new HashSet<string>();
        this.Comments = new List<Dictionary<string, string>>();
    }

    //Changed int types to both a long and a double type
    public long Id { get; set; }
    public double BlogId { get; set; }

    //Added new field
    public BlogPostType PostType { get; set; }

    public string Title { get; set; }
    public string Content { get; set; }

    //Renamed from 'Categories' to 'Labels'
    public List<string> Labels { get; set; }

    //Changed from List to a HashSet
    public HashSet<string> Tags { get; set; }

    //Changed from List of strongly-typed 'BlogPostComment' to loosely-typed string map
    public List<Dictionary<string, string>> Comments { get; set; }

    //Added pointless calculated field
    public int? NoOfComments { get; set; }
}

public enum BlogPostType
{
    None,
    Article,
    Summary,
}
```


### 1. The do-nothing approach - using the old data with the new types
Although hard to believe, with no extra effort you can just pretend *no change was actually done* and freely access new types looking at old data.
This is possible when there is non-destructive changes (i.e. no loss of information) with new field types.
The example below uses the repository from the previous example to populate Redis with test data from the old types. Just as if nothing happened you can read the old data using the new type:


```csharp
var repository = new BlogRepository(redisClient);

//Populate the datastore with the old schema from the 'BlogPostBestPractice'
BlogPostBestPractice.InsertTestData(repository);

//Create a typed-client based on the new schema
using (var redisBlogPosts = redisClient.GetTypedClient<New.BlogPost>())
{
    //Automatically retrieve blog posts
    IList<New.BlogPost> allBlogPosts = redisBlogPosts.GetAll();

    //Print out the data in the list of 'New.BlogPost' populated from old 'BlogPost' type
    Console.WriteLine(allBlogPosts.Dump());
    /*Output:
    [
        {
            Id: 3,
            BlogId: 2,
            PostType: None,
            Title: Redis,
            Labels: [],
            Tags: 
            [
                Redis,
                NoSQL,
                Scalability,
                Performance
            ],
            Comments: 
            [
                {
                    Content: First Comment!,
                    CreatedDate: 2010-04-28T21:42:03.9484725Z
                }
            ]
        },
        {
            Id: 4,
            BlogId: 2,
            PostType: None,
            Title: Couch Db,
            Labels: [],
            Tags: 
            [
                CouchDb,
                NoSQL,
                JSON
            ],
            Comments: 
            [
                {
                    Content: First Comment!,
                    CreatedDate: 2010-04-28T21:42:03.9484725Z
                }
            ]
        },
        {
            Id: 1,
            BlogId: 1,
            PostType: None,
            Title: RavenDB,
            Labels: [],
            Tags: 
            [
                Raven,
                NoSQL,
                JSON,
                .NET
            ],
            Comments: 
            [
                {
                    Content: First Comment!,
                    CreatedDate: 2010-04-28T21:42:03.9004697Z
                },
                {
                    Content: Second Comment!,
                    CreatedDate: 2010-04-28T21:42:03.9004697Z
                }
            ]
        },
        {
            Id: 2,
            BlogId: 1,
            PostType: None,
            Title: Cassandra,
            Labels: [],
            Tags: 
            [
                Cassandra,
                NoSQL,
                Scalability,
                Hashing
            ],
            Comments: 
            [
                {
                    Content: First Comment!,
                    CreatedDate: 2010-04-28T21:42:03.9004697Z
                }
            ]
        }
    ]

     */
}
```


### 2. Using a custom translation to migrate data using application logic

Some drawbacks with the above 'do-nothing' approach is that you will lose the data of 'renamed fields'.
There will also be times when you want the newly migrated data to have specific values that are different from the .NET built-in defaults.
When you want more control over the migration of your old data, adding a custom translation is a trivial exercise when you can do it natively in code:


```csharp
var repository = new BlogRepository(redisClient);

//Populate the datastore with the old schema from the 'BlogPostBestPractice'
BlogPostBestPractice.InsertTestData(repository);

//Create a typed-client based on the new schema
using (var redisBlogPosts = redisClient.GetTypedClient<BlogPost>())
using (var redisNewBlogPosts = redisClient.GetTypedClient<New.BlogPost>())
{
    //Automatically retrieve blog posts
    IList<BlogPost> oldBlogPosts = redisBlogPosts.GetAll();

    //Write a custom translation layer to migrate to the new schema
    var migratedBlogPosts = oldBlogPosts.ConvertAll(old => new New.BlogPost
    {
        Id = old.Id,
        BlogId = old.BlogId,
        Title = old.Title,
        Content = old.Content,
        Labels = old.Categories, //populate with data from renamed field
        PostType = New.BlogPostType.Article, //select non-default enum value
        Tags = old.Tags,
        Comments = old.Comments.ConvertAll(x => new Dictionary<string, string> 
            { { "Content", x.Content }, { "CreatedDate", x.CreatedDate.ToString() }, }),
        NoOfComments = old.Comments.Count, //populate using logic from old data
    });

    //Persist the new migrated blogposts 
    redisNewBlogPosts.StoreAll(migratedBlogPosts);

    //Read out the newly stored blogposts
    var refreshedNewBlogPosts = redisNewBlogPosts.GetAll();
    //Note: data renamed fields are successfully migrated to the new schema
    Console.WriteLine(refreshedNewBlogPosts.Dump());
    /*
    [
        {
            Id: 3,
            BlogId: 2,
            PostType: Article,
            Title: Redis,
            Labels: 
            [
                NoSQL,
                Cache
            ],
            Tags: 
            [
                Redis,
                NoSQL,
                Scalability,
                Performance
            ],
            Comments: 
            [
                {
                    Content: First Comment!,
                    CreatedDate: 28/04/2010 22:58:35
                }
            ],
            NoOfComments: 1
        },
        {
            Id: 4,
            BlogId: 2,
            PostType: Article,
            Title: Couch Db,
            Labels: 
            [
                NoSQL,
                DocumentDB
            ],
            Tags: 
            [
                CouchDb,
                NoSQL,
                JSON
            ],
            Comments: 
            [
                {
                    Content: First Comment!,
                    CreatedDate: 28/04/2010 22:58:35
                }
            ],
            NoOfComments: 1
        },
        {
            Id: 1,
            BlogId: 1,
            PostType: Article,
            Title: RavenDB,
            Labels: 
            [
                NoSQL,
                DocumentDB
            ],
            Tags: 
            [
                Raven,
                NoSQL,
                JSON,
                .NET
            ],
            Comments: 
            [
                {
                    Content: First Comment!,
                    CreatedDate: 28/04/2010 22:58:35
                },
                {
                    Content: Second Comment!,
                    CreatedDate: 28/04/2010 22:58:35
                }
            ],
            NoOfComments: 2
        },
        {
            Id: 2,
            BlogId: 1,
            PostType: Article,
            Title: Cassandra,
            Labels: 
            [
                NoSQL,
                Cluster
            ],
            Tags: 
            [
                Cassandra,
                NoSQL,
                Scalability,
                Hashing
            ],
            Comments: 
            [
                {
                    Content: First Comment!,
                    CreatedDate: 28/04/2010 22:58:35
                }
            ],
            NoOfComments: 1
        }
    ]

     */
}
```


The end result is a datastore filled with new data populated in exactly the way you want it - ready to serve features of your new application.
In contrast, attempting the above in a typical RDBMS solution without any downtime is effectively a feat of magic that is rewardable by 999 [Stack Overflow](http://stackoverflow.com) points and a personal condolence from its grand chancellor [@JonSkeet](http://twitter.com/jonskeet) :)

I hope this clearly illustrates differences between the two technologies. In practice you'll be amazed by the productivity gains made possible when you don't have to model your application to fit around an ORM and an RDBMS and can save objects like it was memory.

It's always a good idea to expose yourself to new technologies so if you haven't already done so, I invite you to get started developing with Redis today to see the benefits for yourself. To get started all you need is an instance of
[the redis-server](http://code.google.com/p/servicestack/wiki/RedisWindowsDownload) (no configuration required, just unzip and run) and the dependency-free
[ServiceStack's C# Redis Client](https://github.com/ServiceStack/ServiceStack.Redis) and you're ready to go!


# Blazor Server Tailwind Template
Source: https://docs.servicestack.net/templates/blazor-server

<div class="not-prose">
    <div id="blazor-server" class="hide-title mt-12 ml-20 flex flex-col items-center">
        <div class="flex">
            <svg class="w-24 h-24 text-purple-600 mr-8" xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24"><path fill="currentColor" d="M23.834 8.101a13.912 13.912 0 0 1-13.643 11.72a10.105 10.105 0 0 1-1.994-.12a6.111 6.111 0 0 1-5.082-5.761a5.934 5.934 0 0 1 11.867-.084c.025.983-.401 1.846-1.277 1.871c-.936 0-1.374-.668-1.374-1.567v-2.5a1.531 1.531 0 0 0-1.52-1.533H8.715a3.648 3.648 0 1 0 2.695 6.08l.073-.11l.074.121a2.58 2.58 0 0 0 2.2 1.048a2.909 2.909 0 0 0 2.695-3.04a7.912 7.912 0 0 0-.217-1.933a7.404 7.404 0 0 0-14.64 1.603a7.497 7.497 0 0 0 7.308 7.405s.549.05 1.167.035a15.803 15.803 0 0 0 8.475-2.528c.036-.025.072.025.048.061a12.44 12.44 0 0 1-9.69 3.963a8.744 8.744 0 0 1-8.9-8.972a9.049 9.049 0 0 1 3.635-7.247a8.863 8.863 0 0 1 5.229-1.726h2.813a7.915 7.915 0 0 0 5.839-2.578a.11.11 0 0 1 .059-.034a.112.112 0 0 1 .12.053a.113.113 0 0 1 .015.067a7.934 7.934 0 0 1-1.227 3.549a.107.107 0 0 0-.014.06a.11.11 0 0 0 .073.095a.109.109 0 0 0 .062.004a8.505 8.505 0 0 0 5.913-4.876a.155.155 0 0 1 .055-.053a.15.15 0 0 1 .147 0a.153.153 0 0 1 .054.053A10.779 10.779 0 0 1 23.834 8.1zM8.895 11.628a2.188 2.188 0 1 0 2.188 2.188v-2.042a.158.158 0 0 0-.15-.15Z"/></svg>
            <svg class="w-28 h-28" xmlns="http://www.w3.org/2000/svg" width="256" height="154" viewBox="0 0 256 154"><defs><linearGradient id="logosTailwindcssIcon0" x1="-2.778%" x2="100%" y1="32%" y2="67.556%"><stop offset="0%" stop-color="#2298BD"/><stop offset="100%" stop-color="#0ED7B5"/></linearGradient></defs><path fill="url(#logosTailwindcssIcon0)" d="M128 0C93.867 0 72.533 17.067 64 51.2C76.8 34.133 91.733 27.733 108.8 32c9.737 2.434 16.697 9.499 24.401 17.318C145.751 62.057 160.275 76.8 192 76.8c34.133 0 55.467-17.067 64-51.2c-12.8 17.067-27.733 23.467-44.8 19.2c-9.737-2.434-16.697-9.499-24.401-17.318C174.249 14.743 159.725 0 128 0ZM64 76.8C29.867 76.8 8.533 93.867 0 128c12.8-17.067 27.733-23.467 44.8-19.2c9.737 2.434 16.697 9.499 24.401 17.318C81.751 138.857 96.275 153.6 128 153.6c34.133 0 55.467-17.067 64-51.2c-12.8 17.067-27.733 23.467-44.8 19.2c-9.737-2.434-16.697-9.499-24.401-17.318C110.249 91.543 95.725 76.8 64 76.8Z"/></svg>
        </div>
    </div>
    <div class="relative bg-white dark:bg-black py-4">
      <div class="mx-auto max-w-md px-4 text-center sm:max-w-3xl sm:px-6 lg:max-w-7xl lg:px-8">
        <p class="mt-2 text-3xl font-extrabold tracking-tight text-gray-900 dark:text-gray-50 sm:text-4xl">Blazor Server Tailwind Template</p>
        <p class="mx-auto mt-5 max-w-prose text-xl text-gray-500">
          Ultimate dev model & UX ideal for low-latency Intranet environments
        </p>
      </div>
    </div>
    <a href="https://blazor.web-templates.io">
      <div class="block flex justify-center shadow hover:shadow-lg rounded py-1">
        <img class="p-4" src="https://raw.githubusercontent.com/ServiceStack/Assets/master/csharp-templates/blazor.png">
      </div>
    </a>
</div>

[ServiceStack.Blazor's Tailwind Components](/templates/blazor-components) also work flawlessly in [Blazor Server Apps](https://learn.microsoft.com/en-us/aspnet/core/blazor/hosting-models?view=aspnetcore-6.0#blazor-server) which benefits from fast startup and exceptional responsiveness in low latency environments thanks to its architecture of running your App in a server session that only needs to propagate thin UI Virtual DOM updates to clients.

The Blazor Server App template offers a number compelling advantages over Blazor WASM, including:

 - A superior dev model and debugging experience
 - Improved live-reload and faster iterative dev cycles
 - Full access to .NET Server functionality
 - Better start times & UI responsiveness
 - Less complexity from unnecessary client project or pre-rendering solutions

Although [the limitations](https://learn.microsoft.com/en-us/aspnet/core/blazor/hosting-models?view=aspnetcore-6.0#blazor-server) of its highly-coupled stateful server rendering session architecture does make it a poor fit for most high latency Internet sites which we continue to recommend our [Blazor WASM project template](/templates/blazor-tailwind) for.

To better showcase our growing Blazor functionality we've created the new Blazor Gallery websites showcasing usage of available rich Blazor Components for rapidly develop beautiful Tailwind Web Apps:

<div id="blazor-component-gallery" class="relative bg-white dark:bg-black py-4">
  <div class="mx-auto max-w-md px-4 text-center sm:max-w-3xl sm:px-6 lg:max-w-7xl lg:px-8">
    <p class="mt-2 text-3xl font-extrabold tracking-tight text-gray-900 dark:text-gray-50 sm:text-4xl">Blazor Gallery</p>
    <p class="mx-auto mt-5 max-w-prose text-xl text-gray-500">
      Discover ServiceStack.Blazor Rich UI Components and Integrated Features
    </p>
  </div>
</div>

[![](/img/pages/blazor/gallery-splash.png)](https://blazor-gallery.servicestack.net)

As our components support both hosting models we're maintaining identical Gallery sites running on both **Blazor Server** and **WASM**:

<div class="not-prose mb-16 mx-auto mt-5 max-w-md sm:flex sm:justify-center md:mt-8">
  <div class="rounded-md shadow">
    <a href="https://blazor-gallery.servicestack.net" class="flex w-full items-center justify-center rounded-md border border-transparent bg-indigo-600 px-8 py-3 text-base font-medium text-white hover:bg-indigo-700 md:py-4 md:px-10 md:text-lg hover:no-underline">
      Blazor Server
    </a>
  </div>
  <div class="mt-3 rounded-md shadow sm:mt-0 sm:ml-3">
    <a href="https://blazor-gallery.jamstacks.net" class="flex w-full items-center justify-center rounded-md border border-transparent bg-white px-8 py-3 text-base font-medium text-indigo-600 hover:bg-gray-50 md:py-4 md:px-10 md:text-lg hover:no-underline">
      Blazor WASM
    </a>
  </div>
</div>

For a closer look at ServiceStack.Blazor Components in action, download & run them to see how good they'll run in your Environment:

<div class="flex flex-col">
  <a href="https://github.com/NetCoreApps/BlazorGallery" class="flex text-xl text-gray-800">
    <svg class="w-6 h-6 mr-2 align-text-bottom" xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24"><path fill="currentColor" d="M12 .297c-6.63 0-12 5.373-12 12c0 5.303 3.438 9.8 8.205 11.385c.6.113.82-.258.82-.577c0-.285-.01-1.04-.015-2.04c-3.338.724-4.042-1.61-4.042-1.61C4.422 18.07 3.633 17.7 3.633 17.7c-1.087-.744.084-.729.084-.729c1.205.084 1.838 1.236 1.838 1.236c1.07 1.835 2.809 1.305 3.495.998c.108-.776.417-1.305.76-1.605c-2.665-.3-5.466-1.332-5.466-5.93c0-1.31.465-2.38 1.235-3.22c-.135-.303-.54-1.523.105-3.176c0 0 1.005-.322 3.3 1.23c.96-.267 1.98-.399 3-.405c1.02.006 2.04.138 3 .405c2.28-1.552 3.285-1.23 3.285-1.23c.645 1.653.24 2.873.12 3.176c.765.84 1.23 1.91 1.23 3.22c0 4.61-2.805 5.625-5.475 5.92c.42.36.81 1.096.81 2.22c0 1.606-.015 2.896-.015 3.286c0 .315.21.69.825.57C20.565 22.092 24 17.592 24 12.297c0-6.627-5.373-12-12-12"/></svg>
    <span>NetCoreApps/BlazorGallery</span>
  </a>
  <a href="https://github.com/NetCoreApps/BlazorGalleryWasm" class="flex mt-2 text-xl text-gray-800">
    <svg class="w-6 h-6 mr-2 align-text-bottom" xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24"><path fill="currentColor" d="M12 .297c-6.63 0-12 5.373-12 12c0 5.303 3.438 9.8 8.205 11.385c.6.113.82-.258.82-.577c0-.285-.01-1.04-.015-2.04c-3.338.724-4.042-1.61-4.042-1.61C4.422 18.07 3.633 17.7 3.633 17.7c-1.087-.744.084-.729.084-.729c1.205.084 1.838 1.236 1.838 1.236c1.07 1.835 2.809 1.305 3.495.998c.108-.776.417-1.305.76-1.605c-2.665-.3-5.466-1.332-5.466-5.93c0-1.31.465-2.38 1.235-3.22c-.135-.303-.54-1.523.105-3.176c0 0 1.005-.322 3.3 1.23c.96-.267 1.98-.399 3-.405c1.02.006 2.04.138 3 .405c2.28-1.552 3.285-1.23 3.285-1.23c.645 1.653.24 2.873.12 3.176c.765.84 1.23 1.91 1.23 3.22c0 4.61-2.805 5.625-5.475 5.92c.42.36.81 1.096.81 2.22c0 1.606-.015 2.896-.015 3.286c0 .315.21.69.825.57C20.565 22.092 24 17.592 24 12.297c0-6.627-5.373-12-12-12"/></svg>
    <span>NetCoreApps/BlazorGalleryWasm</span>
  </a>
  <a href="https://docs.servicestack.net/vue/" class="flex mt-2 text-xl text-gray-800">
    <svg class="w-6 h-6 mr-2 align-text-bottom" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" aria-hidden="true" role="img" class="w-28 h-28 sm:w-44 sm:h-44 iconify iconify--vscode-icons" width="1em" height="1em" viewBox="0 0 32 32"><path fill="#41b883" d="M24.4 3.925H30l-14 24.15L2 3.925h10.71l3.29 5.6l3.22-5.6Z"></path><path fill="#41b883" d="m2 3.925l14 24.15l14-24.15h-5.6L16 18.415L7.53 3.925Z"></path><path fill="#35495e" d="M7.53 3.925L16 18.485l8.4-14.56h-5.18L16 9.525l-3.29-5.6Z"></path></svg>
    <span>Vue Component Gallery</span>
  </a>
</div>

<p class="hide-h2"></p>

## Getting Started

Customize and Download a new Blazor WASM Bootstrap project with your preferred project name:

<h3 class="text-center">Download new C# Blazor Project</h3>

<blazor-templates class="not-prose pb-8"></blazor-templates>

Alternatively you can create & download a new Blazor Project with the [x dotnet tool](/dotnet-new):

:::sh
x new blazor ProjectName
:::


## Universal Blazor Components

Blazor Server has become our preferred platform for Interactive **Intranet** Apps which excels in **low-latency environments** to enable a best-in-class responsive end-user UX that also offers a superior development experience in Visual Studio's live reload where it enables a fast iterative development workflow and good debugging experience.

A fantastic property of Blazor is its support for multiple hosting modes which allows the same components from being able to run in the Browser with Blazor WASM or rendered on the Server with Blazor Server. But whilst Blazor is capable of it, this trait is typically conceded in most Apps with database access where it recommends using
[EF Core directly in Blazor components](https://learn.microsoft.com/en-us/aspnet/core/blazor/blazor-server-ef-core?view=aspnetcore-7.0) - effectively prohibiting reuse in Blazor WASM should you ever want to utilize Blazor's preferred hosting model for hosting your Blazor App's on the Internet.

<div class="my-8 flex justify-center">
    <lite-youtube class="w-full mx-4 my-4" width="560" height="315" videoid="66DgLHExC9E" style="background-image: url('https://img.youtube.com/vi/66DgLHExC9E/maxresdefault.jpg')"></lite-youtube>
</div>

## Blazing Fast Networkless APIs

Whilst better performing, having Blazor components access DB's directly encourages a more tightly-coupled and less reusable & testable architecture than the traditional well-defined API dev model used in client/server Mobile & Desktop Apps or Web SPA Apps like WASM.

To achieve the best of both worlds, we've enabled support for utilizing the In Process [Service Gateway](/service-gateway) in Blazor Server Apps which lets you retain the traditional client/server dev model for invoking your Server APIs **In Process** - avoiding any serialization, HTTP networking or even Kestrel middleware overhead to invoke your APIs directly!

This enables using the **exact same source code** to call APIs in Blazor Server and WASM which allows us to develop reusable Blazor Components to invoke the same Server APIs that serve Web, Mobile and Desktop Apps in Blazor Server Apps. Where instead of using HttpClient to invoke your APIs, they're invoked directly from a C# method which will preserve its StackTrace where you'll be able to track the API call down to the Blazor UI component calling it.

ServiceStack's [Message-based API Design](/api-design) makes it possible for all API calls in ServiceStack.Blazor components and project templates to be routed through these 2 methods:

```csharp
public interface IServiceGatewayAsync
{
  Task<TResponse> SendAsync<TResponse>(object dto, CancellationToken ct=default);
  //...
}

public interface IServiceGatewayFormAsync
{
  Task<TResponse> SendFormAsync<TResponse>(object dto, MultipartFormDataContent form, CancellationToken ct);
}
```

::: info
The `SendFormAsync` API is a new method added to support multi-part API requests with File Uploads
:::

Which allows the HTTP `JsonApiClient` and networkless `InProcessGateway` clients to be used interchangeably. By default Blazor Server Apps now use the InProcess Gateway but can be switched over to invoke APIs using the HTTP `JsonApiClient` with:

```csharp
BlazorConfig.Set(new() {
    UseInProcessClient = false
});
```

Which changes all `Api*` methods in Blazor components and Pages inheriting ServiceStack.Blazor's [BlazorComponentBase](https://reference.servicestack.net/api/ServiceStack.Blazor/BlazorComponentBase) to use the registered `JsonApiClient` client.

Other components can access both the InProcess Gateway or `JsonApiClient` by injecting the `IClientFactory` dependency into their components, e.g:

```csharp
public class MyComponent : ComponentBase
{
    [Inject] public IClientFactory? ClientFactory { get; set; }

    public IServiceGateway Gateway => ClientFactory!.GetGateway();
    public JsonApiClient Client => ClientFactory!.GetClient();
}
```

This capability is what has made it possible for high-level "API-enabled" components like [AutoQuery Grids](https://blazor-gallery.jamstacks.net/grid) and [AutoForm](https://blazor-gallery.jamstacks.net/gallery/autoform) to support both Blazor Server and Blazor WASM utilizing the most efficient API client available to its platform.

The Blazor Gallery websites themselves are also good demonstrations of being able to run **entire Web Apps** in both Blazor Server and WASM, with all development being done with Blazor Server to take advantage of its superior iterative dev model then a script is used to "export" all pages to an identical Blazor WASM project.

## Api and ApiAsync methods

.NET was originally conceived to use Exceptions for error control flow however there's been a tendency in modern languages & libraries to shun Exceptions and return errors as normal values, an approach we believe is a more flexible & ergonomic way to handle API responses.

### The ApiResult way

The `Api(Request)` and `ApiAsync(Request)` APIs returns a typed `ApiResult<Response>` Value Result encapsulating either a Typed Response or a structured API Error populated in `ResponseStatus` allowing you to handle API responses programmatically without `try/catch` handling:

The below example code to create a new Booking:

```csharp
CreateBooking request = new();

ApiResult<IdResponse> api = new();

async Task OnSubmit()
{
    api = await Client.ApiAsync(request);

    if (api.Succeeded)
    {
        await done.InvokeAsync(api.Response!);
        request = new();
    }
}
```

Which despite its terseness handles both **success** and **error** API responses, **if successful** it invokes the `done()` callback notifying its parent of the new Booking API Response before resetting the Form's data model with a new Request DTO.

Upon **failure** the error response is populated in `api.Error` which binds to the UI via Blazor's `<CascadingValue Value=@api.Error>` to propagate it to all its child components in order to show contextual validation errors next to their respective Input controls.

### Public Pages & Components

To reduce boiler plate, your Blazor Pages & components can inherit the templates local [AppComponentBase.cs](https://github.com/NetCoreTemplates/blazor-wasm/blob/main/MyApp.Client/AppComponentBase.cs) which inherits `BlazorComponentBase` that gets injected with the `IClientFactory` and provides convenient access to most common APIs:

```csharp
public class BlazorComponentBase : ComponentBase, IHasJsonApiClient
{
    [Inject] public IClientFactory? ClientFactory { get; set; }
    public IServiceGateway Gateway => ClientFactory!.GetGateway();
    public JsonApiClient Client => ClientFactory!.GetClient();

    public virtual Task<ApiResult<TResponse>> ApiAsync<TResponse>(IReturn<TResponse> request) => UseGateway
        ? Gateway.ManagedApiAsync(request)
        : Client.ManagedApiAsync(request);

    public virtual Task<ApiResult<EmptyResponse>> ApiAsync(IReturnVoid request); /*...*/
    public virtual Task<TResponse> SendAsync<TResponse>(IReturn<TResponse> request);
    public virtual Task<IHasErrorStatus> ApiAsync<Model>(object request);
    public virtual Task<ApiResult<Model>> ApiFormAsync<Model>(object requestDto, MultipartFormDataContent request);
}
```

### Protected Pages & Components

Pages and Components requiring Authentication should inherit from [AppAuthComponentBase](https://github.com/NetCoreTemplates/blazor-wasm/blob/main/MyApp.Client/AppComponentBase.cs) instead which integrates with Blazor's Authentication Model to provide access to the currently authenticated user:

```csharp
public abstract class AppAuthComponentBase : AppComponentBase
{
    [CascadingParameter]
    protected Task<AuthenticationState>? AuthenticationStateTask { get; set; }

    protected bool HasInit { get; set; }

    protected bool IsAuthenticated => User?.Identity?.IsAuthenticated ?? false;

    protected ClaimsPrincipal? User { get; set; }

    protected override async Task OnParametersSetAsync()
    {
        var state = await AuthenticationStateTask!;
        User = state.User;
        HasInit = true;
    }
}
```

## Benefits of Shared DTOs

Typically with Web Apps, our client is using a different language to C#, so an equivalent request DTOs need to be generated for the client.

### TypeScript Example

For example, TypeScript generated DTOs still give us typed end-to-end services with the help of tooling like [Add ServiceStack Reference](/add-servicestack-reference)

```csharp
[Route("/hello/{Name}")]
public class Hello : IReturn<HelloResponse>
{
    public string Name { get; set; }
}

public class HelloResponse
{
    public string Result { get; set; }
}
```

Turns into:

```typescript
// @Route("/hello/{Name}")
export class Hello implements IReturn<HelloResponse>
{
    public name: string;

    public constructor(init?: Partial<Hello>) { (Object as any).assign(this, init); }
    public getTypeName() { return 'Hello'; }
    public getMethod() { return 'POST'; }
    public createResponse() { return new HelloResponse(); }
}

export class HelloResponse
{
    public result: string;
    public responseStatus: ResponseStatus;

    public constructor(init?: Partial<HelloResponse>) { (Object as any).assign(this, init); }
}
```

When Request or Response DTOs changes during development, the client DTOs need to be regenerated using a command like [`x csharp`](./add-servicestack-reference.md#simple-command-line-utilities).

### Blazor Server Example

Developing your Blazor Server UI however, you just change your shared request/response DTO in the shared `ServiceModel` project, and both your client and server compile against the same request/response DTO classes.
This eliminates the need for any additional step.

In the `ServiceModel` project, we still have:

```csharp
[Route("/hello/{Name}")]
public class Hello : IReturn<HelloResponse>
{
    public string Name { get; set; }
}

public class HelloResponse
{
    public string Result { get; set; }
}
```

Which the Blazor C# App can use directly in its **.razor** pages:

```csharp
@code {
    Hello request = new()
    {
        Name = "Blazor WASM"
    };

    ApiResult<HelloResponse> api = new();

    protected override async Task OnInitializedAsync() => await submit();

    async Task submit() => api = await ApiAsync(request);
}
```

## ServiceStack.Blazor Components

The [ServiceStack.Blazor Components library](/templates/blazor-components) contains integrated functionality for Blazor including API-enabled base components, HTML Utils and Tailwind UI Input components heavily utilized throughout the template.


# Blazor Tailwind
Source: https://docs.servicestack.net/templates/blazor-tailwind

<div class="not-prose mt-16 flex flex-col items-center">
   <div class="flex">
      <svg class="w-28 h-28 text-purple-500" xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24"><path fill="currentColor" d="M23.834 8.101a13.912 13.912 0 0 1-13.643 11.72a10.105 10.105 0 0 1-1.994-.12a6.111 6.111 0 0 1-5.082-5.761a5.934 5.934 0 0 1 11.867-.084c.025.983-.401 1.846-1.277 1.871c-.936 0-1.374-.668-1.374-1.567v-2.5a1.531 1.531 0 0 0-1.52-1.533H8.715a3.648 3.648 0 1 0 2.695 6.08l.073-.11l.074.121a2.58 2.58 0 0 0 2.2 1.048a2.909 2.909 0 0 0 2.695-3.04a7.912 7.912 0 0 0-.217-1.933a7.404 7.404 0 0 0-14.64 1.603a7.497 7.497 0 0 0 7.308 7.405s.549.05 1.167.035a15.803 15.803 0 0 0 8.475-2.528c.036-.025.072.025.048.061a12.44 12.44 0 0 1-9.69 3.963a8.744 8.744 0 0 1-8.9-8.972a9.049 9.049 0 0 1 3.635-7.247a8.863 8.863 0 0 1 5.229-1.726h2.813a7.915 7.915 0 0 0 5.839-2.578a.11.11 0 0 1 .059-.034a.112.112 0 0 1 .12.053a.113.113 0 0 1 .015.067a7.934 7.934 0 0 1-1.227 3.549a.107.107 0 0 0-.014.06a.11.11 0 0 0 .073.095a.109.109 0 0 0 .062.004a8.505 8.505 0 0 0 5.913-4.876a.155.155 0 0 1 .055-.053a.15.15 0 0 1 .147 0a.153.153 0 0 1 .054.053A10.779 10.779 0 0 1 23.834 8.1zM8.895 11.628a2.188 2.188 0 1 0 2.188 2.188v-2.042a.158.158 0 0 0-.15-.15Z"></path></svg>
   </div>
</div>
<div class="not-prose mt-4 px-4 sm:px-6">
<div class="text-center"><h3 id="blazor-template" class="text-4xl sm:text-5xl md:text-6xl tracking-tight font-extrabold text-gray-900">
    Blazor WASM Tailwind
</h3></div>
<div class="py-8 max-w-7xl mx-auto px-4 sm:px-6">
    <lite-youtube class="w-full mx-4 my-4" width="560" height="315" videoid="BXjcKkaK-nM" style="background-image: url('https://img.youtube.com/vi/BXjcKkaK-nM/maxresdefault.jpg')"></lite-youtube>
</div>
</div>

<div class="relative bg-white dark:bg-black py-4">
    <div class="mx-auto max-w-md px-4 text-center sm:max-w-3xl sm:px-6 lg:max-w-7xl lg:px-8">
        <h2 class="text-base font-semibold uppercase tracking-wider text-indigo-600">Getting Started</h2>
        <p class="mt-2 text-3xl font-extrabold tracking-tight text-gray-900 dark:text-gray-50 sm:text-4xl">Create a new Blazor WASM Tailwind App</p>
        <p class="mx-auto mt-5 max-w-prose text-xl text-gray-500"> 
            Create a new Blazor WASM Tailwind project with your preferred project name:
        </p>
    </div>
</div>

<blazor-templates class="not-prose pb-8"></blazor-templates>

Alternatively you can create & download a new Blazor Project with the [x dotnet tool](/dotnet-new):

:::sh
x new blazor-wasm ProjectName
:::

The feature-rich Blazor WASM Tailwind template is ideal for teams with strong C# skills building Line Of Business (LOB) applications who prefer utilizing Tailwind's modern utility-first CSS design system to create beautiful, instant-loading Blazor WASM Apps.

<a href="https://blazor-wasm.web-templates.io">
    <div class="block flex justify-center shadow hover:shadow-lg rounded py-1">
        <img class="" src="/img/pages/blazor/blazor-tailwind-splash.png">
    </div>
    <div class="pt-4 text-center">
        blazor-wasm.web-templates.io
    </div>
</a>

Since the release of .NET 8, we have been upgrading our [Blazor Templates](https://servicestack.net/start) and example applications to take advantage of some of the new features, including making use of static Server Side Rendering (SSR) for Blazor, which allows for faster initial page loads and better SEO, and our [blazor-wasm](https://github.com/NetCoreTemplates/blazor-wasm) template uses `InteractiveAuto` by default to provide a more Responsive UI.

## What is InteractiveAuto?

Blazor for .NET 8 has [four different rendering modes](https://learn.microsoft.com/en-us/aspnet/core/blazor/components/render-modes?view=aspnetcore-8.0#render-modes) you can take advantage of:

- Static Server (static SSR)
- Interactive Server
- Interactive WebAssembly (WASM)
- Interactive Auto

For non-interactive pages, the static SSR mode is the fastest, as it renders the page on the server and sends the HTML to the client.
However, when your page needs to be interactive, you need to use one of the interactive modes.

Prior to .NET 8, there was a trade-off between the two available render modes (static server rendering wasn't yet available).
The `Interactive Server` mode was faster to load, but the `Interactive WASM` mode was more responsive.

The initial load times for `Interactive WASM` could be quite slow, as the entire application and all its dependencies needed to be downloaded before the page could render most of the content.

<img class="border-gray-800 border-t border-r" src="/img/pages/blazor/wasm/blazor-wasm-6-slow.gif">

> The initial load time for the `Interactive WASM` mode can be quite slow even for a minimal app

Our templates previously worked around this limitation with a custom Pre-Rendering solution, as the wait times were too long for a good user experience.

.NET 8's new `Interactive Auto` mode provides the best of both worlds as pre-rendering is now enabled by default.

<img class="border-gray-800 border-r" src="/img/pages/blazor/wasm/blazor-wasm-8-fast.gif">

When the page is first loaded, it uses the `Interactive Server` mode, which is faster than `Interactive WASM` as it doesn't need to download WASM resources.
So the user can start interacting with the page straight away, but with a slight delay for each of their interactions due to having to perform round-trips to the server for each interaction.

In the background, the WASM resources are downloaded which can then be used to render the site on the client for subsequent visits.

## Using InteractiveAuto in your Blazor application

In Blazor for .NET 8, render modes can be set on both a per-page and per-component basis.

```html
@page "/counter"
@rendermode InteractiveAuto

<Counter />
```

```html
<Counter @rendermode="RenderMode.InteractiveAuto" />
```

## ServiceStack.Blazor Components

The [ServiceStack.Blazor Components](https://blazor-gallery.jamstacks.net) have been updated for .NET 8 and work with the new `InteractiveAuto` render mode.

This means you can focus more on your application logic and less on the UI, as the components provide a high-productivity UI for common tasks such as CRUD operations.

### AutoQueryGrid

The [AutoQueryGrid](https://blazor-gallery.servicestack.net/gallery/autoquerygrid) component provides a full-featured data grid that can be used to display and edit data from an AutoQuery service.
This is ideal for creating custom admin pages for your application. 
By integrating your admin screens into your application, you can optimize the user experience for specific workflows and get a huge amount of reuse of your existing AutoQuery services.

```html
<AutoQueryGrid Model="Modifier" Apis="Apis.AutoQuery<QueryModifiers,CreateModifier,UpdateModifier,DeleteModifier>()" />
```

![](/img/pages/blazor/wasm/autoquerygrid.png)

For [BlazorDiffusion](https://github.com/NetCoreApps/BlazorDiffusionAuto), our StableDiffusion example application, we used the AutoQueryGrid to create a custom admin page for managing the modifiers in the application.

![](/img/pages/blazor/wasm/stablediffusion-modifiers.png)

This is the simplest and fastest use of the AutoQueryGrid component, but it can also be heavily customized for lots of different use cases.

In [BlazorDiffusion](https://github.com/NetCoreApps/BlazorDiffusionAuto) we customize the grid to enable easy navigation contextually between separate customized admin screens for each Creative, linking to related table data.

![](/img/pages/blazor/wasm/blazordiffusion-creatives.png)

```html
<AutoQueryGrid @ref=@grid Model="Creative" Apis="Apis.AutoQuery<QueryCreatives,UpdateCreative,HardDeleteCreative>()"
               ConfigureQuery="ConfigureQuery">
    <EditForm>
        <div class="relative z-10" aria-labelledby="slide-over-title" role="dialog" aria-modal="true">
            <div class="pointer-events-none fixed inset-y-0 right-0 flex max-w-full pl-10 sm:pl-16">
                <CreativeEdit Creative="context" OnClose="grid.OnEditDone" />
            </div>
        </div>
    </EditForm>
    <Columns>
        <Column Title="User" Field="(Creative x) => x.OwnerId" />
        <Column Title="Id" Field="(Creative x) => x.Id" />
        <Column Field="(Creative x) => x.Modifiers">
            <Template>
                @if (context.Modifiers?.Count > 0)
                {
                <TextLink class="flex" href=@($"/admin/modifiers?Ids={string.Join(",", context.Modifiers.Select(x => x.ModifierId))}")>
                    <Icon class="w-6 h-6 mr-1" Image=@typeof(Modifier).GetIcon() />
                    @TextUtils.Pluralize("Modifier", context.Modifiers)
                </TextLink>
                }
            </Template>
        </Column>
        <Column Field="(Creative x) => x.Artists">
            <Template>
                @if (context.Artists?.Count > 0)
                {
                <TextLink class="flex" href=@($"/admin/artists?Ids={string.Join(",", context.Artists.Select(x => x.ArtistId))}")>
                    <Icon class="w-6 h-6 mr-1" Image=@typeof(Artist).GetIcon() />
                    @TextUtils.Pluralize("Artist", context.Artists)
                </TextLink>
                }
            </Template>
        </Column>
        <Column Field="(Creative x) => x.Artifacts">
            <Template>
                @if (context.Artifacts?.Count > 0)
                {
                <TextLink class="flex" href=@($"/admin/artifacts?CreativeId={context.Id}")>
                    <Icon class="w-6 h-6 mr-1" Image=@typeof(Artifact).GetIcon() />
                    @TextUtils.Pluralize("Artifact", context.Artifacts)
                </TextLink>
                }
            </Template>
        </Column>
        <Column Field="(Creative x) => x.Key" />
        <Column Field="(Creative x) => x.CreatedDate" Format="s" />
        <Column Field="(Creative x) => x.UserPrompt" />
    </Columns>
</AutoQueryGrid>
```

In the above example, we use the `ConfigureQuery` parameter to customize the query used by the AutoQueryGrid when displaying values.
This is ideal if you want to filter the data for specific workflows, for example, only showing the data that is relevant to the current user.

We combine this with a `Tabs` component to provide a navigation bar for the user to switch between the different filters on the same AutoQueryGrid.

```html
<Tabs TabOptions="TabOptions" TabChanged="TabChangedAsync" />
```

:::{.shadow .max-w-screen-sm}
![](/img/pages/blazor/wasm/blazordiffusion-tab.png)
:::

<p></p>

:::{.shadow .max-w-screen-sm}
![](/img/pages/blazor/wasm/blazordiffusion-tab1.png)
:::

We also use the `EditForm` parameter to customize the edit form for the AutoQueryGrid, so the workflow for editing a Creative is optimized using your own completely custom UI.

```html
<AutoQueryGrid @ref=@grid Model="Creative" Apis="Apis.AutoQuery<QueryCreatives,UpdateCreative,HardDeleteCreative>()"
               ConfigureQuery="ConfigureQuery">
    <EditForm>
        <div class="relative z-10" aria-labelledby="slide-over-title" role="dialog" aria-modal="true">
            <div class="pointer-events-none fixed inset-y-0 right-0 flex max-w-full pl-10 sm:pl-16">
                <CreativeEdit Creative="context" OnClose="grid.OnEditDone" />
            </div>
        </div>
    </EditForm>
```

## Upgrading to .NET 8

[BlazorDiffusion](https://github.com/NetCoreApps/BlazorDiffusionAuto) was an example application we originally developed for .NET 6.
We upgraded the production release of this application to use our [blazor-vue](https://github.com/NetCoreTemplates/blazor-vue) template, which can be perfect for public-facing web applications and teams that don't mind including a JavaScript framework in their application.

However, to show the flexibility of Blazor for .NET 8, we also upgraded the whole application from our updated `blazor-wasm` template to take advantage of the new `InteractiveAuto` mode.

### Component Compatibility

Since the ServiceStack.Blazor library has been updated for .NET 8, we just needed to bring over the shared components from the original application and update the references to the new library.

When upgrading your application pages and components, you will need to avoid any JavaScript interop that runs during the `InitializeAsync` lifecycle method, as this is not supported in the `InteractiveAuto` mode.

### Running on both Server vs Client

When using the `InteractiveAuto` mode, first visits will be running on the server, so your pages and components need to be available to both projects, as well as have any required dependencies registered in both projects `Program.cs` files.

By placing your shared pages and components in a shared project like the `.Client` project in the `blazor-wasm` template, you can easily share them between the two projects.

Look for any of your pages or components that use the `@injects` directive, as these will need to be registered in both projects.

::: info
Avoid sharing sensitive information via dependency injection, as this will be available to the client at runtime which will be able to be decompiled and inspected.
:::

### Source code and live demo

The source code for the upgraded `BlazorDiffusionAuto` application is [available on GitHub](https://github.com/NetCoreApps/BlazorDiffusionAuto) and you can view a live demo of the application at [auto.blazordiffusion.com](https://auto.blazordiffusion.com).

### Conclusion

The new `InteractiveAuto` mode in Blazor for .NET 8 provides the best of both worlds for Blazor applications.
A built in pre-rendering solution means that you can have a fast initial load time, but still have a responsive UI for subsequent visits.

And since the ServiceStack.Blazor components have been updated for .NET 8, you can take advantage of the high-productivity UI components to quickly create customizable and professional-looking admin pages in a Blazor application.

---

<div id="blazor-components" class="hide-title not-prose mt-16 mb-8 ml-20 flex flex-col items-center">
    <div class="flex">
        <svg class="w-40 h-40 text-purple-600 mr-8" xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24"><path fill="currentColor" d="M23.834 8.101a13.912 13.912 0 0 1-13.643 11.72a10.105 10.105 0 0 1-1.994-.12a6.111 6.111 0 0 1-5.082-5.761a5.934 5.934 0 0 1 11.867-.084c.025.983-.401 1.846-1.277 1.871c-.936 0-1.374-.668-1.374-1.567v-2.5a1.531 1.531 0 0 0-1.52-1.533H8.715a3.648 3.648 0 1 0 2.695 6.08l.073-.11l.074.121a2.58 2.58 0 0 0 2.2 1.048a2.909 2.909 0 0 0 2.695-3.04a7.912 7.912 0 0 0-.217-1.933a7.404 7.404 0 0 0-14.64 1.603a7.497 7.497 0 0 0 7.308 7.405s.549.05 1.167.035a15.803 15.803 0 0 0 8.475-2.528c.036-.025.072.025.048.061a12.44 12.44 0 0 1-9.69 3.963a8.744 8.744 0 0 1-8.9-8.972a9.049 9.049 0 0 1 3.635-7.247a8.863 8.863 0 0 1 5.229-1.726h2.813a7.915 7.915 0 0 0 5.839-2.578a.11.11 0 0 1 .059-.034a.112.112 0 0 1 .12.053a.113.113 0 0 1 .015.067a7.934 7.934 0 0 1-1.227 3.549a.107.107 0 0 0-.014.06a.11.11 0 0 0 .073.095a.109.109 0 0 0 .062.004a8.505 8.505 0 0 0 5.913-4.876a.155.155 0 0 1 .055-.053a.15.15 0 0 1 .147 0a.153.153 0 0 1 .054.053A10.779 10.779 0 0 1 23.834 8.1zM8.895 11.628a2.188 2.188 0 1 0 2.188 2.188v-2.042a.158.158 0 0 0-.15-.15Z"/></svg>
        <svg class="w-44 h-44" xmlns="http://www.w3.org/2000/svg" width="256" height="154" viewBox="0 0 256 154"><defs><linearGradient id="logosTailwindcssIcon0" x1="-2.778%" x2="100%" y1="32%" y2="67.556%"><stop offset="0%" stop-color="#2298BD"/><stop offset="100%" stop-color="#0ED7B5"/></linearGradient></defs><path fill="url(#logosTailwindcssIcon0)" d="M128 0C93.867 0 72.533 17.067 64 51.2C76.8 34.133 91.733 27.733 108.8 32c9.737 2.434 16.697 9.499 24.401 17.318C145.751 62.057 160.275 76.8 192 76.8c34.133 0 55.467-17.067 64-51.2c-12.8 17.067-27.733 23.467-44.8 19.2c-9.737-2.434-16.697-9.499-24.401-17.318C174.249 14.743 159.725 0 128 0ZM64 76.8C29.867 76.8 8.533 93.867 0 128c12.8-17.067 27.733-23.467 44.8-19.2c9.737 2.434 16.697 9.499 24.401 17.318C81.751 138.857 96.275 153.6 128 153.6c34.133 0 55.467-17.067 64-51.2c-12.8 17.067-27.733 23.467-44.8 19.2c-9.737-2.434-16.697-9.499-24.401-17.318C110.249 91.543 95.725 76.8 64 76.8Z"/></svg>
    </div>
    <h2 class="border-none text-4xl sm:text-5xl md:text-6xl tracking-tight font-extrabold">
        <span class="text-purple-600 mr-6">Blazor</span>
        <span class="mr-6" style="color:#44A8B3">Tailwind</span>
    </h2>
</div>

### Blazor Tailwind Components

[Tailwind](https://tailwindcss.com) has quickly become the best modern CSS framework we've used to create scalable, 
[mobile-first responsive](https://tailwindcss.com/#mobile-first) websites built upon a beautiful expert-crafted constraint-based 
[Design System](https://tailwindcss.com/#constraint-based) that enabled effortless reuse of a growing suite of [Free Community](https://tailwindcomponents.com)
and professionally-designed [Tailwind UI Component Libraries](https://tailwindui.com) which has proven invaluable in quickly creating beautiful websites & docs
that have benefited all our new modern jamstacks.net templates.

[![](/img/pages/blazor/tailwindui.png)](https://tailwindui.com)

### ServiceStack.Blazor Components

Many of Tailwind UI's popular components are encapsulated in ServiceStack.Blazor's righ high-level tailwind components to enable the rapid development of CRUD UIs in Blazor Server and WASM Apps:

<div class="my-8 flex justify-center">
    <lite-youtube class="w-full mx-4 my-4" width="560" height="315" videoid="iKpQI2233nY" style="background-image: url('https://img.youtube.com/vi/iKpQI2233nY/maxresdefault.jpg')"></lite-youtube>
</div>

<div id="blazor-component-gallery" class="mt-16 relative bg-white py-4">
  <div class="mx-auto max-w-md px-4 text-center sm:max-w-3xl sm:px-6 lg:max-w-7xl lg:px-8">
    <p class="mt-2 text-3xl font-extrabold tracking-tight text-gray-900 dark:text-gray-50 sm:text-4xl">Blazor Gallery</p>
    <p class="mx-auto mt-5 max-w-prose text-xl text-gray-500">
      Discover ServiceStack.Blazor Rich UI Components and Integrated Features
    </p>
  </div>
</div>

[![](/img/pages/blazor/gallery-splash.png)](https://blazor-gallery.servicestack.net)

ServiceStack.Blazor Components support both hosting models which sees Blazor Gallery running on both **Blazor Server** and **WASM**:

<div class="not-prose mb-16 mx-auto mt-5 max-w-md sm:flex sm:justify-center md:mt-8">
  <div class="rounded-md shadow">
    <a href="https://blazor-gallery.servicestack.net" class="flex w-full items-center justify-center rounded-md border border-transparent bg-indigo-600 px-8 py-3 text-base font-medium text-white hover:bg-indigo-700 md:py-4 md:px-10 md:text-lg hover:no-underline">
      Blazor Server
    </a>
  </div>
  <div class="mt-3 rounded-md shadow sm:mt-0 sm:ml-3">
    <a href="https://blazor-gallery.jamstacks.net" class="flex w-full items-center justify-center rounded-md border border-transparent bg-white px-8 py-3 text-base font-medium text-indigo-600 hover:bg-gray-50 md:py-4 md:px-10 md:text-lg hover:no-underline">
      Blazor WASM
    </a>
  </div>
</div>

For a closer look at ServiceStack.Blazor Components in action, download & run them to see how good they'll run in your Environment:

<div class="flex flex-col">
  <a href="https://github.com/NetCoreApps/BlazorGallery" class="flex text-xl text-gray-800">
    <svg class="w-6 h-6 mr-2 align-text-bottom" xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24"><path fill="currentColor" d="M12 .297c-6.63 0-12 5.373-12 12c0 5.303 3.438 9.8 8.205 11.385c.6.113.82-.258.82-.577c0-.285-.01-1.04-.015-2.04c-3.338.724-4.042-1.61-4.042-1.61C4.422 18.07 3.633 17.7 3.633 17.7c-1.087-.744.084-.729.084-.729c1.205.084 1.838 1.236 1.838 1.236c1.07 1.835 2.809 1.305 3.495.998c.108-.776.417-1.305.76-1.605c-2.665-.3-5.466-1.332-5.466-5.93c0-1.31.465-2.38 1.235-3.22c-.135-.303-.54-1.523.105-3.176c0 0 1.005-.322 3.3 1.23c.96-.267 1.98-.399 3-.405c1.02.006 2.04.138 3 .405c2.28-1.552 3.285-1.23 3.285-1.23c.645 1.653.24 2.873.12 3.176c.765.84 1.23 1.91 1.23 3.22c0 4.61-2.805 5.625-5.475 5.92c.42.36.81 1.096.81 2.22c0 1.606-.015 2.896-.015 3.286c0 .315.21.69.825.57C20.565 22.092 24 17.592 24 12.297c0-6.627-5.373-12-12-12"/></svg>
    <span>NetCoreApps/BlazorGallery</span>
  </a>
  <a href="https://github.com/NetCoreApps/BlazorGalleryWasm" class="flex mt-2 text-xl text-gray-800">
    <svg class="w-6 h-6 mr-2 align-text-bottom" xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24"><path fill="currentColor" d="M12 .297c-6.63 0-12 5.373-12 12c0 5.303 3.438 9.8 8.205 11.385c.6.113.82-.258.82-.577c0-.285-.01-1.04-.015-2.04c-3.338.724-4.042-1.61-4.042-1.61C4.422 18.07 3.633 17.7 3.633 17.7c-1.087-.744.084-.729.084-.729c1.205.084 1.838 1.236 1.838 1.236c1.07 1.835 2.809 1.305 3.495.998c.108-.776.417-1.305.76-1.605c-2.665-.3-5.466-1.332-5.466-5.93c0-1.31.465-2.38 1.235-3.22c-.135-.303-.54-1.523.105-3.176c0 0 1.005-.322 3.3 1.23c.96-.267 1.98-.399 3-.405c1.02.006 2.04.138 3 .405c2.28-1.552 3.285-1.23 3.285-1.23c.645 1.653.24 2.873.12 3.176c.765.84 1.23 1.91 1.23 3.22c0 4.61-2.805 5.625-5.475 5.92c.42.36.81 1.096.81 2.22c0 1.606-.015 2.896-.015 3.286c0 .315.21.69.825.57C20.565 22.092 24 17.592 24 12.297c0-6.627-5.373-12-12-12"/></svg>
    <span>NetCoreApps/BlazorGalleryWasm</span>
  </a>
</div>

<div class="my-16 px-4 sm:px-6">
    <div class="text-center">
        <h1 class="text-4xl sm:text-5xl md:text-6xl tracking-tight font-extrabold text-gray-900">
            <span class="block">
                Creating Beautiful <span class="text-purple-600">Blazor Apps</span>
            </span>
            <span style="color:#44A8B3" class="block">with Tailwind</span>
        </h1>
    </div>
        <p class="mx-auto mt-5 max-w-prose text-xl text-gray-500"> 
            Preview the highly productive development model of the new Blazor Tailwind 
            template showing how easy it is to utilize beautifully designed components
        </p>
    <div class="my-8">
        <lite-youtube class="w-full mx-4 my-4" width="560" height="315" videoid="3gD_MMcYI-4" style="background-image: url('https://img.youtube.com/vi/3gD_MMcYI-4/maxresdefault.jpg')"></lite-youtube>
    </div>    
</div>


<div class="relative bg-white py-4 mt-12">
    <div class="mx-auto max-w-md px-4 text-center sm:max-w-3xl sm:px-6 lg:max-w-7xl lg:px-8">
        <p class="mt-2 text-3xl font-extrabold tracking-tight text-gray-900 dark:text-gray-50 sm:text-4xl">Blazor Components</p>
        <p class="mx-auto mt-5 max-w-prose text-xl text-gray-500"> 
            Rich, themable UI Component Library with declarative contextual Validation
        </p>
    </div>
</div>

To maximize productivity the template utilizes the **ServiceStack.Blazor** library containing integrated functionality for Blazor including an optimal JSON API HttpClient Factory, API-enabled base components and a rich library of Tailwind & Bootstrap UI Input components with integrated contextual validation support 
of ServiceStack's [structured Error responses](/error-handling) heavily utilized throughout each project template.

### Blazor Tailwind UI Components

The Built-in UI Components enable a clean & productive dev model, which as of this release include:

| Component         | Description                                                                       |
|-------------------|-----------------------------------------------------------------------------------|
| `<TextInput>`     | Text Input control for string properties                                          |
| `<DateTimeInput>` | Date Input control for Date properties                                            |
| `<CheckboxInput>` | Checkbox Input control for Boolean properties                                     |
| `<SelectInput>`   | Select Dropdown for properties with finite list of values like Enums              |
| `<TextAreaInput>` | Text Input control for large strings                                              |
| `<DynamicInput>`  | Dynamic component utilizing the appropriate above Input controls in Auto Forms    |
| `<AlertSuccess>`  | Displaying successful notification feedback                                       |
| `<ErrorSummary>`  | Displaying error summary message when no contextual field validation is available |
| `<FileUpload>`    | Used with `FilesUploadFeature` and `UploadTo` attribute to upload files           |


The Tailwind & Bootstrap components share the same functionally equivalent base classes that can be easily swapped when switching CSS frameworks by updating its namespace in your App's `_Imports.razor`.

```csharp
@using ServiceStack.Blazor.Components.Tailwind
//@using ServiceStack.Blazor.Components.Bootstrap
```

#### Themable 

Should it be needed, their decoupled design also allows easy customization by running the included [README.ss](https://github.com/LegacyTemplates/blazor-wasm/blob/main/MyApp.Client/Shared/Components/README.ss) executable documentation to copy each controls **Razor** UI markup locally into your project, enabling easy customization of all UI input controls.

### Bookings CRUD Example

To demonstrate ServiceStack's clean & highly productive Blazor dev model, we'll walk through implementing the [AutoQuery Bookings CRUD](/autoquery/crud-bookings) example in Blazor.

Since we're using [AutoQuery CRUD](/autoquery/crud) we only need to define the Request DTO with the input fields we want the user to populate in our `Booking` RDBMS table in [Bookings.cs](https://github.com/NetCoreTemplates/blazor/blob/main/MyApp.ServiceModel/Bookings.cs):

```csharp
[Tag("bookings"), Description("Create a new Booking")]
[Route("/bookings", "POST")]
[ValidateHasRole("Employee")]
[AutoApply(Behavior.AuditCreate)]
public class CreateBooking : ICreateDb<Booking>, IReturn<IdResponse>
{
    [Description("Name this Booking is for"), ValidateNotEmpty]
    public string Name { get; set; }
    public RoomType RoomType { get; set; }
    [ValidateGreaterThan(0)]
    public int RoomNumber { get; set; }
    [ValidateGreaterThan(0)]
    public decimal Cost { get; set; }
    public DateTime BookingStartDate { get; set; }
    public DateTime? BookingEndDate { get; set; }
    [Input(Type = "textarea")]
    public string? Notes { get; set; }
}
```

Where we make use of [Declarative Validation](/declarative-validation) attributes to define the custom validation rules for this API.

::: tip
The `[Tag]`, `[Description]` and `[Input]` attributes are optional to markup how this API appears in ServiceStack's built-in [API Explorer](/api-explorer.html#details-tab) and [Locode UIs](/locode/declarative)
:::

### Blazor WASM App

Thanks to ServiceStack's [Recommended Project Structure](/physical-project-structure) no any additional classes are needed as we're able to bind UI Controls directly to our typed server `CreateBooking` Request DTO used to define the API in 
[BookingsCrud/Create.razor](https://github.com/LegacyTemplates/blazor-wasm/blob/main/MyApp.Client/Pages/BookingsCrud/Create.razor):

```csharp
<form @onsubmit="_ => OnSubmit()" @onsubmit:preventDefault>
<CascadingValue Value=@api.Error>
<div class=@CssUtils.ClassNames("shadow overflow-hidden sm:rounded-md bg-white", @class)>
    <div class="relative px-4 py-5 bg-white sm:p-6">
        <CloseButton OnClose="close" />
        <fieldset>
            <legend class="text-base font-medium text-gray-900 text-center mb-4">New Booking</legend>

            <ErrorSummary Except=@VisibleFields />

            <div class="grid grid-cols-6 gap-6">
                <div class="col-span-6 sm:col-span-3">
                    <TextInput @bind-Value="request.Name" required placeholder="Name for this booking" />
                </div>

                <div class="col-span-6 sm:col-span-3">
                    <SelectInput @bind-Value="request.RoomType" Options=@(Enum.GetValues<RoomType>()) /> 
                </div>

                <div class="col-span-6 sm:col-span-3">
                    <TextInput type="number" @bind-Value="request.RoomNumber" min="0" required />
                </div>

                <div class="col-span-6 sm:col-span-3">
                    <TextInput type="number" @bind-Value="request.Cost" min="0" required />
                </div>

                <div class="col-span-6 sm:col-span-3">
                    <DateTimeInput @bind-Value="request.BookingStartDate" required />
                </div>
                <div class="col-span-6 sm:col-span-3">
                    <DateTimeInput @bind-Value="request.BookingEndDate" />
                </div>
    
                <div class="col-span-6">
                    <TextAreaInput @bind-Value="request.Notes" placeholder="Notes about this booking" />
                </div>
            </div>
        </fieldset>
    </div>
</div>
</CascadingValue>
</form>

@code {
    [Parameter] public EventCallback<IdResponse> done { get; set; }
    [Parameter] public string? @class { get; set; }

    CreateBooking request = new() {
        BookingStartDate = DateTime.UtcNow,
    };

    // Hide Error Summary Messages for Visible Fields which displays contextual validation errors
    string[] VisibleFields => new[] {
        nameof(request.Name), 
        nameof(request.RoomType), 
        nameof(request.RoomNumber), 
        nameof(request.BookingStartDate),
        nameof(request.BookingEndDate), 
        nameof(request.Cost), 
        nameof(request.Notes),
    };

    ApiResult<IdResponse> api = new();

    async Task OnSubmit()
    {
        api = await ApiAsync(request);

        if (api.Succeeded)
        {
            await done.InvokeAsync(api.Response!);
            request = new();
        }
    }

    async Task close() => await done.InvokeAsync(null);
}
```

Calling ServiceStack APIs requires no additional code-gen or boilerplate where the populated Request DTO can be sent as-is using the
[JsonApiClient Api methods](/csharp-client#high-level-api-and-apiasync-methods) which returns an encapsulated successful API or structured error response 
in its typed `ApiResult<T>`.

The UI validation binding uses Blazor's `<CascadingValue>` to propagate any `api.error` responses down to the child Input components.

That's all there's to it, we use [Tailwind's CSS Grid classes](https://tailwindcss.com/docs/grid-template-columns) to define our UI layout which shows each control in its own row for mobile UIs or 2 fields per row in resolutions larger than the [Tailwind's sm: responsive breakpoint](https://tailwindcss.com/docs/responsive-design) to render our beautiful Bookings Form:

<div class="mx-auto max-w-screen-md text-center py-8">
    <img src="/img/pages/blazor/bookings-create.png">
</div>

Which utilizes both client and server validation upon form submission, displaying UX friendly contextual errors under each field when they violate any server [declarative validation](/declarative-validation) or Client UI **required** rules:

<div class="mx-auto max-w-screen-md text-center py-8">
        <img src="/img/pages/blazor/bookings-create-validation.png">
</div>

## Optimal Development Workflow

Utilizing Blazor WebAssembly (WASM) with a ServiceStack backend yields an optimal frictionless [API First development model](/api-first-development) where UIs can bind directly to Typed DTOs whilst benefiting from ServiceStack's [structured error handling](/validation) & rich contextual form validation binding.

By utilizing ServiceStack's [decoupled project structure](/physical-project-structure), combined with Blazor enabling C# on the client, we're able to get 100% reuse of your APIs shared DTOs as-is to enable an end-to-end Typed API automatically free from any additional tooling or code-gen complexity.

<lite-youtube class="w-full mx-4 my-4" width="560" height="315" videoid="BcQqCzm4tK0" style="background-image: url('https://img.youtube.com/vi/BcQqCzm4tK0/maxresdefault.jpg')"></lite-youtube>

## Api and ApiAsync methods

.NET was originally conceived to use Exceptions for error control flow however there's been a tendency in modern languages & libraries to shun Exceptions and return errors as normal values, an approach we believe is a more flexible & ergonomic way to handle API responses.

### The ApiResult way

The `Api(Request)` and `ApiAsync(Request)` APIs returns a typed `ApiResult<Response>` Value Result encapsulating either a Typed Response or a structured API Error populated in `ResponseStatus` allowing you to handle API responses programmatically without `try/catch` handling:

The below example code to create a new Booking:

```csharp
CreateBooking request = new();

ApiResult<IdResponse> api = new();

async Task OnSubmit()
{
    api = await Client.ApiAsync(request);

    if (api.Succeeded)
    {
        await done.InvokeAsync(api.Response!);
        request = new();
    }
}
```

Which despite its terseness handles both **success** and **error** API responses, **if successful** it invokes the `done()` callback notifying its parent of the new Booking API Response before resetting the Form's data model with a new Request DTO.

Upon **failure** the error response is populated in `api.Error` which binds to the UI via Blazor's `<CascadingValue Value=@api.Error>` to propagate it to all its child components in order to show contextual validation errors next to their respective Input controls.

## JSON API Client

The recommended way for configuring a Service Client to use in your Blazor WASM Apps is to use `AddBlazorApiClient()`, e.g:

```csharp
builder.Services.AddBlazorApiClient(builder.Configuration["ApiBaseUrl"] ?? builder.HostEnvironment.BaseAddress);
```

Which registers a typed Http Client factory returning a recommended pre-configured `JsonApiClient` to communicate with your back-end ServiceStack APIs including support for CORS, required when hosting the decoupled UI on a different server (e.g. CDN) to your server. 

If you're deploying your Blazor WASM UI to a CDN you'll need to specify the URL for the server, otherwise if it's deployed together with your Server App you can use the Host's Base Address.

### Public Pages & Components

To reduce boiler plate, your Blazor Pages & components can inherit the templates local [AppComponentBase.cs](https://github.com/NetCoreTemplates/blazor-wasm/blob/main/MyApp.Client/AppComponentBase.cs) which inherits `BlazorComponentBase` which gets injected with the `JsonApiClient` and provides short-hand access to its most common APIs:

```csharp
public class BlazorComponentBase : ComponentBase, IHasJsonApiClient
{
    [Inject]
    public JsonApiClient? Client { get; set; }

    public virtual Task<ApiResult<TResponse>> ApiAsync<TResponse>(IReturn<TResponse> request)  => Client!.ApiAsync(this, request);
    public virtual Task<ApiResult<EmptyResponse>> ApiAsync(IReturnVoid request) => Client!.ApiAsync(this, request);
    public virtual Task<TResponse> SendAsync<TResponse>(IReturn<TResponse> request) => Client!.SendAsync(this, request);
}
```

### Protected Pages & Components

Pages and Components requiring Authentication should inherit from [AppAuthComponentBase](https://github.com/NetCoreTemplates/blazor-wasm/blob/main/MyApp.Client/AppComponentBase.cs) instead which integrates with Blazor's Authentication Model to provide access to the currently authenticated user:

```csharp
public abstract class AppAuthComponentBase : AppComponentBase
{
    [CascadingParameter]
    protected Task<AuthenticationState>? AuthenticationStateTask { get; set; }

    protected bool HasInit { get; set; }

    protected bool IsAuthenticated => User?.Identity?.IsAuthenticated ?? false;

    protected ClaimsPrincipal? User { get; set; }

    protected override async Task OnParametersSetAsync()
    {
        var state = await AuthenticationStateTask!;
        User = state.User;
        HasInit = true;
    }
}
```

## Benefits of Shared DTOs

Typically with Web Apps, our client is using a different language to C#, so an equivalent request DTOs need to be generated for the client.

### TypeScript Example

For example, TypeScript generated DTOs still give us typed end-to-end services with the help of tooling like [Add ServiceStack Reference](/add-servicestack-reference)

```csharp
[Route("/hello/{Name}")]
public class Hello : IReturn<HelloResponse>
{
    public string Name { get; set; }
}

public class HelloResponse
{
    public string Result { get; set; }
}
```

Turns into:

```typescript
// @Route("/hello/{Name}")
export class Hello implements IReturn<HelloResponse>
{
    public name: string;

    public constructor(init?: Partial<Hello>) { (Object as any).assign(this, init); }
    public getTypeName() { return 'Hello'; }
    public getMethod() { return 'POST'; }
    public createResponse() { return new HelloResponse(); }
}

export class HelloResponse
{
    public result: string;
    public responseStatus: ResponseStatus;

    public constructor(init?: Partial<HelloResponse>) { (Object as any).assign(this, init); }
}
```

When Request or Response DTOs changes during development, the client DTOs need to be regenerated using a command like [`x csharp`](./add-servicestack-reference.md#simple-command-line-utilities).

### Blazor WASM Example

Developing your Blazor WASM UI however, you just change your shared request/response DTO in the shared `ServiceModel` project, and both your client and server compile against the same request/response DTO classes.
This eliminates the need for any additional step.

In the `ServiceModel` project, we still have:

```csharp
[Route("/hello/{Name}")]
public class Hello : IReturn<HelloResponse>
{
    public string Name { get; set; }
}

public class HelloResponse
{
    public string Result { get; set; }
}
```

Which the Blazor C# App can use directly in its **.razor** pages:

```csharp
@code {
    Hello request = new()
    {
        Name = "Blazor WASM"
    };

    ApiResult<HelloResponse> api = new();

    protected override async Task OnInitializedAsync() => await submit();

    async Task submit() => api = await ApiAsync(request);
}
```

### FileUpload Control

The File Upload UI component used in the [File Blazor Demo](/locode/files-blazor) has been extracted into a reusable Blazor component you can utilize in your own apps:

![](/img/pages/templates/fileupload-blazor-usage-example.png)

It's a simple control that takes advantage of ServiceStack's declarative [Managed File Uploads](/locode/files-overview) support to effortlessly enable multiple file uploads that can be declaratively added to any Request DTO, which only requires setting 2 properties:

| Property         | Description                                                                                        |
|------------------|----------------------------------------------------------------------------------------------------|
| Request          | Request DTO object instance populated with into to be sent to your endpoint                        |
| FilePropertyName | The name of the property that is used to reference your file, used with the `[UploadTo]` attribute |

#### Example usage

Below is an AutoQuery CRUD API example that references an upload location defined when configuring the [FileUploadFeature Plugin](/locode/files-upload-filesystem.md):

```csharp
public class CreateMyDtoWithFileUpload : ICreateDb<MyDtoWithFileUpload>, IReturn<IdResponse>
{
    [Input(Type="file"), UploadTo("fs")]
    public string FilePath { get; set; }
    
    public string OtherData { get; set; }
}

public class QueryFileUpload : QueryDb<MyDtoWithFileUpload> {}

public class MyDtoWithFileUpload
{
    [AutoIncrement]
    public int Id { get; set; }
    
    public string FilePath { get; set; }
    
    public string OtherData { get; set; }
}
```

When calling this API, the Managed File Uploads feature will upload the HTTP File Upload included in the API request to the configured **fs** upload location and populate the uploaded path to the `FilePath` Request DTO property. 

The Blazor `FileUpload` Control handles the [C# File Upload API Request](/locode/files.html#uploading-files-from-c) by providing the Request DTO instance to send and the DTO property the File Upload should populate:

```html
@page "/file-upload"
<h3>FileUploadPage</h3>

<FileUpload Request="request" FilePropertyName="@nameof(CreateMyDtoWithFileUpload.FilePath)" />

@code {

    // Any additional values should be populated 
    // on the request object before the upload starts.
    CreateMyDtoWithFileUpload request = new() {
        OtherData = "Test"
    };
}
```

![](/img/pages/templates/fileupload-blazor-example.png)

The `FilePropertyName` matches the property name that is annotated by the `UploadTo` attribute. The `Request` is the instance of the Request DTO.

### Existing Template Upgrade for 6.3

If you created a `blazor-tailwind` project using this template before the ServiceStack 6.4 release, you should run the following commands to upgrade your project to use components from `ServiceStack.Blazor` component library which should be run from your `.Client` project:

::: sh
x mix -delete blazor-upgrade-clean
:::

::: sh
x mix blazor-upgrade
:::


# Blazor Tailwind Components
Source: https://docs.servicestack.net/templates/blazor-components

ServiceStack.Blazor high-productivity components enable rapid development in Blazor Server and WASM Apps:

<div class="my-8 flex justify-center">
    <lite-youtube class="w-full mx-4 my-4" width="560" height="315" videoid="iKpQI2233nY" style="background-image: url('https://img.youtube.com/vi/iKpQI2233nY/maxresdefault.jpg')"></lite-youtube>
</div>

<div id="blazor-component-gallery" class="not-prose mt-16 relative bg-white dark:bg-black py-4">
  <div class="mx-auto max-w-md px-4 text-center sm:max-w-3xl sm:px-6 lg:max-w-7xl lg:px-8">
    <p class="mt-2 text-3xl font-extrabold tracking-tight text-gray-900 dark:text-gray-50 sm:text-4xl">Blazor Gallery</p>
    <p class="mx-auto mt-5 max-w-prose text-xl text-gray-500">
      Discover ServiceStack.Blazor Rich UI Components and Integrated Features
    </p>
  </div>
</div>

[![](/img/pages/blazor/gallery-splash.png)](https://blazor-gallery.servicestack.net)

As our components support both hosting models we're maintaining identical Gallery sites running on both **Blazor Server** and **WASM**:

<div class="not-prose mb-16 mx-auto mt-5 max-w-md sm:flex sm:justify-center md:mt-8">
  <div class="rounded-md shadow">
    <a href="https://blazor-gallery.servicestack.net" class="flex w-full items-center justify-center rounded-md border border-transparent bg-indigo-600 px-8 py-3 text-base font-medium text-white hover:bg-indigo-700 md:py-4 md:px-10 md:text-lg hover:no-underline">
      Blazor Server
    </a>
  </div>
  <div class="mt-3 rounded-md shadow sm:mt-0 sm:ml-3">
    <a href="https://blazor-gallery.jamstacks.net" class="flex w-full items-center justify-center rounded-md border border-transparent bg-white px-8 py-3 text-base font-medium text-indigo-600 hover:bg-gray-50 md:py-4 md:px-10 md:text-lg hover:no-underline">
      Blazor WASM
    </a>
  </div>
</div>

For a closer look at ServiceStack.Blazor Components in action, download & run them to see how good they'll run in your Environment:

<div class="flex flex-col">
  <a href="https://github.com/NetCoreApps/BlazorGallery" class="flex text-xl text-gray-800">
    <svg class="w-6 h-6 mr-2 align-text-bottom" xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24"><path fill="currentColor" d="M12 .297c-6.63 0-12 5.373-12 12c0 5.303 3.438 9.8 8.205 11.385c.6.113.82-.258.82-.577c0-.285-.01-1.04-.015-2.04c-3.338.724-4.042-1.61-4.042-1.61C4.422 18.07 3.633 17.7 3.633 17.7c-1.087-.744.084-.729.084-.729c1.205.084 1.838 1.236 1.838 1.236c1.07 1.835 2.809 1.305 3.495.998c.108-.776.417-1.305.76-1.605c-2.665-.3-5.466-1.332-5.466-5.93c0-1.31.465-2.38 1.235-3.22c-.135-.303-.54-1.523.105-3.176c0 0 1.005-.322 3.3 1.23c.96-.267 1.98-.399 3-.405c1.02.006 2.04.138 3 .405c2.28-1.552 3.285-1.23 3.285-1.23c.645 1.653.24 2.873.12 3.176c.765.84 1.23 1.91 1.23 3.22c0 4.61-2.805 5.625-5.475 5.92c.42.36.81 1.096.81 2.22c0 1.606-.015 2.896-.015 3.286c0 .315.21.69.825.57C20.565 22.092 24 17.592 24 12.297c0-6.627-5.373-12-12-12"/></svg>
    <span>NetCoreApps/BlazorGallery</span>
  </a>
  <a href="https://github.com/NetCoreApps/BlazorGalleryWasm" class="flex mt-2 text-xl text-gray-800">
    <svg class="w-6 h-6 mr-2 align-text-bottom" xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24"><path fill="currentColor" d="M12 .297c-6.63 0-12 5.373-12 12c0 5.303 3.438 9.8 8.205 11.385c.6.113.82-.258.82-.577c0-.285-.01-1.04-.015-2.04c-3.338.724-4.042-1.61-4.042-1.61C4.422 18.07 3.633 17.7 3.633 17.7c-1.087-.744.084-.729.084-.729c1.205.084 1.838 1.236 1.838 1.236c1.07 1.835 2.809 1.305 3.495.998c.108-.776.417-1.305.76-1.605c-2.665-.3-5.466-1.332-5.466-5.93c0-1.31.465-2.38 1.235-3.22c-.135-.303-.54-1.523.105-3.176c0 0 1.005-.322 3.3 1.23c.96-.267 1.98-.399 3-.405c1.02.006 2.04.138 3 .405c2.28-1.552 3.285-1.23 3.285-1.23c.645 1.653.24 2.873.12 3.176c.765.84 1.23 1.91 1.23 3.22c0 4.61-2.805 5.625-5.475 5.92c.42.36.81 1.096.81 2.22c0 1.606-.015 2.896-.015 3.286c0 .315.21.69.825.57C20.565 22.092 24 17.592 24 12.297c0-6.627-5.373-12-12-12"/></svg>
    <span>NetCoreApps/BlazorGalleryWasm</span>
  </a>
</div>

<div class="not-prose pt-8 my-8 ml-20 flex flex-col items-center">
    <div>
        <svg class="w-40 h-40 text-gray-800 mr-8" xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24"><path fill="currentColor" d="M9.37 5.51A7.35 7.35 0 0 0 9.1 7.5c0 4.08 3.32 7.4 7.4 7.4c.68 0 1.35-.09 1.99-.27A7.014 7.014 0 0 1 12 19c-3.86 0-7-3.14-7-7c0-2.93 1.81-5.45 4.37-6.49zM12 3a9 9 0 1 0 9 9c0-.46-.04-.92-.1-1.36a5.389 5.389 0 0 1-4.4 2.26a5.403 5.403 0 0 1-3.14-9.8c-.44-.06-.9-.1-1.36-.1z"/></svg>
    </div>
    <h2 id="darkmode" class="border-none text-4xl sm:text-5xl md:text-6xl tracking-tight font-extrabold">
        <span class="text-gray-800 mr-6">Dark Mode</span>
    </h2>
</div>

All ServiceStack.Blazor components take advantage of Tailwind DarkMode support to include full support for Dark Mode.

![](/img/pages/blazor/dark-and-light-mode.png)

[Tailwind](https://tailwindcss.com) has revolutionized how we style our Web Apps with its [mobile first](https://tailwindcss.com/#mobile-first) design system that's dramatically simplified creating maintainable responsive Web Apps. It also excels at adding support for [Dark Mode](https://tailwindcss.com/#dark-mode) with its first-class **dark:** modifier allowing the use of standard tailwind classes to specify what elements should look like when viewed in **Dark Mode**, e.g:

<div class="not-prose relative bg-slate-50 rounded-xl overflow-hidden dark:bg-slate-800/25"><div style="background-position:10px 10px" class="absolute inset-0 bg-grid-slate-100 [mask-image:linear-gradient(0deg,#fff,rgba(255,255,255,0.6))] dark:bg-grid-slate-700/25 dark:[mask-image:linear-gradient(0deg,rgba(255,255,255,0.1),rgba(255,255,255,0.5))]"></div><div class="relative rounded-xl overflow-auto">
  <div class="grid grid-cols-1 sm:grid-cols-2">
    <div class="p-8 pt-7">
      <p class="mb-2 text-sm font-medium text-slate-500">Light mode</p>
      <div class="bg-white rounded-lg px-6 py-8 ring-1 ring-slate-900/5 shadow-xl">
        <div>
          <span class="inline-flex items-center justify-center p-2 bg-indigo-500 rounded-md shadow-lg">
            <svg class="h-6 w-6 text-white" xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke="currentColor" aria-hidden="true">
              <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M11 5H6a2 2 0 00-2 2v11a2 2 0 002 2h11a2 2 0 002-2v-5m-1.414-9.414a2 2 0 112.828 2.828L11.828 15H9v-2.828l8.586-8.586z"></path></svg>
          </span>
        </div>
        <h3 class="mt-5 text-base font-medium text-slate-900 tracking-tight">Writes Upside-Down</h3>
        <p class="mt-2 text-sm text-slate-500">
          The Zero Gravity Pen can be used to write in any orientation, including upside-down. It even works in outer space.
        </p>
      </div>
    </div>
    <div class="bg-slate-900 p-8 pt-7">
      <p class="mb-2 text-sm font-medium text-slate-400">Dark mode</p>
      <div class="bg-slate-800 rounded-lg px-6 py-8 ring-1 ring-slate-900/5 shadow-xl">
        <div>
          <span class="inline-flex items-center justify-center p-2 bg-indigo-500 rounded-md shadow-lg">
            <svg class="h-6 w-6 text-white" xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke="currentColor" aria-hidden="true">
              <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M11 5H6a2 2 0 00-2 2v11a2 2 0 002 2h11a2 2 0 002-2v-5m-1.414-9.414a2 2 0 112.828 2.828L11.828 15H9v-2.828l8.586-8.586z"></path></svg>
          </span>
        </div>
        <h3 class="mt-5 text-base font-medium text-white tracking-tight">Writes Upside-Down</h3>
        <p class="mt-2 text-sm text-slate-400">
          The Zero Gravity Pen can be used to write in any orientation, including upside-down. It even works in outer space.
        </p>
      </div>
    </div>
  </div>
</div><div class="absolute inset-0 pointer-events-none border border-black/5 rounded-xl dark:border-white/5"></div></div>

```html
<div class="bg-white dark:bg-slate-800 rounded-lg px-6 py-8 ring-1 ring-slate-900/5 shadow-xl">
  <div>
    <span class="inline-flex items-center justify-center p-2 bg-indigo-500 rounded-md shadow-lg">
      <svg class="h-6 w-6 text-white" xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke="currentColor" aria-hidden="true"><!-- ... --></svg>
    </span>
  </div>
  <h3 class="text-slate-900 dark:text-white mt-5 text-base font-medium tracking-tight">Writes Upside-Down</h3>
  <p class="text-slate-500 dark:text-slate-400 mt-2 text-sm">
    The Zero Gravity Pen can be used to write in any orientation, including upside-down. It even works in outer space.
  </p>
</div>
```

### View ServiceStack.Blazor in Dark Mode

We're happy to announce that Dark Mode support is included in **all ServiceStack.Blazor components** and all Blazor Tailwind project templates where you'll be able to toggle on/off Dark Mode with the new `<DarkModeToggle>` component. Checkout this video to see how beautiful Dark Mode looks like in the latest ServiceStack.Blazor Components and Tailwind project templates:

<div class="my-8 flex justify-center">
    <lite-youtube class="w-full mx-4 my-4" width="560" height="315" videoid="8nwpC_B4AC4" style="background-image: url('https://img.youtube.com/vi/8nwpC_B4AC4/maxresdefault.jpg')"></lite-youtube>
</div>

For a more interactive view, use the right Dark Mode toggle to turn on/off Dark Mode in the embedded [Blazor Gallery Contacts Page](https://blazor-gallery.jamstacks.net/grid/contacts-meta):

<iframe src="https://blazor-gallery.jamstacks.net/grid/contacts-meta/embed" class="w-full border-none h-[970px]"></iframe>

Dark Mode is all implemented with CSS, controlled by toggling the **dark** class on the `<html class="dark">` element, `<DarkModeToggle>` also saves this user preference in `localStorage` where it's preserved across browser restarts.

### View in Dark Mode

The Blazor Tailwind templates also include the ability to override the users color scheme preference and open a page in dark or light mode with the 
`?dark` and `?light` query params:

<div class="not-prose relative">
  <div class="grid grid-cols-1 sm:grid-cols-2 text-center">
    <div>
        <a class="flex flex-col" href="https://blazor.web-templates.io/?light">
            <div class="py-4">blazor.web-templates.io/?light</div>
            <img class="rounded-xl overflow-hidden" src="/img/pages/blazor/blazor-gallery-light.png">
        </a>
    </div>
    <div>
        <a class="flex flex-col" href="https://blazor.web-templates.io/?dark">
            <div class="py-4">blazor.web-templates.io/?dark</div>
            <img class="rounded-xl overflow-hidden" src="/img/pages/blazor/blazor-gallery-dark.png">
        </a>
    </div>
  </div>
</div>

### Force Dark Mode

If your App is best viewed in Dark Mode you can force it to use Dark Mode with `JS.init()` when initializing ServiceStack.Blazor's JS library in Blazor Server's **_Layout.cshtml** or Blazor WASM's **index.html**, e.g:

```html
<script src="_framework/blazor.server.js"></script>
<script src="/js/servicestack-blazor.js"></script>
<script>JS.init({ colorScheme:'dark' })</script>
```

<p class="hide-h2"></p>

## Blazor Tailwind Components

<div id="blazor-components" class="not-prose mt-16 mb-8 ml-20 flex flex-col items-center">
    <div class="flex">
        <svg class="w-40 h-40 text-purple-600 mr-8" xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24"><path fill="currentColor" d="M23.834 8.101a13.912 13.912 0 0 1-13.643 11.72a10.105 10.105 0 0 1-1.994-.12a6.111 6.111 0 0 1-5.082-5.761a5.934 5.934 0 0 1 11.867-.084c.025.983-.401 1.846-1.277 1.871c-.936 0-1.374-.668-1.374-1.567v-2.5a1.531 1.531 0 0 0-1.52-1.533H8.715a3.648 3.648 0 1 0 2.695 6.08l.073-.11l.074.121a2.58 2.58 0 0 0 2.2 1.048a2.909 2.909 0 0 0 2.695-3.04a7.912 7.912 0 0 0-.217-1.933a7.404 7.404 0 0 0-14.64 1.603a7.497 7.497 0 0 0 7.308 7.405s.549.05 1.167.035a15.803 15.803 0 0 0 8.475-2.528c.036-.025.072.025.048.061a12.44 12.44 0 0 1-9.69 3.963a8.744 8.744 0 0 1-8.9-8.972a9.049 9.049 0 0 1 3.635-7.247a8.863 8.863 0 0 1 5.229-1.726h2.813a7.915 7.915 0 0 0 5.839-2.578a.11.11 0 0 1 .059-.034a.112.112 0 0 1 .12.053a.113.113 0 0 1 .015.067a7.934 7.934 0 0 1-1.227 3.549a.107.107 0 0 0-.014.06a.11.11 0 0 0 .073.095a.109.109 0 0 0 .062.004a8.505 8.505 0 0 0 5.913-4.876a.155.155 0 0 1 .055-.053a.15.15 0 0 1 .147 0a.153.153 0 0 1 .054.053A10.779 10.779 0 0 1 23.834 8.1zM8.895 11.628a2.188 2.188 0 1 0 2.188 2.188v-2.042a.158.158 0 0 0-.15-.15Z"/></svg>
        <svg class="w-44 h-44" xmlns="http://www.w3.org/2000/svg" width="256" height="154" viewBox="0 0 256 154"><defs><linearGradient id="logosTailwindcssIcon0" x1="-2.778%" x2="100%" y1="32%" y2="67.556%"><stop offset="0%" stop-color="#2298BD"/><stop offset="100%" stop-color="#0ED7B5"/></linearGradient></defs><path fill="url(#logosTailwindcssIcon0)" d="M128 0C93.867 0 72.533 17.067 64 51.2C76.8 34.133 91.733 27.733 108.8 32c9.737 2.434 16.697 9.499 24.401 17.318C145.751 62.057 160.275 76.8 192 76.8c34.133 0 55.467-17.067 64-51.2c-12.8 17.067-27.733 23.467-44.8 19.2c-9.737-2.434-16.697-9.499-24.401-17.318C174.249 14.743 159.725 0 128 0ZM64 76.8C29.867 76.8 8.533 93.867 0 128c12.8-17.067 27.733-23.467 44.8-19.2c9.737 2.434 16.697 9.499 24.401 17.318C81.751 138.857 96.275 153.6 128 153.6c34.133 0 55.467-17.067 64-51.2c-12.8 17.067-27.733 23.467-44.8 19.2c-9.737-2.434-16.697-9.499-24.401-17.318C110.249 91.543 95.725 76.8 64 76.8Z"/></svg>
    </div>
    <h2 class="border-none text-4xl sm:text-5xl md:text-6xl tracking-tight font-extrabold">
        <span class="text-purple-600 mr-6">Blazor</span>
        <span class="mr-6" style="color:#44A8B3">Tailwind</span>
        <span class="text-gray-800">Components</span>
    </h2>
</div>

We encourage you to explore to the Blazor Gallery websites for the full preview, but we'll look at some of the Components here to give you some idea of the functionality available.

### DataGrid

`DataGrid` is a versatile Component we expect to be heavily used for rendering any typed collection:

```html
<DataGrid Model="Track" Items=@Track.Results />
```

Which by default renders results in a striped Tailwind Table:

![](/img/pages/blazor/datagrid-tracks.png)

Whose appearance can be styled to support many of the [Tailwind Table Styles](https://tailwindui.com/components/application-ui/lists/tables) with the `TableStyles` Flag enum, e.g:

```html
<DataGrid Model="Track" Items=@Track.Results TableStyle="TableStyle.VerticalLines" />

<DataGrid Model="Track" Items=@Track.Results TableStyle="TableStyle.WhiteBackground" />

<DataGrid Model="Track" Items=@Track.Results TableStyle="TableStyle.FullWidth" />

<DataGrid Model="Track" Items=@Track.Results 
          TableStyle="TableStyle.UppercaseHeadings | TableStyle.FullWidth | TableStyle.VerticalLines" />
```

![](/img/pages/blazor/datagrid-table-styles.png)

It's a highly versatile component where you'll be able to control which columns are displayed and how they're formatted using `<Column>` definitions, e.g. here's how we can customize the table to look like Blazor's [FetchData.cshtml](https://github.com/SteveSanderson/Blazor/blob/master/samples/ClientServerApp/ClientServerApp.Client/FetchData.cshtml) tabular results:

```html
<DataGrid Items=@forecasts class="max-w-screen-md" TableStyle="TableStyle.StripedRows | TableStyle.UppercaseHeadings">
    <Column Field="(WeatherForecast x) => x.Date" Format="dd/MM/yyyy" />
    <Column Title="Temp. (C)" Field="(WeatherForecast x) => x.TemperatureC" />
    <Column Title="Temp. (F)" Field="(WeatherForecast x) => x.TemperatureF" />
    <Column Field="(WeatherForecast x) => x.Summary" />
</DataGrid>

@code {
    List<WeatherForecast> forecasts = new();

    protected override async Task OnInitializedAsync()
    {
        forecasts = await Http.GetFromJsonAsync<List<WeatherForecast>>("data/weather.json") ?? new();
    }
}
```

[![](/img/pages/blazor/datagrid-weather.png)](https://blazor-gallery.servicestack.net/fetchdata)


Here's a more advanced example showing how to implement a responsive DataGrid by utilizing custom Header and Table Cell templates to define what columns and Headers are visible at different responsive breakpoints and how to enable different features like **Row Selection** and **Filtering** and examples of handling the Row and Header selected events App's can use for executing custom logic:

```html
<DataGrid Model="Booking" Items=@Items AllowSelection="true" AllowFiltering="true"
          HeaderSelected="HandleSelectedHeader" RowSelected="HandleSelectedRow">
    <Column Field="(Booking x) => x.Id" class="text-gray-900" />
    <Column Field="(Booking x) => x.Name" VisibleFrom="Breakpoint.ExtraLarge" />
    <Column Field="(Booking x) => x.RoomType">
        <Header>
            <span class="hidden lg:inline">Room </span>Type
        </Header>
    </Column>
    <Column Field="(Booking x) => x.RoomNumber">
        <Header>
            <span class="hidden lg:inline">Room </span>No
        </Header>
    </Column>
    <Column Field="(Booking x) => x.Cost" Format="C" />
    <Column Field="(Booking x) => x.BookingStartDate" Formatter="FormatDate" VisibleFrom="Breakpoint.Small">
        <Header>
            Start<span class="hidden lg:inline"> Date</span>
        </Header>
    </Column>
    <Column Field="(Booking x) => x.BookingEndDate" Formatter="FormatDate" VisibleFrom="Breakpoint.ExtraLarge">
        <Header>
            End<span class="hidden lg:inline"> Date</span>
        </Header>
        <Template>@{ var booking = context as Booking; }@booking.BookingEndDate?.ToString("D")
        </Template>
    </Column>
    <Column Title="Employee" Field="(Booking x) => x.CreatedBy" VisibleFrom="Breakpoint.Medium" />
</DataGrid>

@code {
    public List<Booking> Items { get; set; } = new() {
        Create.Booking("First Booking!",  RoomType.Queen,  10, 100, "employee@email.com", "BOOK10"),
        Create.Booking("Booking 2",       RoomType.Double, 12, 120, "manager@email.com",  "BOOK25"),
        Create.Booking("Booking the 3rd", RoomType.Suite,  13, 130, "employee@email.com", "BOOK50"),
    };

    string FormatDate(object o) => o is DateTime d ? d.ToShortDateString() : "";

    public async Task HandleSelectedHeader(Column<Booking> item)
    {
        await JS.Log(item.Name);
    }

    public async Task HandleSelectedRow(Booking x)
    {
        await JS.Log(x);
    }
}
```

:::tip
Resize webpage to preview its responsive appearance and different resolution breakpoints
:::

<iframe class="w-full border-none" style="height:385px" src="https://blazor-gallery.jamstacks.net/gallery/datagrid/responsive"></iframe>

### AutoQueryGrid

The functionality and extensibility in `DataGrid` lays the foundation for higher-level components like `AutoQueryGrid` which makes use of it to enable its Auto UI around [AutoQuery CRUD](/autoquery/crud) Services. 

### AutoQueryGrid Read Only

At a minimum AutoQueryGrid requires the AutoQuery APIs it should call to implement its functionality, so you can implement a **read-only** grid by only
specifying the AutoQuery API to query a data model, e.g:

```csharp
<AutoQueryGrid Model="Booking" Apis="Apis.AutoQuery<QueryBookings>()" />
```

This one AutoQuery API is enough to power a functional read-only UI enabling multi flexible querying capabilities, paging, custom column selection and the ability to export the desired filtered resultset to .csv which can be open in Excel or copy the API URL Apps can use to consume the JSON API results:

<iframe class="w-full border-none" style="height:430px" src="https://blazor-gallery.jamstacks.net/gallery/autoquerygrid/readonly"></iframe>

### AutoQueryGrid CRUD

Full CRUD functionality can be enabled by specifying the AutoQuery CRUD APIs for a specified data model, e.g:

```csharp
<AutoQueryGrid Model="Booking" Apis="Apis.AutoQuery<QueryBookings,CreateBooking,UpdateBooking,DeleteBooking>()" />
```

[![](/img/pages/blazor/autoquerygrid-crud.png)](https://blazor-gallery.jamstacks.net/gallery/autoquerygrid/crud)

### Customizable Columns

As `AutoQueryGrid` builds on `DataGrid` it also inherits its customizable option allowing for [customizable responsive columns](https://blazor-gallery.servicestack.net/gallery/autoquerygrid), e.g:

```html
<AutoQueryGrid Model="Booking" Apis="Apis.AutoQuery<QueryBookings,CreateBooking,UpdateBooking,DeleteBooking>()"
               AllowSelection="true" AllowFiltering="true"
               HeaderSelected="OnSelectedHeader" RowSelected="OnSelectedRow">
    <Columns>
        <!-- Custom class -->
        <Column Field="(Booking x) => x.Id" class="text-gray-900" />
        <!-- Only show from Tailwind's xl responsive Breakpoint -->
        <Column Field="(Booking x) => x.Name" VisibleFrom="Breakpoint.ExtraLarge" />
        <!-- Custom Header collapsing 'Room' below 'lg' responsive breakpoint -->
        <Column Field="(Booking x) => x.RoomType">
            <Header>
                <span class="hidden lg:inline">Room </span>Type
            </Header>
        </Column>
        <!-- Custom Header collapsing 'Room' below 'lg' responsive breakpoint -->
        <Column Field="(Booking x) => x.RoomNumber">
            <Header>
                <span class="hidden lg:inline">Room </span>No
            </Header>
        </Column>
        <!-- Custom string Format -->
        <Column Field="(Booking x) => x.Cost" Format="C" />
        <!-- Custom C# Formatter -->
        <Column Field="(Booking x) => x.BookingStartDate" Formatter="FormatDate" VisibleFrom="Breakpoint.Small">
            <Header>
                Start<span class="hidden lg:inline"> Date</span>
            </Header>
        </Column>
        <!-- Custom Header and Cell Value -->
        <Column Field="(Booking x) => x.BookingEndDate" VisibleFrom="Breakpoint.ExtraLarge2x">
            <Header>
                End<span class="hidden lg:inline"> Date</span>
            </Header>
            <Template>
                @context.BookingEndDate?.ToString("D")
            </Template>
        </Column>
        <!-- Custom Title and Complex Type Cell with Reference Link -->
        <Column Title="Voucher" Field="(Booking x) => x.Discount" VisibleFrom="Breakpoint.ExtraLarge">
            <Template>
@if (context.Discount != null)
{
    <TextLink class="flex items-end" href=@($"/gallery/autoquerygrid/coupons?Id={context.Discount.Id}")>
        <PreviewFormat Value=@context.Discount />
    </TextLink>
}          </Template>
        </Column>
    </Columns>
</AutoQueryGrid>
```

Customizing how and when columns are rendered at different breakpoints using different formatting options and custom table header and cell templates:

[![](/img/pages/blazor/autoquerygrid-responsive.png)](https://blazor-gallery.jamstacks.net/gallery/autoquerygrid/responsive)

### Declarative Customizations

The columns can also be customized declaratively using the `[Format]` Metadata Attribute on the Model type:

```csharp
public class Contact : AuditBase
{
    [AutoIncrement]
    public int Id { get; set; }

    [Format(FormatMethods.IconRounded)]
    public string ProfileUrl { get; set; }

    public string FirstName { get; set; }
    public string LastName { get; set; }

    [Format(FormatMethods.Currency)]
    public int? SalaryExpectation { get; set; }

    [Format(FormatMethods.LinkEmail, Options = 
        @"{target:'_self',subject:'New Job Opportunity',
           body:'We have an exciting new opportunity...', cls:'text-green-600'}")]
    public string Email { get; set; }

    [Format(FormatMethods.LinkPhone)]
    public string Phone { get; set; }
}
```

Which can change how results are formatted in the data grid results:

[![](/img/pages/blazor/autoquerygrid-metadata.png)](https://blazor-gallery.jamstacks.net/grid/contacts-meta)

Whilst the `[Input]` and `[FieldCss]` attributes on the AutoQuery CRUD DTOs:

```csharp
public class UpdateContact : IPatchDb<Contact>, IReturn<Contact>
{
    public int Id { get; set; }

    [ValidateNotEmpty]
    public string? FirstName { get; set; }

    [ValidateNotEmpty]
    public string? LastName { get; set; }

    [Input(Type = "file"), UploadTo("profiles")]
    public string? ProfileUrl { get; set; }
    
    public int? SalaryExpectation { get; set; }

    [ValidateNotEmpty]
    public string? JobType { get; set; }

    public int? AvailabilityWeeks { get; set; }
    public EmploymentType? PreferredWorkType { get; set; }
    public string? PreferredLocation { get; set; }

    [ValidateNotEmpty]
    public string? Email { get; set; }
    public string? Phone { get; set; }
 
    [Input(Type="textarea")]
    [FieldCss(Field="col-span-12 text-center", Input="h-48", Label="text-xl text-indigo-700")]
    public string? About { get; set; }
}
```

Can customize how forms are rendered, e.g:

[![](/img/pages/blazor/autoquerygrid-metadata-form.png)](https://blazor-gallery.jamstacks.net/grid/contacts-meta)


### ToolbarButtons

The `<ToolbarButtons>` element can be used to customize the AutoQueryGrid to add your own custom Toolbar buttons, e.g:

```html
<AutoQueryGrid>
  <ToolbarButtons>
    <div class="pl-2"><button>1</button></div>
    <div class="pl-2"><button>2</button></div>
  </ToolbarButtons>
</AutoQueryGrid>
```

 Enabling complete control over the Toolbar as all existing toolbar buttons can be removed with [AutoQueryGrid parameters](https://reference.servicestack.net/api/ServiceStack.Blazor.Components.Tailwind/AutoQueryGrid%60Model%60).

### Custom Edit and Create Forms

The `<CreateForm>` and `<EditForm>` elements can be used to replace the default [Auto Forms](https://blazor-gallery.jamstacks.net/gallery/autoform) used in creating and editing rows when more advanced or customized functionality is needed.

With this feature we can create a Custom AutoQueryGrid component that uses Custom Edit & Create Forms when selecting and adding new records and also customize the Grid results displayed with the new `ConfigureQuery` parameter to ensure results are filtered to the selected Tenant records:

```html
<AutoQueryGrid @ref=@grid Model="Item" Apis="Apis.AutoQuery<QueryItems,NewItem,EditItem>()" ConfigureQuery="Configure">
    <CreateForm>
        <div class="relative z-10">
            <div class="pointer-events-none fixed inset-y-0 right-0 flex max-w-full pl-10 sm:pl-16">
                <CustomCreateItem OnClose="grid!.OnEditDone" />
            </div>
        </div>
    </CreateForm>
    <EditForm>
        <div class="relative z-10">
            <div class="pointer-events-none fixed inset-y-0 right-0 flex max-w-full pl-10 sm:pl-16">
                <CustomEditItem Item="context" OnClose="grid!.OnEditDone" />
            </div>
        </div>
    </EditForm>
</AutoQueryGrid>

@code {
    AutoQueryGrid<Creative>? grid;
    [Parameter, SupplyParameterFromQuery] public int? TenantId { get; set; }

    void Configure(QueryBase query)
    {
        query.AddQueryParam("TenantId", TenantId);
    }
}
```

### Managing Filters & Preferences

By default the AutoQueryGrid displays the user's selected columns and query limit preferences which are persisted in localStorage. 
They can be overridden with the new **Prefs** attribute which has different ergonomic methods for configuration within an attribute:

To limit the Query Results Limit:

```html
<AutoQueryGrid @ref=@grid Model="Contact" Apis="Apis.AutoQuery<QueryContacts,CreateContact,UpdateContact>()"
               Prefs="ApiPrefs.Create(take:10)" />
```

To limit which columns are displayed in the Query Results:

```html
<AutoQueryGrid @ref=@grid Model="Contact" Apis="Apis.AutoQuery<QueryContacts,CreateContact,UpdateContact>()"
               Prefs="ApiPrefs.Columns(nameof(Contact.Id), nameof(Contact.LastName))" />
```

```html
<AutoQueryGrid @ref=@grid Model="Contact" Apis="Apis.AutoQuery<QueryContacts,CreateContact,UpdateContact>()"
               Prefs="ApiPrefs.Columns<Contact>(x => new { x.Id, x.LastName, x.Email })" />
```

To configure both Query Limit and Selected Columns:

```html
<AutoQueryGrid @ref=@grid Model="Contact" Apis="Apis.AutoQuery<QueryContacts,CreateContact,UpdateContact>()"
               Prefs="ApiPrefs.Create(take:10, columns:new(){ nameof(Contact.Id), nameof(Contact.LastName) })" />
```

```html
<AutoQueryGrid @ref=@grid Model="Contact" Apis="Apis.AutoQuery<QueryContacts,CreateContact,UpdateContact>()"
               Prefs="ApiPrefs.Configure(x => { x.Take = 5; x.SelectedColumns=new() { nameof(Contact.LastName) }; })"/>
```

In addition the new methods below can be used to clear any user-defined query filters and column preferences:

| Method | Description |
|--|--|
| grid.ClearFiltersAsync()     | Remove user-defined Filters |
| grid.ResetPreferencesAsync() | Remove user-defined Filters and Column Preferences |


### Disable Column Filtering

By default Filtering and Sorting are disabled for complex type columns, they can also be explicitly disabled per column with `AllowFiltering`, e.g:

```html
<AutoQueryGrid>
    <Column Field="(Contact x) => x.Phone" AllowFiltering="false" />
<AutoQueryGrid>
```

### Changing AutoQueryGrid Defaults

A lot of AutoQueryGrid's UI is customizable allowing you to easily toggle on/off UI features as needed, if you have a consistent style you wish to enforce you can 
change the defaults of every AutoQueryGrid component with [BlazorConfig](#blazor-config), e.g. you can remove **Copy URL** button and change the default Table style to use Uppercase Headings with:

```csharp
BlazorConfig.Set(new() {
    //...
    AutoQueryGridDefaults = new() {
        TableStyle = TableStyle.StripedRows | TableStyle.UppercaseHeadings,
        ShowCopyApiUrl = false,
    }
});
```

Which will change the appearance of every `AutoQueryGrid` Component used in the App unless overridden.

### AutoQueryGrid Gallery

As AutoQueryGrid is a core component for the rapid development of Apps we're maintaining a dedicated section showcasing their different features at [blazor-gallery.servicestack.net/grid](https://blazor-gallery.servicestack.net/grid):

[![](/img/pages/blazor/autoquerygrid-more.png)](https://blazor-gallery.servicestack.net/grid)

## Modal Lookups

To provide an optimal UX for relational fields `AutoQueryGrid` utilizes Modal Lookups for searching and selecting referential data that's automatically inferred from your OrmLite data model relationships, e.g:

```csharp
public class JobApplication : AuditBase
{
    [AutoIncrement]
    public int Id { get; set; }

    [References(typeof(Job))]
    public int JobId { get; set; }
    
    [References(typeof(Contact))]
    public int ContactId { get; set; }
    //...
}
```

Where it will display an enhanced [LookupInput](https://reference.servicestack.net/api/ServiceStack.Blazor.Components.Tailwind/LookupInput) instead of a plain Text Input for the relational `JobId` and `ContactId` fields:

[![](/img/pages/blazor/modalLookup-input.png)](https://blazor-gallery.servicestack.net/grid/job-applications?edit=1)

Which users can use to quickly search for the related record instead of manually inserting Foreign Key Ids:

[![](/img/pages/blazor/modalLookup-dialog.png)](https://blazor-gallery.servicestack.net/grid/job-applications?edit=1)

## File Uploads

Another feature showcased in the above screenshots is support for [Managed File Uploads](/locode/files-overview) which can be declaratively added with the `[Input(Type="file")]` to render the [FileInput](https://reference.servicestack.net/api/ServiceStack.Blazor.Components.Tailwind/FileInput) Component and `[UploadTo]` attribute to specify which File [Upload location](/locode/files#basic-file-upload-example) it should use:

```csharp
public class UpdateJobApplication : IPatchDb<JobApplication>, IReturn<JobApplication>
{
    public int Id { get; set; }
    public int? JobId { get; set; }
    public int? ContactId { get; set; }
    public DateTime? AppliedDate { get; set; }
    public JobApplicationStatus? ApplicationStatus { get; set; }

    [Input(Type = "file"), UploadTo("applications")]
    public List<JobApplicationAttachment>? Attachments { get; set; }
}
```

For a quick primer on using Managed File Uploads to [Upload files from Blazor](/locode/files-blazor) checkout:

<div class="my-16 px-4 sm:px-6">
    <div class="text-center">
      <h1 class="text-4xl tracking-tight font-extrabold text-gray-900 sm:text-5xl">
        <a href="/locode/files-blazor" class="block xl:inline">File Blazor</a>
      </h1>
    </div>
    <div class="my-8">
        <lite-youtube class="w-full mx-4 my-4" width="560" height="315" videoid="5sd00MzHpaU" style="background-image: url('https://img.youtube.com/vi/5sd00MzHpaU/maxresdefault.jpg')"></lite-youtube>
    </div>
</div>

## Auto Forms

The Auto Form components are other high productivity components which can be used to create an automated form based from a Request DTO definition:

```csharp
<AutoCreateForm Model="Booking" ApiType="typeof(CreateBooking)" />
```

[![](/img/pages/blazor/AutoCreateForm.png)](https://blazor-gallery.servicestack.net/gallery/autoform)

### AutoEditForm

Whilst `AutoEditForm` can be used to render an automated form based to update and delete an [AutoQuery CRUD](/autoquery/crud) API:

```csharp
<AutoEditForm Model="Booking" Edit="Model" ApiType="typeof(UpdateBooking)" DeleteApiType="typeof(DeleteBooking)" />

@code {
    Booking Model = Create.Booking("First Booking!", RoomType.Queen, 10, 100, "employee@email.com");
}
```

[![](/img/pages/blazor/AutoEditForm.png)](https://blazor-gallery.servicestack.net/gallery/autoform)

The forms behavior and appearance is further customizable with the [API annotation](/locode/declarative#annotate-apis), declarative [validation](/locode/declarative#type-validation-attributes) and the custom [Field and Input](/locode/declarative#custom-fields-and-inputs) attributes, e.g:

```csharp
[Description("Update an existing Booking")]
[Notes("Find out how to quickly create a <a class='svg-external' target='_blank' href='https://youtu.be/rSFiikDjGos'>C# Bookings App from Scratch</a>")]
[Route("/booking/{Id}", "PATCH")]
[ValidateHasRole("Employee")]
[AutoApply(Behavior.AuditModify)]
public class UpdateBooking : IPatchDb<Booking>, IReturn<IdResponse>
{
    public int Id { get; set; }
    public string? Name { get; set; }
    public RoomType? RoomType { get; set; }
    [ValidateGreaterThan(0)]
    public int? RoomNumber { get; set; }
    [ValidateGreaterThan(0)]
    public decimal? Cost { get; set; }
    public DateTime? BookingStartDate { get; set; }
    public DateTime? BookingEndDate { get; set; }
    [Input(Type = "textarea")]
    public string? Notes { get; set; }
    public bool? Cancelled { get; set; }
}
```


Both AutoForm components will render the Forms UI in a Slide Over dialog and includes built-in support for calling the API to update or edit the record with integrated contextual validation, reporting any field validation errors alongside their Input controls.

### AutoFormFields

If more advanced customization of a Forms appearance and behavior is required, you can use `AutoFormFields` to just render the Form's fields (including Validation binding) that can be used to populate a Request DTO that your App can handle sending, e.g:

[![](/img/pages/blazor/AutoFormFields.png)](https://blazor-gallery.servicestack.net/gallery/autoform)

```csharp
<form @onsubmit="submit" @onsubmit:preventDefault>
    <div class="shadow sm:overflow-hidden sm:rounded-md max-w-screen-lg">
        <div class="space-y-6 bg-white py-6 px-4 sm:p-6">
            <div>
                <h3 class="text-lg font-medium leading-6 text-gray-900">@(ApiType.GetDescription())</h3>
                <p class="notes mt-1 text-sm text-gray-500">
                    @((MarkupString)ApiType.GetNotes())
                </p>
            </div>

            <AutoFormFields Type="typeof(Booking)" Api="Api" FormLayout="FormLayout" ModelDictionary="ModelDictionary"/>

        </div>
        <div class="bg-gray-50 px-4 py-3 text-right sm:px-12">
            <PrimaryButton type="submit" onclick="submit">Save</PrimaryButton>
        </div>
    </div>
</form>

@code {
    [Inject] public JsonApiClient? Client { get; set; }
    IHasErrorStatus? Api { get; set; }
    Type ApiType = typeof(UpdateBooking);
    List<InputInfo>? FormLayout { get; set; }
    Dictionary<string, object> ModelDictionary { get; set; } = new();
    MetadataType MetadataType => ApiType.ToMetadataType();

    Booking Edit = Create.Booking("First Booking!", RoomType.Queen, 10, 100, "employee@email.com");

    protected override async Task OnParametersSetAsync()
    {
        await base.OnParametersSetAsync();
        Api = null;

        ModelDictionary = Edit.ToModelDictionary();
        FormLayout ??= MetadataType.CreateFormLayout<Booking>();
    }

    async Task submit()
    {
        var request = ModelDictionary.FromModelDictionary<UpdateBooking>();
        Api = await Client!.ApiAsync(request);
    }
}
```

## Autocomplete

The `<Autocomplete>` component provides a user friendly Input for being able to search and quickly select items, that includes support for rich templated content, custom matching and infinite scrolling that avoids pre-loading the entire bound list of items. 

Instead of being populated with a fixed List of strings or Key Value Pairs the Autocomplete component can bind directly to a list of POCOs to render its templated content where you'll be able to specify a custom `Match` filter to control which filtered items are displayed, that it can fuzzy match on single or multiple POCO properties.

### Single Contact

Here's a simple Autocomplete example that binds to a **simple** `Contact` from a `List<Contact>` in **allContacts**:

```html
<Autocomplete T="Contact" Options="allContacts" @bind-Value="simple" Label="Single Contact"
    Match="(x, value) => x!.DisplayName.Contains(value, StringComparison.OrdinalIgnoreCase)"
    placeholder="Select Contact">
    <Item>
        <span class="block truncate">@context!.DisplayName</span>
    </Item>
</Autocomplete>
```

### Single Contact with Icon

The item content is templated allowing for rich content which can be used to display a Contact's profile picture and name:

```html
<Autocomplete T="Contact" Options="allContacts" @bind-Value="contact" Label="Single Contact with Icon"
    Match="(x, value) => x!.DisplayName.Contains(value, StringComparison.OrdinalIgnoreCase)"
    placeholder="Select Contact">
    <Item>
        <div class="flex items-center">
            <Icon class="h-6 w-6 flex-shrink-0 rounded-full" Src=@context.ProfileUrl />
            <span class="ml-3 truncate">@context!.DisplayName</span>
        </div>
    </Item>
</Autocomplete>
```

### Multiple Contacts with Icon

It also supports multiple selection by using `@bind-Values` to bind to the `List<Contact>` in **contacts** instead, e.g:

```html
<Autocomplete Options="allContacts" @bind-Values="contacts" Label="Multiple Contacts with Icon"
    Match="(x, value) => x!.DisplayName.Contains(value, StringComparison.OrdinalIgnoreCase)"
    placeholder="Select Contacts">
    <Item>
        <div class="flex items-center">
            <Icon class="h-6 w-6 flex-shrink-0 rounded-full" Src=@context.ProfileUrl />
            <span class="ml-3 truncate">@context!.DisplayName</span>
        </div>
    </Item>
</Autocomplete>
```

and here's a working example of what they look like together in the same form ([example source code](https://blazor-gallery.jamstacks.net/gallery/inputs)):

<div class="pt-12 flex justify-center">
    <iframe src="https://blazor-gallery.jamstacks.net/gallery/inputs/autocomplete" class="w-[500px] border-none h-[560px]"></iframe>
</div>

## TagInput

The TagInput component is useful for when you want to manage a list of strings like words or tags - an input that's notably lacking in HTML Forms.
Best of all `<TagInput>` functions like any other input where it can be included and customized in declarative forms. 

For example this Update AutoQuery Request DTO:

```csharp
// Customize Edit Forms with [Input] and [FieldCss] attributes 
public class UpdateContact : IPatchDb<Contact>, IReturn<Contact>
{
    public int Id { get; set; }

    [ValidateNotEmpty]
    public string? FirstName { get; set; }

    [ValidateNotEmpty]
    public string? LastName { get; set; }

    [Input(Type = "file"), UploadTo("profiles")]
    public string? ProfileUrl { get; set; }
    
    public int? SalaryExpectation { get; set; }

    [ValidateNotEmpty]
    public string? JobType { get; set; }

    public int? AvailabilityWeeks { get; set; }
    public EmploymentType? PreferredWorkType { get; set; }
    public string? PreferredLocation { get; set; }

    [ValidateNotEmpty]
    public string? Email { get; set; }
    public string? Phone { get; set; }
    
    [Input(Type = "tag"), FieldCss(Field = "col-span-12")]
    public List<string>? Skills { get; set; }}
 
    [Input(Type="textarea")]
    [FieldCss(Field="col-span-12 text-center", Input="h-48", Label="text-xl text-indigo-700")]
    public string? About { get; set; }
}
```

is all that's needed to render an instantly working API-enabled Form with validation binding using 
[Auto Form components](https://blazor-gallery.jamstacks.net/gallery/autoform):

```html
<AutoEditForm class=@Class Model="Contact" ApiType="typeof(UpdateContact)" Edit=@contact />
```

Which by default renders the form in a SlideOver dialog as seen when editing a row in the [Contacts AutoQueryGrid](https://blazor-gallery.jamstacks.net/grid/contacts-meta?edit=1) component:

<iframe src="https://blazor-gallery.jamstacks.net/grid/contacts-meta/embed?edit=1" class="mt-8 w-full border-none h-[970px]"></iframe>

Alternatively it can be rendered in a traditional **"card"** form layout with the new `FormStyle.Card` option:

```html
<AutoEditForm class=@Class FormStyle="FormStyle.Card" Model="Contact" ApiType="typeof(UpdateContact)" Edit=@contact />
```

<iframe src="https://blazor-gallery.jamstacks.net/gallery/inputs/tag?layout=ExampleLayout&class=max-w-screen-md+mx-auto" class="mt-8 w-full border-none h-[1570px]"></iframe>

Where it functions the same as other Input components where it can be bound directly to a `List<string>` Request DTO property:

```html
<form @onsubmit="submit" @onsubmit:preventDefault class=@Class>
<CascadingValue Value=@apiQuery.Error>
    <div class="shadow sm:rounded-md bg-white dark:bg-black">
        <div class="relative px-4 py-5 sm:p-6">
            <fieldset>
                <ErrorSummary Except=@VisibleFields />

                <div class="grid grid-cols-12 gap-6">
                    <div class="col-span-6">
                        <TextInput @bind-Value="request.FirstName" />
                    </div>

                    <div class="col-span-6">
                        <TextInput @bind-Value="request.LastName" />
                    </div>

                    <div class="col-span-12">
                        <TagInput @bind-Value="request.Skills" />
                    </div>
                </div>
            </fieldset>
        </div>
    </div>
</CascadingValue>
</form>
```

### NavList

The NavList component encapsulates Tailwind's beautiful List component which is used extensively in [Blazor Gallery's Navigation](https://blazor-gallery.jamstacks.net/grid):

```html
<div class="max-w-screen-sm">
    <NavList Title="Explore Blazor Components">
        <NavListItem Title="DataGrid" href="/gallery/datagrid" IconSvg=@Icons.DataGrid>
            DataGrid Component Examples for rendering tabular data
        </NavListItem>
        <NavListItem Title="AutoQuery Grid" href="/gallery/autoquerygrid" IconSvg=@Icons.AutoQueryGrid>
            Instant customizable UIs for calling AutoQuery CRUD APIs
        </NavListItem>
    </NavList>

    <h2 class="mt-8 text-base font-semibold text-gray-500 dark:text-gray-400 flex">
        <span title="Requires Auth"><Icon class="h-6 w-6 mr-2" Svg=@Icons.Padlock /></span>
        Booking APIs
    </h2>
    <NavList>
        <NavListItem Title="Bookings" href="/grid/bookings" Icon=@typeof(Booking).GetIcon()>
            Create and manage Bookings
        </NavListItem>
        <NavListItem Title="Coupons" href="/grid/coupons" Icon=@typeof(Coupon).GetIcon()>
            Create and manage discount Coupons
        </NavListItem>
    </NavList>
</div>
```

Where it will render a list of navigation links with descriptions and icons:

<div class="my-8 flex justify-center">
    <iframe src="https://blazor-gallery.jamstacks.net/gallery/navigation/navlist" class="my-8 w-full h-[510px] border-none"></iframe>
</div>

### Colored Buttons

The `ButtonStyle` on PrimaryButton component can be used to render buttons into Tailwind's different primary colors:

```csharp
<div class="grid gap-4 grid-cols-3">
    <PrimaryButton>Default</PrimaryButton>
    <PrimaryButton Style="ButtonStyle.Blue">Blue</PrimaryButton>
    <PrimaryButton Style="ButtonStyle.Purple">Purple</PrimaryButton>
    <PrimaryButton Style="ButtonStyle.Red">Red</PrimaryButton>
    <PrimaryButton Style="ButtonStyle.Green">Green</PrimaryButton>
    <PrimaryButton Style="ButtonStyle.Sky">Sky</PrimaryButton>
    <PrimaryButton Style="ButtonStyle.Cyan">Cyan</PrimaryButton>
</div>
```

<div class="my-8 flex justify-center">
    <iframe src="https://blazor-gallery.jamstacks.net/gallery/navigation/buttons/styles" class="my-8 w-full h-[160px] border-none"></iframe>
</div>

### Select Input

The `<SelectInput>` `Values` and `Entries` parameters can be used to populate options from an array of string's or KeyValuePair's, it also includes declarative features enabling more capable declarative forms which are typically restricted by the compile-time constant expression limitation of .NET attributes. 

The `EvalAllowableValues` and `EvalAllowableEntries` attribute properties overcomes this limitation by letting you define the Select options with a [#Script](https://sharpscript.net) Expression whose great [.NET scriptability](https://sharpscript.net/docs/script-net) lets you reference your App's .NET instances from a string expression. This feature can then be used to populate declarative Select options from a .NET Instance, e.g:

```csharp
public class CreateModifier : ICreateDb<Modifier>, IReturn<Modifier>
{
    [ValidateNotEmpty]
    public string Name { get; set; }

    [ValidateNotEmpty]
    [Input(Type="select", EvalAllowableValues = "AppData.Categories")]
    public string Category { get; set; }
 
    public string? Description { get; set; }
}
```

That we register as a global variable in our AppHost's `ScriptContext` which we can populate from a dynamic source like a DB Table, e.g:

```csharp
using var db = container.Resolve<IDbConnectionFactory>().Open();
ScriptContext.Args[nameof(AppData)] = new AppData
{
    Categories = db.Column<string>(db.From<Category>().Select(x => x.Name))
};
```

Where it will populate the Select input in all `CreateModifier` Auto Form components:

<div class="mt-8 flex justify-center">
    <img src="/img/pages/blazor/diffusion-CreateModifier.png" class="max-w-screen-md" style="border:1px solid #CACACA">
</div>

## PreviewFormat

The `<PreviewFormat>` component is useful for rendering Table Cell data into different customizable formats, e.g:

```html
<PreviewFormat Value="50" Format=Formats.Currency />

<PreviewFormat Value="1000000" Format=Formats.Bytes />

<PreviewFormat Value=@Url Format=Formats.Icon IconClass="w-40 h-40" />

<PreviewFormat Value=@Url Format=Formats.Icon IconClass="w-40 h-40 rounded-full" />

<PreviewFormat Value=@Url Format=Formats.Attachment />

<PreviewFormat Value=@Path Format=Formats.Attachment />

<PreviewFormat Value=@Url Format=Formats.Link />

<PreviewFormat Value=@Email Format=Formats.LinkEmail />

<PreviewFormat Value=@Phone Format=Formats.LinkPhone />
```

[![](/img/pages/blazor/PreviewFormat.png)](https://blazor-gallery.servicestack.net/gallery/formats)

## HtmlFormat

Whilst the versatile `<HtmlFormat>` component can be used to render any Serializable object into a human-friendly HTML Format, e.g:

### Single Model

```html
<div class="max-w-screen-sm">
    <HtmlFormat Value=@Track.Results[0] />
</div>
```

[![](/img/pages/blazor/HtmlFormat-single.png)](https://blazor-gallery.servicestack.net/gallery/formats)

### Item Collections

```html
<div class="max-w-screen-sm">
    <HtmlFormat Value=@Track.Results />
</div>
```

[![](/img/pages/blazor/HtmlFormat-collection.png)](https://blazor-gallery.servicestack.net/gallery/formats)

### Nested Complex Types

```html
<HtmlFormat Value=@Create.Players />
```

[![](/img/pages/blazor/HtmlFormat-complex.png)](https://blazor-gallery.servicestack.net/gallery/formats)

For more info about the Blazor Components available checkout the [Component Gallery](https://blazor-gallery.servicestack.net/gallery):

[![](/img/pages/blazor/component-gallery.png)](https://blazor-gallery.servicestack.net/gallery)

## Blazor Config

A lot of the default conventions used by the Blazor Components are overridable with [BlazorConfig](https://reference.servicestack.net/api/ServiceStack.Blazor/BlazorConfig) initialized in `Program.cs`, where Blazor WASM projects configured with something like:

```csharp
BlazorConfig.Set(new BlazorConfig
{
    IsWasm = true,
    Services = app.Services,
    FallbackAssetsBasePath = apiBaseUrl,
    EnableLogging = true,
    EnableVerboseLogging = builder.HostEnvironment.IsDevelopment(),
});
```

### Asset and Fallback Paths

Where `FallbackAssetsBasePath` allows you to specify a fallback path for Images which is useful when there's a delay for syncing uploaded assets to the CDN that the Blazor WASM client is deployed to, as it can fallback to referencing the asset from the .NET App Server that handled the file upload. 

Alternatively `AssetsBasePath` can be used for specifying a different primary CDN location that's different from the Blazor WASM App CDN or `AssetsPathResolver` and `FallbackPathResolver` can be used when more a advanced custom strategy is required.


# Vue SPA Project Template
Source: https://docs.servicestack.net/templates/vue

The latest [Vue SPA](https://github.com/NetCoreTemplates/vue-spa) template is a good example of this, building on and enhancing
the built-in ASP.NET Core Vue SPA template with many high-productivity features.

<div class="not-prose mt-16 flex flex-col items-center">
   <div class="flex">
        <svg class="-mt-3 w-32 h-32" xmlns="http://www.w3.org/2000/svg" width="1em" height="1em" viewBox="0 0 32 32"><g fill="none"><path fill="url(#vscodeIconsFileTypeVite0)" d="m29.884 6.146l-13.142 23.5a.714.714 0 0 1-1.244.005L2.096 6.148a.714.714 0 0 1 .746-1.057l13.156 2.352a.714.714 0 0 0 .253 0l12.881-2.348a.714.714 0 0 1 .752 1.05z"/><path fill="url(#vscodeIconsFileTypeVite1)" d="M22.264 2.007L12.54 3.912a.357.357 0 0 0-.288.33l-.598 10.104a.357.357 0 0 0 .437.369l2.707-.625a.357.357 0 0 1 .43.42l-.804 3.939a.357.357 0 0 0 .454.413l1.672-.508a.357.357 0 0 1 .454.414l-1.279 6.187c-.08.387.435.598.65.267l.143-.222l7.925-15.815a.357.357 0 0 0-.387-.51l-2.787.537a.357.357 0 0 1-.41-.45l1.818-6.306a.357.357 0 0 0-.412-.45"/><defs><linearGradient id="vscodeIconsFileTypeVite0" x1="6" x2="235" y1="33" y2="344" gradientTransform="translate(1.34 1.894)scale(.07142)" gradientUnits="userSpaceOnUse"><stop stop-color="#41d1ff"/><stop offset="1" stop-color="#bd34fe"/></linearGradient><linearGradient id="vscodeIconsFileTypeVite1" x1="194.651" x2="236.076" y1="8.818" y2="292.989" gradientTransform="translate(1.34 1.894)scale(.07142)" gradientUnits="userSpaceOnUse"><stop stop-color="#ffea83"/><stop offset=".083" stop-color="#ffdd35"/><stop offset="1" stop-color="#ffa800"/></linearGradient></defs></g></svg>
        <svg class="w-28 h-28" xmlns="http://www.w3.org/2000/svg" width="1.16em" height="1em" viewBox="0 0 256 221"><path fill="#41b883" d="M204.8 0H256L128 220.8L0 0h97.92L128 51.2L157.44 0z"/><path fill="#41b883" d="m0 0l128 220.8L256 0h-51.2L128 132.48L50.56 0z"/><path fill="#35495e" d="M50.56 0L128 133.12L204.8 0h-47.36L128 51.2L97.92 0z"/></svg>
   </div>
</div>
<div class="not-prose mt-4 px-4 sm:px-6">
<div class="text-center"><h3 id="docker-containers" class="text-4xl sm:text-5xl md:text-6xl tracking-tight font-extrabold text-gray-900">
    Vite Vue SPA Template
</h3></div>
<p class="mx-auto mt-5 max-w-3xl text-xl text-gray-500">
    Explore the high productivity features in the new ServiceStack Vue SPA template
</p>
<div class="py-8 max-w-7xl mx-auto px-4 sm:px-6">
    <lite-youtube class="w-full mx-4 my-4" width="560" height="315" videoid="JlUjWlVslRg" style="background-image: url('https://img.youtube.com/vi/JlUjWlVslRg/maxresdefault.jpg')"></lite-youtube>
</div>
</div>

:::{.text-center}
## Live Demo
:::

:::{.shadow .pb-1}
[![](https://raw.githubusercontent.com/ServiceStack/Assets/master/csharp-templates/vue-spa.png)](https://vue-spa.web-templates.io)
:::

## ASP.NET Core Vue SPA Template 

The [Vue and ASP.NET Core](https://learn.microsoft.com/en-us/visualstudio/javascript/tutorial-asp-net-core-with-vue) 
template provides a seamless starting solution which runs both the .NET API backend and Vite Vue frontend during development.

It's a modern template capturing the best Vue has to offer, configured with Vite's fast HMR (Hot Module Reload) and TypeScript support - 
it allows App's to be developed with Vue's typed [Single File Components](https://vuejs.org/guide/scaling-up/sfc.html) enabling
both a productive development experience and an optimal high-performance production build at runtime.

### Minimal API integration

Whilst a great starting point, it's still only a basic template configured with a bare-bones Vue Vite App that's modified
to show an example of calling a Minimal API.

### Built-in API Integration

Although the approach used isn't very scalable, with a proxy rule needed for every user-defined API route:

```ts
export default defineConfig({
    //...
    server: {
        proxy: {
            '^/weatherforecast': {
                target,
                secure: false
            }
        },
    }
})
```

And the need for hand maintained Types to describe the shape of the API responses with [Stringly Typed](https://wiki.c2.com/?StringlyTyped)
fetch API calls referencing **string** routes:

```ts
import { defineComponent } from 'vue';

type Forecasts = {
    date: string,
    temperatureC: string,
    temperatureF: string,
    summary: string
}[];

interface Data {
    loading: boolean,
    post: null | Forecasts
}

export default defineComponent({
    data(): Data {
        return {
            loading: false,
            post: null
        };
    },
    created() {
        // fetch the data when the view is created and the data is
        // already being observed
        this.fetchData();
    },
    watch: {
        // call again the method if the route changes
        '$route': 'fetchData'
    },
    methods: {
        fetchData(): void {
            this.post = null;
            this.loading = true;

            fetch('weatherforecast')
                .then(r => r.json())
                .then(json => {
                    this.post = json as Forecasts;
                    this.loading = false;
                    return;
                });
        }
    },
});
```

Which is used to render the API response in a hand rolled table: 

```html
<div v-if="post" class="content">
    <table>
        <thead>
            <tr>
                <th>Date</th>
                <th>Temp. (C)</th>
                <th>Temp. (F)</th>
                <th>Summary</th>
            </tr>
        </thead>
        <tbody>
            <tr v-for="forecast in post" :key="forecast.date">
                <td>{{ forecast.date }}</td>
                <td>{{ forecast.temperatureC }}</td>
                <td>{{ forecast.temperatureF }}</td>
                <td>{{ forecast.summary }}</td>
            </tr>
        </tbody>
    </table>
</div>
```

### ServiceStack API Integration

Fortunately ServiceStack can significantly improve this development experience with the 
[/api pre-defined route](https://docs.servicestack.net/endpoint-routing#api-pre-defined-route) where only a single
proxy rule is needed to proxy all APIs:

```ts
export default defineConfig({
    //...
    server: {
        proxy: {
            '^/api': {
                target,
                secure: false
            }
        },
    }
})
```

### End-to-end Typed APIs

Instead of hand-rolled types and Stringly Typed API calls, it utilizes server 
[generated TypeScript DTOs](https://docs.servicestack.net/typescript-add-servicestack-reference)
with a generic JsonServiceClient to enable end-to-end Typed APIs:

```ts
import { ref, onMounted } from 'vue'
import { ApiResult } from "@servicestack/client"
import { useClient } from "@servicestack/vue"
import { GetWeatherForecast } from "@/dtos"

const client = useClient()
const api = ref(new ApiResult())

onMounted(async () => {
    api.value = await client.api(new GetWeatherForecast())
})
```

This benefits in less code to maintain, immediate static typing analysis to ensure correct usage of APIs and valuable 
feedback when APIs are changed, that's easily updated with a single command:

:::sh
npm run dtos
:::

### High Productivity Vue Components

With access to the [ServiceStack Vue Components](https://docs.servicestack.net/vue/) library there's also less code to 
maintain in the UI, where you can render a beautiful tailwind styled DataGrid with just:

```html
<DataGrid :items="api.response" />
```

## ServiceStack Vue SPA Features

Other high-productivity features available in the ServiceStack Vue SPA template include:

### Integrated Identity Auth

Pre-configured with ASP.NET Core Identity Auth, including Sign In and Custom Registration APIs and
UI Pages which can be customized as needed, examples of Role-based security as well as a turn key solution for
Integrating Identity Auth Registration workflow with your [SMTP Provider](https://docs.servicestack.net/auth/identity-auth#smtp-iemailsender)
with all emails sent from a managed non-blocking [Background MQ](https://docs.servicestack.net/background-mq)
for optimal responsiveness and execution.

### tailwindcss

[Tailwind](https://tailwindcss.com) has quickly become the best modern CSS framework for creating scalable, 
[mobile-first](https://tailwindcss.com/#mobile-first) responsive websites built
upon a beautiful expert-crafted constraint-based [Design System](https://tailwindcss.com/#constraint-based) 
that enables effortless reuse of a growing suite of [Free Community](https://tailwindcomponents.com) and 
professionally-designed [Tailwind UI Component](https://tailwindui.com) Libraries, invaluable for quickly creating beautiful websites.

[![](/img/pages/release-notes/v8.2/tailwindui.png)](https://tailwindcss.com)

<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" aria-hidden="true" role="img" class="mx-auto w-40 h-40 text-gray-800" viewBox="0 0 24 24">
    <path fill="currentColor" d="M9.37 5.51A7.35 7.35 0 0 0 9.1 7.5c0 4.08 3.32 7.4 7.4 7.4c.68 0 1.35-.09 1.99-.27A7.014 7.014 0 0 1 12 19c-3.86 0-7-3.14-7-7c0-2.93 1.81-5.45 4.37-6.49zM12 3a9 9 0 1 0 9 9c0-.46-.04-.92-.1-1.36a5.389 5.389 0 0 1-4.4 2.26a5.403 5.403 0 0 1-3.14-9.8c-.44-.06-.9-.1-1.36-.1z"></path>
</svg>

### Dark Mode

In addition to revolutionizing how we style mobile-first responsive Apps, Tailwind's
[Dark Mode](https://tailwindcss.com/#dark-mode) does the same for enabling Dark Mode
a feature supported throughout all of ServiceStack's [Vue Component Library](https://docs.servicestack.net/vue/).

![](/img/pages/release-notes/v8.2/dark-and-light-mode.png)

### Built for Productivity

So that you're immediately productive out-of-the-box, the template includes a rich set of high-productivity features, including:

|                                                                            |                                                              |
|----------------------------------------------------------------------------|--------------------------------------------------------------|
| [tailwind/typography](https://tailwindcss-typography.vercel.app)           | Beautiful css typography for markdown articles & blog posts  |
| [tailwind/forms](https://github.com/tailwindlabs/tailwindcss-forms)        | Beautiful css form & input styles that's easily overridable  |
| [Markdown](https://github.com/markdown-it/markdown-it)                     | Native Markdown integration                                  |
| [plugin/press](https://github.com/ServiceStack/vite-plugin-press)          | Static markdown for creating blogs, videos and other content |
| [plugin/vue-router](https://github.com/posva/unplugin-vue-router)          | Conventional file system based routing for Vue 3 on Vite     |
| [plugin/layouts](https://github.com/JohnCampionJr/vite-plugin-vue-layouts) | Support for multiple page layouts                            |
| [plugin/components](https://github.com/antfu/unplugin-vue-components)      | Auto importing & registering of components on-demand         |
| [plugin/svg](https://github.com/jpkleemans/vite-svg-loader)                | Load SVG files as Vue components                             |
| [Iconify](https://iconify.design)                                          | Unified registry to access 100k+ high quality SVG icons      |

### Bookings CRUD Pages

Bookings CRUD example shows how you can rapidly develop beautiful responsive, customized CRUD UIs with minimal effort using 
[AutoQuery APIs](https://docs.servicestack.net/autoquery/), [AutoForms](https://docs.servicestack.net/autoform) &
[AutoQueryGrid](https://blazor-gallery.servicestack.net/gallery/autoquerygrid) Vue Components.

### Admin Pages

Whilst Bookings CRUD is a good example of creating custom UI for end users, you may also want to quickly develop a set
of back-office CRUD Admin UIs to manage your App's Database tables, which is easily achievable AutoQueryGrid's default
behavior:

<div class="py-8 max-w-7xl mx-auto px-4 sm:px-6">
    <lite-youtube class="w-full mx-4 my-4" width="560" height="315" videoid="wlRA4_owEsc" style="background-image: url('https://img.youtube.com/vi/wlRA4_owEsc/maxresdefault.jpg')"></lite-youtube>
</div>

The development UX of Admin Pages is further improved in Vue Vite which is able to use SFC Pages and conventional file system
routing to quickly add Admin Pages to manage an App's back-end tables, e.g:

#### [/admin/coupons.vue](https://github.com/NetCoreTemplates/vue-spa/blob/main/MyApp.Client/src/pages/admin/coupons.vue)

```html
<AutoQueryGrid type="Coupon" />
```

#### [/admin/bookings.vue](https://github.com/NetCoreTemplates/vue-spa/blob/main/MyApp.Client/src/pages/admin/bookings.vue)

```html
<AutoQueryGrid type="Booking"
selected-columns="id,name,roomType,roomNumber,bookingStartDate,cost,couponId,discount"
  :header-titles="{ roomNumber:'Room No', bookingStartDate:'Start Date' }"
   :visible-from="{ roomNumber:'lg', cost:'md', couponId:'xl', discount:'never' }" />
```


# React SPA Project Template
Source: https://docs.servicestack.net/templates/react

## ServiceStack React SPA Template

The new TypeScript [Vite React SPA template](https://react-spa.web-templates.io) is an enhanced version of .NET's
built-in ASP.NET Core React SPA template with many new value-added and high-productivity features.

<div class="not-prose mt-16 flex flex-col items-center">
   <div class="flex">
        <svg class="w-28 h-28" xmlns="http://www.w3.org/2000/svg" width="1em" height="1em" viewBox="0 0 32 32"><g fill="none"><path fill="url(#vscodeIconsFileTypeVite0)" d="m29.884 6.146l-13.142 23.5a.714.714 0 0 1-1.244.005L2.096 6.148a.714.714 0 0 1 .746-1.057l13.156 2.352a.714.714 0 0 0 .253 0l12.881-2.348a.714.714 0 0 1 .752 1.05z"/><path fill="url(#vscodeIconsFileTypeVite1)" d="M22.264 2.007L12.54 3.912a.357.357 0 0 0-.288.33l-.598 10.104a.357.357 0 0 0 .437.369l2.707-.625a.357.357 0 0 1 .43.42l-.804 3.939a.357.357 0 0 0 .454.413l1.672-.508a.357.357 0 0 1 .454.414l-1.279 6.187c-.08.387.435.598.65.267l.143-.222l7.925-15.815a.357.357 0 0 0-.387-.51l-2.787.537a.357.357 0 0 1-.41-.45l1.818-6.306a.357.357 0 0 0-.412-.45"/><defs><linearGradient id="vscodeIconsFileTypeVite0" x1="6" x2="235" y1="33" y2="344" gradientTransform="translate(1.34 1.894)scale(.07142)" gradientUnits="userSpaceOnUse"><stop stop-color="#41d1ff"/><stop offset="1" stop-color="#bd34fe"/></linearGradient><linearGradient id="vscodeIconsFileTypeVite1" x1="194.651" x2="236.076" y1="8.818" y2="292.989" gradientTransform="translate(1.34 1.894)scale(.07142)" gradientUnits="userSpaceOnUse"><stop stop-color="#ffea83"/><stop offset=".083" stop-color="#ffdd35"/><stop offset="1" stop-color="#ffa800"/></linearGradient></defs></g></svg>
        <svg class="w-28 h-28" xmlns="http://www.w3.org/2000/svg" width="1em" height="1em" viewBox="0 0 32 32"><circle cx="16" cy="15.974" r="2.5" fill="#007acc"/><path fill="#007acc" d="M16 21.706a28.385 28.385 0 0 1-8.88-1.2a11.3 11.3 0 0 1-3.657-1.958A3.543 3.543 0 0 1 2 15.974c0-1.653 1.816-3.273 4.858-4.333A28.755 28.755 0 0 1 16 10.293a28.674 28.674 0 0 1 9.022 1.324a11.376 11.376 0 0 1 3.538 1.866A3.391 3.391 0 0 1 30 15.974c0 1.718-2.03 3.459-5.3 4.541a28.8 28.8 0 0 1-8.7 1.191m0-10.217a27.948 27.948 0 0 0-8.749 1.282c-2.8.977-4.055 2.313-4.055 3.2c0 .928 1.349 2.387 4.311 3.4A27.21 27.21 0 0 0 16 20.51a27.6 27.6 0 0 0 8.325-1.13C27.4 18.361 28.8 16.9 28.8 15.974a2.327 2.327 0 0 0-1.01-1.573a10.194 10.194 0 0 0-3.161-1.654A27.462 27.462 0 0 0 16 11.489"/><path fill="#007acc" d="M10.32 28.443a2.639 2.639 0 0 1-1.336-.328c-1.432-.826-1.928-3.208-1.327-6.373a28.755 28.755 0 0 1 3.4-8.593a28.676 28.676 0 0 1 5.653-7.154a11.376 11.376 0 0 1 3.384-2.133a3.391 3.391 0 0 1 2.878 0c1.489.858 1.982 3.486 1.287 6.859a28.806 28.806 0 0 1-3.316 8.133a28.385 28.385 0 0 1-5.476 7.093a11.3 11.3 0 0 1-3.523 2.189a4.926 4.926 0 0 1-1.624.307m1.773-14.7a27.948 27.948 0 0 0-3.26 8.219c-.553 2.915-.022 4.668.75 5.114c.8.463 2.742.024 5.1-2.036a27.209 27.209 0 0 0 5.227-6.79a27.6 27.6 0 0 0 3.181-7.776c.654-3.175.089-5.119-.713-5.581a2.327 2.327 0 0 0-1.868.089A10.194 10.194 0 0 0 17.5 6.9a27.464 27.464 0 0 0-5.4 6.849Z"/><path fill="#007acc" d="M21.677 28.456c-1.355 0-3.076-.82-4.868-2.361a28.756 28.756 0 0 1-5.747-7.237a28.676 28.676 0 0 1-3.374-8.471a11.376 11.376 0 0 1-.158-4A3.391 3.391 0 0 1 8.964 3.9c1.487-.861 4.01.024 6.585 2.31a28.8 28.8 0 0 1 5.39 6.934a28.384 28.384 0 0 1 3.41 8.287a11.3 11.3 0 0 1 .137 4.146a3.543 3.543 0 0 1-1.494 2.555a2.59 2.59 0 0 1-1.315.324m-9.58-10.2a27.949 27.949 0 0 0 5.492 6.929c2.249 1.935 4.033 2.351 4.8 1.9c.8-.465 1.39-2.363.782-5.434A27.212 27.212 0 0 0 19.9 13.74a27.6 27.6 0 0 0-5.145-6.64c-2.424-2.152-4.39-2.633-5.191-2.169a2.327 2.327 0 0 0-.855 1.662a10.194 10.194 0 0 0 .153 3.565a27.465 27.465 0 0 0 3.236 8.1Z"/></svg>
   </div>
</div>
<div class="not-prose mt-4 px-4 sm:px-6">
<div class="text-center"><h3 id="docker-containers" class="text-4xl sm:text-5xl md:text-6xl tracking-tight font-extrabold text-gray-900">
    Vite React SPA Template
</h3></div>
<p class="mx-auto mt-5 max-w-3xl text-xl text-gray-500">
    Explore the high productivity features in the new ServiceStack React SPA template
</p>
<div class="py-8 max-w-7xl mx-auto px-4 sm:px-6">
    <lite-youtube class="w-full mx-4 my-4" width="560" height="315" videoid="WXLF0piz6G0" style="background-image: url('https://img.youtube.com/vi/WXLF0piz6G0/maxresdefault.jpg')"></lite-youtube>
</div>
</div>

:::{.text-center}
## Live Demo
:::

:::{.shadow .pb-1}
[![](https://raw.githubusercontent.com/ServiceStack/Assets/master/csharp-templates/react-spa.png)](https://react-spa.web-templates.io)
:::

## ASP.NET Core React SPA Template 

The [React and ASP.NET Core](https://learn.microsoft.com/en-us/visualstudio/javascript/tutorial-asp-net-core-with-react) 
template provides a seamless starting solution which runs both the .NET API backend and Vite React frontend during development.

It's a modern template enabling an excellent developer workflow for .NET React Apps, configured with Vite's fast 
HMR (Hot Module Reload), TypeScript support with TSX enabling development of concise and expressive type-safe components.   

### Minimal API integration

Whilst a great starting point, it's still only a basic template configured with a bare-bones React Vite App that's modified
to show an example of calling a Minimal API.

### Built-in API Integration

Although the approach used isn't very scalable, with a proxy rule needed for every user-defined API route:

```ts
export default defineConfig({
    //...
    server: {
        proxy: {
            '^/weatherforecast': {
                target,
                secure: false
            }
        },
    }
})
```

And the need for hand maintained Types to describe the shape of the API responses with [Stringly Typed](https://wiki.c2.com/?StringlyTyped)
fetch API calls referencing **string** routes:

```ts
interface Forecast {
    date: string;
    temperatureC: number;
    temperatureF: number;
    summary: string;
}

function App() {
    const [forecasts, setForecasts] = useState<Forecast[]>();

    useEffect(() => {
        populateWeatherData();
    }, []);
    //...
}

async function populateWeatherData() {
    const response = await fetch('weatherforecast');
    const data = await response.json();
    setForecasts(data);
}
```

Which is used to render the API response in a hand rolled table:

```tsx
function App() {
    //...
    const contents = forecasts === undefined
        ? <p><em>Loading... Please refresh once the ASP.NET backend has started. See 
            <a href="https://aka.ms/jspsintegrationreact">jsps</a> for more details.
            </em></p>
        : <table className="table table-striped" aria-labelledby="tabelLabel">
            <thead>
            <tr>
                <th>Date</th>
                <th>Temp. (C)</th>
                <th>Temp. (F)</th>
                <th>Summary</th>
            </tr>
            </thead>
            <tbody>
                {forecasts.map(forecast =>
                    <tr key={forecast.date}>
                        <td>{forecast.date}</td>
                        <td>{forecast.temperatureC}</td>
                        <td>{forecast.temperatureF}</td>
                        <td>{forecast.summary}</td>
                    </tr>
                )}
            </tbody>
        </table>;
}
```

### ServiceStack API Integration

Fortunately ServiceStack can significantly improve this development experience with the
[/api pre-defined route](https://docs.servicestack.net/endpoint-routing#api-pre-defined-route) where only a single
proxy rule is needed to proxy all APIs:

```ts
export default defineConfig({
    //...
    server: {
        proxy: {
            '^/api': {
                target,
                secure: false
            }
        },
    }
})
```

### End-to-end Typed APIs

Instead of hand-rolled types and Stringly Typed API calls, it utilizes server
[generated TypeScript DTOs](https://docs.servicestack.net/typescript-add-servicestack-reference)
with a generic JsonServiceClient to enable end-to-end Typed APIs:

```ts
import { useState, useEffect } from "react"
import { useClient } from "@/gateway"
import { GetWeatherForecast } from "@/dtos"

const client = useClient()
const [forecasts, setForecasts] = useState<Forecast[]>([])

useEffect(() => {
    (async () => {
        const api = await client.api(new GetWeatherForecast())
        if (api.succeeded) {
            setForecasts(api.response!)
        }
    })()
}, [])
```

This benefits in less code to maintain, immediate static typing analysis to ensure correct usage of APIs and valuable
feedback when APIs are changed, that's easily updated with a single command:

:::sh
npm run dtos
:::

### React Component Ecosystem

Given it's popularity, React has arguably the richest ecosystem of freely available libraries and components, a good
example are the popular [shadcn/ui](https://ui.shadcn.com) Tailwind components. Unlike most libraries they're source copied 
piecemeal into your project where they're locally modifiable, i.e. instead of an immutable package reference. 

As they're just blueprints, they're not dependent on a single library and will utilize the best library to implement
each component if needed. E.g. the [Data Table](https://ui.shadcn.com/docs/components/data-table) component documents how to implement
your own Data Table utilizing the headless [TanStack Table](https://tanstack.com/table/latest) - a version of which
we've built into [DataTable.tsx](https://github.com/NetCoreTemplates/react-spa/blob/main/MyApp.Client/src/components/DataTable.tsx)
which is used in the template to implement both complex CRUD UIs and 
[weather.tsx](https://github.com/NetCoreTemplates/react-spa/blob/main/MyApp.Client/src/pages/weather.tsx) simple table results:

```tsx
import { columnDefs, DataTable, getCoreRowModel } from "@/components/DataTable.tsx"

const columns = columnDefs(['date', 'temperatureC', 'temperatureF', 'summary'],
  ({ temperatureC, temperatureF}) => {
    temperatureC.header = "Temp. (C)"
    temperatureF.header = "Temp. (F)"
    temperatureC.cell = temperatureF.cell = ({ getValue }) => <>{getValue()}&deg;</>
  })

return (<LayoutPage title="Weather">
  <DataTable columns={columns} data={forecasts} getCoreRowModel={getCoreRowModel()} />
</LayoutPage>)
```

To render the [/weather](https://react-spa.web-templates.io/weather) customized Data Table:

:::{.mx-auto .max-w-lg .shadow .rounded}
[![](/img/pages/release-notes/v8.2/data-table.png)](https://react-spa.web-templates.io/weather)
:::

The template also includes customizable [Form.tsx](https://github.com/NetCoreTemplates/react-spa/blob/main/MyApp.Client/src/components/Form.tsx)
Input components which can be used to create beautiful validation-bound forms which effortlessly integrates with ServiceStack's
[Error Handling](https://docs.servicestack.net/error-handling) and 
[Declarative Validation](https://docs.servicestack.net/declarative-validation) attributes.

## ServiceStack React SPA Features

Other high-productivity features available in the ServiceStack React SPA template include:

### Integrated Identity Auth

Pre-configured with ASP.NET Core Identity Auth, including Sign In and Custom Registration APIs and
UI Pages which can be customized as needed, examples of Role-based security as well as a turn key solution for
Integrating Identity Auth Registration workflow with your [SMTP Provider](https://docs.servicestack.net/auth/identity-auth#smtp-iemailsender)
with all emails sent from a managed non-blocking [Background MQ](https://docs.servicestack.net/background-mq)
for optimal responsiveness and execution.

### tailwindcss

[Tailwind](https://tailwindcss.com) has quickly become the best modern CSS framework for creating scalable,
[mobile-first](https://tailwindcss.com/#mobile-first) responsive websites built
upon a beautiful expert-crafted constraint-based [Design System](https://tailwindcss.com/#constraint-based)
that enables effortless reuse of a growing suite of [Free Community](https://tailwindcomponents.com) and
professionally-designed [Tailwind UI Component](https://tailwindui.com) Libraries, invaluable for quickly creating beautiful websites.

[![](/img/pages/release-notes/v8.2/tailwindui.png)](https://tailwindcss.com)

<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" aria-hidden="true" role="img" class="mx-auto w-40 h-40 text-gray-800" viewBox="0 0 24 24">
    <path fill="currentColor" d="M9.37 5.51A7.35 7.35 0 0 0 9.1 7.5c0 4.08 3.32 7.4 7.4 7.4c.68 0 1.35-.09 1.99-.27A7.014 7.014 0 0 1 12 19c-3.86 0-7-3.14-7-7c0-2.93 1.81-5.45 4.37-6.49zM12 3a9 9 0 1 0 9 9c0-.46-.04-.92-.1-1.36a5.389 5.389 0 0 1-4.4 2.26a5.403 5.403 0 0 1-3.14-9.8c-.44-.06-.9-.1-1.36-.1z"></path>
</svg>

In addition to revolutionizing how we style mobile-first responsive Apps, Tailwind's
[Dark Mode](https://tailwindcss.com/#dark-mode) does the same for enabling Dark Mode
a feature supported throughout the template and its Tailwind UI Components.

[![](/img/pages/release-notes/v8.2/dark-mode.png)](https://tailwindcss.com/#dark-mode)

### Built for Productivity

So that you're immediately productive out-of-the-box, the template includes a rich set of high-productivity features, including:

|                                                                     |                                                              |
|---------------------------------------------------------------------|--------------------------------------------------------------|
| [tailwind/typography](https://tailwindcss-typography.vercel.app)    | Beautiful css typography for markdown articles & blog posts  |
| [tailwind/forms](https://github.com/tailwindlabs/tailwindcss-forms) | Beautiful css form & input styles that's easily overridable  |
| [Markdown](https://mdxjs.com/docs/getting-started/)                 | Native [mdx](https://mdxjs.com) Markdown integration         |
| [React Router](https://reactrouter.com)                             | Full featured routing library for React                      |
| [plugin/press](https://github.com/ServiceStack/vite-plugin-press)   | Static markdown for creating blogs, videos and other content |
| [plugin/pages](https://github.com/hannoeru/vite-plugin-pages)       | Conventional file system based routing for Vite              |
| [plugin/svg](https://github.com/pd4d10/vite-plugin-svgr)            | Load SVG files as React components                           |
| [Iconify](https://iconify.design)                                   | Unified registry to access 100k+ high quality SVG icons      |

### Bookings CRUD Pages

The [Bookings CRUD example](https://react-spa.web-templates.io/bookings-crud) shows how you can utilize a customized 
Data Table and templates Form components to create a beautifully styled CRUD UI with minimal effort.

## Vite Press Plugin

[![](https://images.unsplash.com/photo-1524668951403-d44b28200ce0?crop=entropy&fit=crop&h=384&w=768)](https://vue-spa.web-templates.io/posts/vite-press-plugin)

Most Apps typically have a mix of dynamic functionality and static content which in our experience is best maintained
in Markdown, which is why excited about the new [Vite Press Plugin](https://vue-spa.web-templates.io/posts/vite-press-plugin)
which brings the same Markdown features in our
[razor-ssg](https://razor-ssg.web-templates.io), [razor-press](https://razor-press.web-templates.io) and our
[blazor-vue](https://blazor-vue.web-templates.io) templates, and re-implements them in Vite where they can be used
to add the same rich content features to Vite Vue and Vite React Apps.

A goal for vite-press-plugin is to implement a suite of universal markdown-powered features that can be reused across all
our Vue, React and .NET Razor and Blazor project templates, allowing you to freely copy and incorporate same set of
markdown feature folders to power markdown content features across a range of websites built with different technologies.

All of Razor SSG's features are available in Vite Press Plugin, including:

- [Blog](https://vue-spa.web-templates.io/blog) - Full Featured, beautiful Tailwind Blog with multiple discoverable views
- [What's New](https://vue-spa.web-templates.io/whatsnew) - Build Product and Feature Release pages
- [Videos](https://vue-spa.web-templates.io/videos) - Maintain Video Libraries and Playlists
- [Metadata APIs](https://vue-spa.web-templates.io/posts/vite-press-plugin#metadata-apis-feature) - Generate queryable static .json metadata APIs for all content
- [Includes](https://vue-spa.web-templates.io/posts/vite-press-plugin#includes-feature) - Create and reuse Markdown fragments

It also supports an enhanced version of markdown for embedding richer UI markup in markdown content where most of
[VitePress Containers](https://vitepress.dev/guide/markdown#custom-containers) are supported, including:

- [Custom Markdown Containers](https://vue-spa.web-templates.io/posts/vite-press-plugin#markdown-containers)
    - **Alerts**
        - `info`
        - `tip`
        - `warning`
        - `danger`
    - `copy`
    - `sh`
    - `youtube`
- [Markdown Fenced Code Blocks](https://vue-spa.web-templates.io/posts/vite-press-plugin#markdown-fenced-code-blocks) - Convert fenced code blocks into Richer UIs

### React Components In Markdown

At the cost of reduced portability, you’re also able to embed richer Interactive Vue components directly in markdown:

- [React Components in Markdown](https://react-spa.web-templates.io/posts/markdown-components-in-react)


# Angular Tailwind Template
Source: https://docs.servicestack.net/templates/angular

We're thrilled to announce the launch of our newest Single Page Application (SPA) template which enhances the
seamless integration in [ASP.NET Core's Angular SPA template](https://learn.microsoft.com/en-us/aspnet/core/client-side/spa/angular)
but upgraded from Angular 15 to the accelerated workflow in [Angular 19's investment in developer experience](https://blog.angular.dev/meet-angular-v19-7b29dfd05b84) 
and performance that's been rewritten to use the latest modern web technologies:

1. **Built-in Identity Authentication:** Secured out-of-the-box, this template integrates seamlessly with ASP.NET Core Identity, providing ready-to-use registration, login, and User Admin management features.
2. **Tailwind v4 CSS:** Rewritten to use Tailwind v4 CSS, allowing you to rapidly build beautiful, responsive designs directly in your markup.
3. **Dark Mode Support:** Cater to user preferences with built-in, easily toggleable dark mode support, styled elegantly with Tailwind.
4. **Customizable DataGrid Component:** Effortlessly display tabular data with the included customizable DataGrid. Easily adapt it for sorting, filtering and displaying your specific data structures.
5. **Reusable Input Components with Validation:** The template includes reusable, pre-styled input components (e.g., text input, selects) with built-in support for validation bound forms and contextual displaying of validation errors.
6. **RxJS & Signals Support:** Modern Angular reactivity: whether you prefer the established power of **RxJS Observables** or the new granular reactivity of **Angular Signals**, our template is structured to support *both* programming models.

Angular's structured approach to modern web development is ideal for large complex Applications that stitches together various 
technologies, handling authentication, designing responsive UIs, and managing complex state which the new Angular SPA template
embraces to provide a productive starting point with a robust foundation packed with essential features right out of the box.

## Getting Started

The default Angular SPA Template can be downloaded below:  

<project-creator v-slot="x">
    <project-template :name="x.text" repo="NetCoreTemplates/angular-spa" :tags="['vite','auth']">
        <div class="mb-3 text-xl font-medium text-gray-700 dark:text-gray-200">Angular SPA</div>
        <template #icon>
            <svg class="w-12 h-12 text-indigo-600" xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24"><path fill="currentColor" d="m12 2.5l8.84 3.15l-1.34 11.7L12 21.5l-7.5-4.15l-1.34-11.7L12 2.5m0 2.1L6.47 17h2.06l1.11-2.78h4.7L15.45 17h2.05L12 4.6m1.62 7.9h-3.23L12 8.63l1.62 3.87Z"></path></svg>
        </template>
    </project-template>
</project-creator>

Alternatively you can download a custom template from the [Start Page](https://servicestack.net/start).

The source code for the template is maintained at [NetCoreTemplates/angular-spa](https://github.com/NetCoreTemplates/angular-spa)
whilst an online live-demo is available from: [angular-spa.web-templates.io](https://angular-spa.web-templates.io)

## Feature Tour

We'll take a quick tour to explore the templates features

### Home Page

The home page sports a responsive Tailwind design where all its components are encapsulated within its 
[/MyApp.Client/src/app/home](https://github.com/NetCoreTemplates/angular-spa/tree/main/MyApp.Client/src/app/home)
with its logic maintained in `*.ts` files and its presentation UI optionally maintained in a separate `*.html` file:

[![](/img/pages/templates/angular-spa/angular-home.webp)](https://angular-spa.web-templates.io)

The [dark-mode-toggle.component.ts](https://github.com/NetCoreTemplates/angular-spa/blob/main/MyApp.Client/src/components/dark-mode-toggle.component.ts)
and [theme.service.ts](https://github.com/NetCoreTemplates/angular-spa/blob/main/MyApp.Client/src/components/services/theme.service.ts)
handles switching between Light and Dark Mode which is initially populated from the Users OS preference: 

[![](/img/pages/templates/angular-spa/angular-dark.webp)](https://angular-spa.web-templates.io)

### Weather

The Weather page maintained in [/app/weather](https://github.com/NetCoreTemplates/angular-spa/tree/main/MyApp.Client/src/app/weather) 
provides a good example of utilizing an RxJS Observable programming model with the 
[api-http-client.service.ts](https://github.com/NetCoreTemplates/angular-spa/blob/main/MyApp.Client/src/components/services/api-http-client.service.ts)
that extends Angular's Observable HttpClient with an additional `api` method that lets you use your Services typed `dtos.ts`
TypeScript DTOs to enable type-safe integration with your back-end services: 

```ts
import { Forecast, GetWeatherForecast, ResponseStatus } from 'src/dtos'
import { ApiHttpClient } from 'src/components/services/api-http-client.service'

export class WeatherComponent {
  http = inject(ApiHttpClient);

  public error: ResponseStatus | null = null;
  public forecasts: Forecast[] = [];

  getForecasts() {
    this.http.api(new GetWeatherForecast({ date:'2025-04-01' })).subscribe({
        next:(result) => {
            this.error = null;
            this.forecasts = result;
        },
        error:(error) => {
            this.error = error;
        }
    });
  }
}
```

Whilst its [weather.component.html](https://github.com/NetCoreTemplates/angular-spa/blob/main/MyApp.Client/src/app/weather/weather.component.html)
template showcases the new [data-grid.component.ts](https://github.com/NetCoreTemplates/angular-spa/blob/main/MyApp.Client/src/components/data-grid.component.ts)
to display a beautiful tailwind DataGrid with just:

```html
<data-grid [items]="forecasts"></data-grid>
```

[![](/img/pages/templates/angular-spa/angular-datagrid-default.webp)](https://angular-spa.web-templates.io/weather)

It's a direct port of our [Vue DataGrid](https://docs.servicestack.net/vue/datagrid) that also supports
the same customizations allowing for custom Headers and Column fields, e.g:

```html
<data-grid [items]="forecasts">
    <ng-template #dateHeader>
        <div class="flex items-center">
            <span class="font-bold text-green-700 uppercase">Date</span>
        </div>
    </ng-template>

    <ng-template #date let-x="date">{{ x | date:'MMMM d, yyyy' }}</ng-template>
    <ng-template #temperatureC let-x="temperatureC">
        {{ x }}&deg;
    </ng-template>
    <ng-template #temperatureF let-x="temperatureF">
        {{ x }}&deg;
    </ng-template>
    <ng-template #summary let-x="summary">{{ x }}</ng-template>
</data-grid>
```

Which renders the expected:

[![](/img/pages/templates/angular-spa/angular-datagrid-custom.webp)](https://angular-spa.web-templates.io/weather)

## Todos MVC

The Todos MVC App maintained in [/app/todomvc](https://github.com/NetCoreTemplates/angular-spa/tree/main/MyApp.Client/src/app/todomvc) 
demonstrates how to create the popular [todomvc.com](https://todomvc.com) App in Angular 19.

[![](/img/pages/templates/angular-spa/angular-todos.webp)](https://angular-spa.web-templates.io/todomvc)

It's another example of building a simple CRUD Application with Angular RxJS Observables and your APIs TypeScript DTOs.

This snippet shows how to query and create Todos with the `ApiHttpClient`:

```ts
import { Todo, QueryTodos, CreateTodo, ResponseStatus } from 'src/dtos'
import { ApiHttpClient } from 'src/components/services/api-http-client.service'

export class TodoMvcComponent implements OnInit {
    client = inject(ApiHttpClient);
    error: ResponseStatus | null = null;
    todos: Todo[] = [];
    newTodoText = '';
    
    loadTodos(): void {
        this.client.api(new QueryTodos()).subscribe({
            next: (todos) => {
                this.todos = todos.results;
            },
            error: (err) => {
                this.error = err;
            }
        });
    }

    addTodo(): void {
        if (!this.newTodoText.trim()) return;

        this.client.api(new CreateTodo({
            text: this.newTodoText.trim()
        })).subscribe({
            next: (todo) => {
                this.todos.push(todo);
                this.newTodoText = '';
            },
            error: (err) => {
                this.error = err;
                console.error('Error adding todo:', err);
            }
        });
    }
    //...
}
```

## Bookings

All other examples in the template uses Angular's newer Signal for reactivity and the standard ServiceStack `JsonServiceClient` 
used in all other TypeScript/JS Apps.

The Bookings Pages are maintained in [/app/bookings](https://github.com/NetCoreTemplates/angular-spa/tree/main/MyApp.Client/src/app/bookings)
and showcases a more complete example of developing a CRUD UI in Angular starting with an example of how to encapsulate
route information for a feature in an isolated [booking.routes.ts](https://github.com/NetCoreTemplates/angular-spa/blob/main/MyApp.Client/src/app/bookings/booking.routes.ts):

```ts
import { Routes } from '@angular/router';
import { BookingListComponent } from './booking-list.component';
import { BookingCreateComponent } from './booking-create.component';
import { BookingEditComponent } from './booking-edit.component';
import { authGuard } from 'src/guards';

export const BOOKING_ROUTES: Routes = [
  { 
    path: 'bookings', 
    component: BookingListComponent,
    canActivate: [authGuard]
  },
  { 
    path: 'bookings/create', 
    component: BookingCreateComponent,
    canActivate: [authGuard]
  },
  { 
    path: 'bookings/edit/:id', 
    component: BookingEditComponent,
    canActivate: [authGuard]
  }
];
```

The use of the Route `authGuard` ensures only Authenticated Users can access these routes, as well as redirecting 
non-authenticated users to the Sign In page.

### Bookings List 

[![](/img/pages/templates/angular-spa/angular-bookings-list.webp)](https://angular-spa.web-templates.io/bookings)

The bookings list component shows an example of using Angular's Signals with the `JsonServiceClient` together with
an `ApiState` context to enable data bound forms and validation errors:

```ts
@Component({
    templateUrl: './booking-list.component.html',
    providers: [
        ...provideApiState()
    ],
    //...
})
export class BookingListComponent implements OnInit {
    private router = inject(Router);
    private client = inject(JsonServiceClient);
    api = inject(ApiState);

    // Signals for state
    allBookings = signal<Booking[]>([]);

    ngOnInit(): void {
        this.loadBookings();
    }

    async loadBookings(): Promise<void> {
        this.api.begin();

        const api = await this.client.api(new QueryBookings({
            orderByDesc: 'BookingStartDate',
        }));
        if (api.succeeded) {
            this.allBookings.set(api.response!.results);
        }

        this.api.complete(api.error);
    }
}
```

Using `provideApiState()` implicitly injects the populated API context containing both the APIs Loading and Error state into child components saving you from having to explicitly inject it into each component.

E.g. the `<form-loading>` component will display when API Requests are in-flight whilst API Error Responses are displayed
after receiving failed API Responses:

```html
<app-page title="Bookings" class="max-w-6xl">

    <form-loading text="Loading Bookings..."></form-loading>
    <error-summary></error-summary>

    @if (allBookings().length > 0) {
    <data-grid [items]="allBookings()">...</data-grid>
    }
    @else {
    <div class="text-center py-4 bg-gray-50 rounded-md">
        <p class="text-gray-500">No bookings found</p>
    </div>
    }
    
</app-page>
```

### Create Booking

The [booking-create.component.ts](https://github.com/NetCoreTemplates/angular-spa/blob/main/MyApp.Client/src/app/bookings/booking-create.component.ts) shows the standard pattern of calling ServiceStack Typed APIs to 
save forms whilst saving any validation errors to the `ApiState` context:

```ts
async save(): Promise<void> {
    this.api.begin();

    const request = new CreateBooking(this.booking());
    const api = await this.client.api(request);
    if (api.succeeded) {
        // Navigate back to bookings list after successful save
        this.router.navigate(['/bookings']);
    }

    this.api.complete(api.error);
}
```

Where any contextual validation will be displayed next to the input field:

[![](/img/pages/templates/angular-spa/angular-booking-create-validation.webp)](https://angular-spa.web-templates.io/bookings/create)

### Edit Booking

The [booking-edit.component.ts](https://github.com/NetCoreTemplates/angular-spa/blob/main/MyApp.Client/src/app/bookings/booking-edit.component.ts)
shows an example of using the `JsonServiceClient` with Signals to get and modify bookings:

```ts
export class BookingEditComponent implements OnInit {
    private route = inject(ActivatedRoute);
    private router = inject(Router);
    private client = inject(JsonServiceClient);
    meta = inject(MetadataService);
    api = inject(ApiState);

    // Signals
    booking = signal<Booking>(new Booking());

    ngOnInit(): void {
        // Get booking ID from route params
        const id = this.route.snapshot.paramMap.get('id');
        if (id) {
            this.fetchBooking(parseInt(id, 10));
        } else {
            this.api.setErrorMessage('Booking ID is required');
        }
    }

    async fetchBooking(id: number): Promise<void> {
        this.api.begin();

        const api = await this.client.api(new QueryBookings({id}));
        if (api.succeeded) {
            this.booking.set(api.response!.results[0]);
        }

        this.api.complete(api.error);
    }

    async save(): Promise<void> {
        this.api.begin();

        const api = await this.client.api(new UpdateBooking(this.booking()));
        if (api.succeeded) {
            this.router.navigate(['/bookings']);
        }

        this.api.complete(api.error);
    }
}
```

[![](/img/pages/templates/angular-spa/angular-booking-edit.webp)](https://angular-spa.web-templates.io/bookings/edit/1)

It shows an example of a validation bound form bounded to a signal instance of a `Booking` DTO with summary and
contextual validation and utilization of your API's metadata with `meta.enumOptions('RoomType')` which populates
the `<select>` drop down with the C# `RoomType` enum values:

```html
<app-page title="Edit Booking">
<form-loading></form-loading>

@if (booking().id) {
<form class="grid gap-4 py-4" (ngSubmit)="save()">
  <input class="hidden" type="submit" />
  <fieldset [disabled]="api.loading()">
  <error-summary except="name,roomType,roomNumber,cost,bookingStartDate,notes" class="mb-4"></error-summary>
    <div class="grid grid-cols-6 gap-6">
        <div class="col-span-6 sm:col-span-3">
            <text-input id="name" name="name" required placeholder="Name for this booking"
                        [(ngModel)]="booking().name"></text-input>
        </div>
        <div class="col-span-6 sm:col-span-3">
            <select-input id="roomType" name="roomType" [options]="meta.enumOptions('RoomType')"
                          [(ngModel)]="booking().roomType"></select-input>
        </div>
        <div class="col-span-6 sm:col-span-3">
            <text-input type="number" id="roomNumber" name="roomNumber" min="0" required
                        [(ngModel)]="booking().roomNumber"></text-input>
        </div>
        <div class="col-span-6 sm:col-span-3">
            <text-input type="number" id="cost" name="cost" min="0" required
                        [(ngModel)]="booking().cost"></text-input>
        </div>
        <div class="col-span-6 sm:col-span-3">
            <text-input type="date" id="bookingStartDate" name="bookingStartDate" required
                        [(ngModel)]="booking().bookingStartDate"></text-input>
        </div>
        <div class="col-span-6 sm:col-span-3">
            <text-input type="date" id="bookingEndDate" name="bookingEndDate"
                        [(ngModel)]="booking().bookingEndDate"></text-input>
        </div>
        <div class="col-span-6">
            <textarea-input id="notes" name="notes" rows="6" placeholder="Notes about this booking"
                            [(ngModel)]="booking().notes"></textarea-input>
        </div>
    </div>
  </fieldset>
  <div class="flex justify-between">
    <div>
        <confirm-delete (delete)="delete()"></confirm-delete>
    </div>
    <div class="flex flex-wrap sm:flex-nowrap gap-4">
        <secondary-button (click)="close()">
            Close
        </secondary-button>
        @if (booking().cancelled) {
        <primary-button type="button" color="green" [disabled]="api.loading()" (click)="cancelBooking(false)">
            Restore Booking
        </primary-button>
        }
        @else {
        <primary-button type="button" color="red" [disabled]="api.loading()" (click)="cancelBooking(true)">
            Cancel Booking
        </primary-button>
        }
        <primary-button type="submit" [disabled]="api.loading()">
            {{ api.loading() ? 'Saving...' : 'Save Booking' }}
        </primary-button>
    </div>
  </div>
</form>
}
@else {
<error-summary></error-summary>
}
</app-page>
```

## Sign In Page

The [signin.component.ts](https://github.com/NetCoreTemplates/angular-spa/blob/main/MyApp.Client/src/app/signin/signin.component.ts)
shows an example of integrating with [auth.service.ts](https://github.com/NetCoreTemplates/angular-spa/blob/main/MyApp.Client/src/services/auth.service.ts)
to Authenticate a User on the Client and Server:

[![](/img/pages/templates/angular-spa/angular-signin.webp)](https://angular-spa.web-templates.io/signin)

## Sign Up Page

The [signup.component.ts](https://github.com/NetCoreTemplates/angular-spa/blob/main/MyApp.Client/src/app/signup/signup.component.ts)
shows an example of the Identity Auth Sign Up workflow of creating new users with the `Register` API and redirecting to
the [signup-confirm.component.ts](https://github.com/NetCoreTemplates/angular-spa/blob/main/MyApp.Client/src/app/signup/signup-confirm.component.ts)
for Email Confirmation.

[![](/img/pages/templates/angular-spa/angular-register.webp)](https://angular-spa.web-templates.io/signup)


# C# Jamstack Project Templates
Source: https://docs.servicestack.net/templates/jamstack

ServiceStack's Jamstack templates encapsulates the latest technologies at the forefront of modern web development to deliver both a great **developer experience** and **performant** end-user UX.

[Jamstack](https://jamstack.org/what-is-jamstack) (**J**avaScript, **A**PIs, and **M**arkup) is a modern architecture pattern to build fast, secure and easy to scale web applications where pre-rendering content, enhancing with JavaScript and leveraging CDN static hosting results in a highly productive, flexible and performant system that takes advantage of CDN edge caches to deliver **greater performance** & efficiency at **lower cost**. 

<div class="not-prose">
<a href="https://jamstacks.net" class="my-8 py-8 flex justify-center text-gray-600 hover:no-underline" title="jamstacks.net">
    <div class="flex justify-center items-end p-4 pt-0 border-2 border-solid border-transparent rounded hover:border-indigo-600">
        <svg viewBox="0 0 256 256" class="w-20 h-20 mr-2" alt="Jamstacks logo"><path d="M128 0C57.221 0 0 57.221 0 128c0 70.778 57.221 128 128 128c70.778 0 128-57.222 128-128V0H128z" fill="#F0047F"></path><path d="M121.04 134.96v93.312c-49.663-2.837-89.64-42.345-93.215-91.81l-.097-1.502h93.312zm90.962 0c-2.6 49.664-38.816 89.64-84.159 93.215l-1.377.097V134.96h85.536zm.112-91.074v85.648h-85.648V43.886h85.648z" fill="#FFF"></path></svg>
        <h1 class="text-8xl font-bold">Jamstacks</h1>
        <div class="ml-4 bg-purple-600 text-white py-1 pb-2 px-3 rounded-md text-7xl">.NET</div>
    </div>
</a>
</div>

### Jamstack Benefits

It's become the preferred architecture for modern performant web apps with 
[benefits](https://jamstack.org/why-jamstack/) extending beyond performance to improved: 

 - **Security** from a reduced attack surface from hosting read-only static resources and requiring fewer App Servers
 - **Scale** with non-essential load removed from App Servers to CDN's architecture capable of incredible scale & load capacity
 - **Maintainability** resulting from reduced hosting complexity and the clean decoupling of UI and server logic
 - **Portability** with your static UI assets being easily capable from being deployed and generically hosted from any CDN or web server
 - **Developer Experience** with major JavaScript Frameworks embracing Jamstack in their dev model, libraries & tooling  

Ultimately, it's hosting your App's pre-rendered static UI assets on Content Delivery Network (CDN) edge caches close to users locations that's primarily responsible for its lightning performance.

![](/img/pages/jamstack/cdn-world-view.png)

### $0.40 /month

Other by-products of generating pre-computed CDN hostable assets, is interchangeable cost-effective hosting and great SEO - characteristics our Jamstack Demos take advantage of with free **UI** hosting on GitHub Pages CDN leaving their only cost to host its **.NET 6 API** back-ends, deployed with SSH in Docker compose containers to a vanilla [Digital Ocean](https://www.digitalocean.com) droplet costing only **[$0.40 /month each](https://vue-ssg.jamstacks.net/hosting)**.

### Recommended Templates

These templates represent the best-in class experiences for their respective **React**, **Vue** & **Blazor WASM** ecosystems each, packed with features & examples common in many websites including Integrated Auth, rich Markdown content as well as TODOs MVC and CRUD examples with built-in contextual validation binding. As such they're **now recommended** over our existing SPA and C# MVC Templates.

We've put together a quick check list to help decide which templates we'd recommend:

| Project                                                 | Recommendation                                                                  |
|---------------------------------------------------------|---------------------------------------------------------------------------------|
| [Next.js](https://github.com/NetCoreTemplates/nextjs)   | If you prefer React                                                             |
| [Vue SSG](https://github.com/NetCoreTemplates/vue-ssg)  | If you prefer Vue and SEO is important                                          |
| [Blazor Tailwind](/templates/blazor-tailwind)           | If you prefer a full C# Stack or are developing Line of Business (LOB) Apps     |
| [Vue SPA](https://github.com/NetCoreTemplates/vue-vite) | If you prefer Vue and happy to trade SEO benefits of SSG for a simpler template |

Still not sure? familiarize yourself with their respective dev models by comparing their functionality equivalent TODOs MVC Examples:

### TODOs MVC

<jamstack-todos class="not-prose my-8 pb-8"></jamstack-todos>

All projects utilize the same back-end ServiceStack Services with **TODOs MVC** implemented in
[TodosServices.cs](https://github.com/NetCoreTemplates/blazor-wasm/blob/main/MyApp.ServiceInterface/TodosServices.cs).


As **Bookings CRUD** is an [AutoQuery CRUD](/autoquery/crud) API, it defines [all its functionality](/autoquery/crud-bookings) in its declarative
[Bookings.cs](https://github.com/NetCoreTemplates/blazor-wasm/blob/main/MyApp.ServiceModel/Bookings.cs) DTOs and serves as a good example for the minimal dev model effort required to implement a typical Authenticated CRUD UI in each framework:

### Bookings CRUD

<jamstack-bookings-crud body="max-w-screen-lg" class="not-prose my-8 pb-8"></jamstack-bookings-crud>

<p class="text-center">Once you know the framework you wish to use, create a new App using your preferred <b>Project Name</b> below:</p>

<h3 class="text-center">Download new C# Jamstack Project Template</h3>

<jamstack-templates class="not-prose pb-8"></jamstack-templates>

::: info
An updated list of available Jamstack project templates is also at https://jamstacks.net (built with Razor SSG)
:::

### Pre-configured Jamstack App Deployments

All project templates supports CDN hostable UI assets and include the [necessary GitHub Actions](https://vue-ssg.jamstacks.net/posts/deploy) that takes care of building and SSH deploying a Docker compose production build of your App to any Linux Host with just a few GitHub Action Secrets in your GitHub repo. 

The optional `DEPLOY_CDN` secret lets you control whether to deploy your App's static `/wwwroot` assets to your GitHub Pages CDN by specifying the custom domain to use and is what all JamStack Live demos used to deploy a copy of their UIs to GitHub Pages CDN:

| Project Source                                                         | GitHub Pages CDN              | Digital Ocean Docker .NET API     |
| -                                                                      | -                             | -                                 |
| [nextjs](https://github.com/NetCoreTemplates/nextjs)                   | nextjs.jamstacks.net          | nextjs-api.jamstacks.net          |
| [vue-ssg](https://github.com/NetCoreTemplates/vue-ssg)                 | vue-ssg.jamstacks.net         | vue-ssg-api.jamstacks.net         |
| [blazor](https://github.com/NetCoreTemplates/blazor)                   | blazor.web-templates.io       | blazor.web-templates.io           |
| [vue-spa](https://github.com/NetCoreTemplates/vue-spa)                 | vue-spa.jamstacks.net         | vue-spa-api.jamstacks.net         |
| [blazor-wasm](https://github.com/NetCoreTemplates/blazor-wasm)         | blazor-wasm.web-templates.io  | blazor-wasm.web-templates.io      |

## Blazor WebAssembly

The [Blazor WebAssembly (WASM)](/templates/blazor-tailwind) template offers a pure end-to-end integrated C# solution to building a high performance web application with [Blazor](https://dotnet.microsoft.com/en-us/apps/aspnet/web-apps/blazor) and ServiceStack. Due to the integrated dev model we've been able to achieve in Blazor it's become **our preferred technology** to use to develop **Line of Business Apps** since it's the only C# Razor solution adopting our preferred [API First Development](/api-first-development) model with Web UIs reusing the same well-defined APIs as Mobile and Desktop Apps.

<lite-youtube class="w-full mx-4 my-4" width="560" height="315" videoid="TIgjMf_vtCI" style="background-image: url('https://img.youtube.com/vi/TIgjMf_vtCI/maxresdefault.jpg')"></lite-youtube>

### Great Perceived Performance and SEO

Typically the **large download sizes** & slow initial load times of Blazor WASM Apps would make it a poor choice for Internet hosted sites. However, our Blazor WASM template has largely mitigated this with easily maintainable built-in pre-rendering techniques to make every page appear to load quickly, including **instant loading** of its Markdown Pages courtesy of the GitHub Actions publish task generating & deploying pre-rendered content pages.

<p class="pt-3 text-center">You can see the results of this in its live demo when loading the home page, which only has a slight delay:</p>

<a class="flex flex-col justify-center items-center hover:no-underline mb-8" href="https://blazor-wasm.web-templates.io">
    <h3 class="mb-3">blazor-wasm.web-templates.io</h3>
    <img src="/img/pages/jamstack/blazor-wasm/home.png" class="border border-solid border-gray-200 max-w-screen-sm">
</a>

### Learn more

To find out more watch its [YouTube overview](https://youtu.be/TIgjMf_vtCI) and visit the [Blazor WASM docs](/templates/blazor-tailwind).

## Razor SSG

The [razor-ssg](https://razor-ssg.web-templates.io/posts/razor-ssg) ServiceStack template leverages the power of .NET Razor to provide seamless static site generation (SSG) capabilities. It's perfect for building content-rich applications like product websites, blogs, portfolios, and more. 

This template streamlines the development process while offering versatility in customizing and extending your project. With GitHub Codespaces integration, you can develop, test, and manage your application all within your browser, eliminating the need for a dedicated development environment and expediting your workflow.

<lite-youtube class="w-full mx-4 my-4" width="560" height="315" videoid="MRQMBrXi5Sc" style="background-image: url('https://img.youtube.com/vi/MRQMBrXi5Sc/maxresdefault.jpg')"></lite-youtube>

## Next.js

For those preferring working with **React**, there's a clear choice in Nextjs.org - currently the flagship & [most popular Jamstack](https://jamstack.org/generators/) framework backed by the folks over at [Vercel](https://vercel.com), where it enjoys deep engineering talent committed to maintaining and continually improving it, so you can be confident in the longevity of the technology and the React framework maintained by [Meta](https://meta.com) (Facebook).

<a href="https://nextjs.jamstacks.net" title="nextjs.jamstacks.net"><img src="/img/pages/jamstack/next-black.svg" class="mx-auto block" /></a>

Designed as an SSG framework from the start, its pre-defined patterns include static generation and UX focused functionality built-in. 

<lite-youtube class="w-full mx-4 my-4" width="560" height="315" videoid="3pPLRyPsO5A" style="background-image: url('https://img.youtube.com/vi/3pPLRyPsO5A/maxresdefault.jpg')"></lite-youtube>

### Stale While Revalidate

Its [SWR](https://swr.vercel.app) Data Fetching React Hooks library is one innovative example utilizing the popular 
[stale-while-revalidate](https://web.dev/stale-while-revalidate/) UX pattern to help developers balance 
between **immediacy** — loading cached content right away — and **freshness** — ensuring updates to the cached content are used in the future.

To take advantage of this, the [nextjs](https://github.com/NetCoreTemplates/nextjs) template includes a `swrClient` that provides a typed wrapper for making typed SWR API Requests with ServiceStack's generic [JsonServiceClient](/typescript-add-servicestack-reference):

```tsx
import { swrClient } from "../lib/gateway"
import { Hello } from "../lib/dtos"

const HelloApi = ({ name }) => {
  const {data, error} = swrClient.get(() => 
    new Hello({ name }))
  if (error) return <div>{error.message}</div>
  return <div>{data?data.result:'loading...'}</div>
}
```

This reactively sets up the UI to handle multiple states:
 - `loading` - displays **loading...** message whilst API request is in transit
 - `data` - when completed, populated with a `HelloResponse` and displayed
 - `error` - when failed, populated with `ResponseStatus` and displayed

The primary UX benefits are realized when re-making an existing request in which a locally-cached *stale* version
is **immediately** returned and displayed whilst a new API Request is made behind the scenes, updating the UI if the fresh response was modified.


<p class="hide-h2"></p>

## Vite

<div class="not-prose">
<a href="https://vitejs.dev" class="flex justify-center mt-8 py-8 hover:no-underline text-gray-700">
    <div class="flex flex-col align-center text-center">
        <div class="pl-10">
            <svg class="w-60 h-60" xmlns="http://www.w3.org/2000/svg" width="256" height="257" viewBox="0 0 256 257"><defs><linearGradient id="logosVitejs0" x1="-.828%" x2="57.636%" y1="7.652%" y2="78.411%"><stop offset="0%" stop-color="#41D1FF"/><stop offset="100%" stop-color="#BD34FE"/></linearGradient><linearGradient id="logosVitejs1" x1="43.376%" x2="50.316%" y1="2.242%" y2="89.03%"><stop offset="0%" stop-color="#FFEA83"/><stop offset="8.333%" stop-color="#FFDD35"/><stop offset="100%" stop-color="#FFA800"/></linearGradient></defs><path fill="url(#logosVitejs0)" d="M255.153 37.938L134.897 252.976c-2.483 4.44-8.862 4.466-11.382.048L.875 37.958c-2.746-4.814 1.371-10.646 6.827-9.67l120.385 21.517a6.537 6.537 0 0 0 2.322-.004l117.867-21.483c5.438-.991 9.574 4.796 6.877 9.62Z"/><path fill="url(#logosVitejs1)" d="M185.432.063L96.44 17.501a3.268 3.268 0 0 0-2.634 3.014l-5.474 92.456a3.268 3.268 0 0 0 3.997 3.378l24.777-5.718c2.318-.535 4.413 1.507 3.936 3.838l-7.361 36.047c-.495 2.426 1.782 4.5 4.151 3.78l15.304-4.649c2.372-.72 4.652 1.36 4.15 3.788l-11.698 56.621c-.732 3.542 3.979 5.473 5.943 2.437l1.313-2.028l72.516-144.72c1.215-2.423-.88-5.186-3.54-4.672l-25.505 4.922c-2.396.462-4.435-1.77-3.759-4.114l16.646-57.705c.677-2.35-1.37-4.583-3.769-4.113Z"/></svg>
        </div>
        <h3 class="text-6xl mb-3 mt-0">Vite</h3>
        <h4 class="text-2xl text-gray-400 font-normal">Next Generation Frontend Tooling</h4>
    </div>
</a>
</div>

Despite Vercel's full-time resources, Next.js is still reliant on the Webpack ecosystem, who although have done a formidable job managing complex tooling requirements for npm projects over a number of years, has since lost the Developer Experience (DX) crown to [vitejs.dev](https://vitejs.dev)

Vite is being [built for speed](https://vitejs.dev/guide/why.html) in the modern era and takes advantage of modern browser features like native ES modules support to remove bundling entirely during development and adopts performance leading technologies like [esbuild](https://github.com/evanw/esbuild) to pre-bundle dependencies and [transpile TypeScript](https://vitejs.dev/guide/features.html#typescript) which is able to do **20-30x** faster than TypeScript's own `tsc` compiler.

Ultimately its architectural choices allows Vite to deliver Lightning Fast **Hot Module Reload** (HMR) to remain at the developer-experience forefront of modern web development serving a [growing ecosystem](https://vitejs.dev/guide/) of frameworks with a rich typed suite of [Universal Plugins](https://vitejs.dev/plugins/).

<lite-youtube class="w-full mx-4 my-4" width="560" height="315" videoid="D-rU0lU_B4I" style="background-image: url('https://img.youtube.com/vi/D-rU0lU_B4I/maxresdefault.jpg')"></lite-youtube>

### Vue SSG or SPA

Both Vue & Vite being led by [Evan You](https://github.com/yyx990803), which ensures both have stellar integration and delivers a well-supported & productive development experience making it the clear choice for any new Vue project.

Both vue-ssg.jamstacks.net and vue-vite.jamstacks.net utilizing the same high-end Vue3, TypeScript and Tailwind components means their included pages like **TODOs MVC**, **Bookings** and **Sign In** contain **identical source code**, the choice on which to use effectively becomes if you need advanced features like [Static Site Generation](https://www.cloudflare.com/en-au/learning/performance/static-site-generator/) **(SSG)** and **Dark Mode** or would otherwise prefer to start with a simpler template.

#### Features list comparison

 - vue-ssg.jamstacks.net/features
 - vue-vite.jamstacks.net/features

### Stale-while-revalidate in Vue3

Just like [Next.js's Stale While Revalidate](#stale-while-revalidate), both Vue templates includes a `swrClient` providing a typed wrapper around [SWVR](https://github.com/Kong/swrv) Vue3 composition library around making typed SWR API Requests using ServiceStack’s typed `JsonServiceClient`, e.g:

```html
<template>
  <div v-if="error">{{ error.message }}</div>
  <div v-else>{{data ? data.result :'loading...'}}</div>
</template>

<script setup lang="ts">
import { Hello } from "@/dtos"
import { swrClient } from "@/api"

const props = defineProps<{ name: string }>()

const { data, error } = swrClient.get(() => 
    new Hello({ name: props.name }))
</script>
```

Where it yields the same optimal UX with cached API responses rendered instantly before later updating itself if modified.

## Vue SSG

React & Next.js are primarily corporate-led efforts whilst the Vue ecosystem is largely community led, with one of Vue's lieutenants [Anthony Fu](https://github.com/antfu) being the primary developer behind many of the developer-experience focused features adopted in his [vite-ssg](https://github.com/antfu/vite-ssg) project. Most of these features are designed to reduce developer effort by auto registering routes and components by convention which effectively gives it [Nuxt](https://nuxtjs.org) like productivity by utilizing hand-picked quality dependencies without needing to be reliant on the slow development pace of a heavy framework like Nuxt.

Anthony's own opinionated Vite Starter Template - [Vitesse](https://github.com/antfu/vitesse) serves as a great resource for an experienced insight into a curated list of Vue & Vite packages offering the nicest developer experience, although Vue SSG will be more conservative and adopt more well-known technologies like [tailwindcss](https://tailwindcss.com/) in favor of [Windi CSS](https://github.com/windicss/windicss).

Otherwise, it's still jam-packed full of features for modern Web Apps, including built-in **Dark Mode** support:

<a class="flex flex-col justify-center items-center my-8" href="https://vue-ssg.jamstacks.net">
    <img src="/img/pages/jamstack/vue-ssg-home.png" class="max-w-screen-md">
</a>

## Vue Vite

Don't need SSG or Dark mode? Try the simpler **SPA** template instead:

<a class="flex flex-col justify-center items-center my-8 pb-8" href="https://vue-vite.jamstacks.net">
    <img src="/img/pages/jamstack/vue-vite-home.png" class="max-w-screen-md">
</a>

## /api route

Each Jamstack templates are configured to the `/api` predefined route for JSON APIs:

<div class="not-prose">
<h3 class="text-4xl text-center text-indigo-800 pb-3">/api/{Request}</h3>
</div>

This simple and popular convention makes it easy to remember the route new APIs are immediately available on & also pairs nicely with:

<div class="not-prose">
<h3 class="text-4xl text-center text-indigo-800 pb-3">/ui/{Request}</h3>
</div>

i.e. An easy to remember route for API Explorer's Auto Form UI, together we expect both to yield greater utility [out-of-the-box](https://en.wikipedia.org/wiki/Out_of_the_box_(feature)) in ServiceStack Apps. 

### Benefits in Jamstack Apps

The `/api` route is particularly useful in Jamstack Apps as the 2 ways to call back-end APIs from decoupled UIs hosted on CDNs is to make CORS requests which doesn't send pre-flight CORS requests for [Simple Browser requests](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS#simple_requests). As such, we can improve the latency of **GET** and **POST** API Requests by configuring our `JsonServiceClient` to use `/api` and to not send the `Content-Type: application/json` HTTP Header which isn't necessary for `/api` who always expects and returns JSON:

### Configuring in TypeScript

```ts
import { JsonServiceClient } from "@servicestack/client"

const client = new JsonServiceClient(baseUrl)
```

It also benefits the **alternative method** to CORS in only needing to define a **single reverse proxy rule** on the CDN host to proxy all API requests to downstream back-end servers.


# Empty Project Templates
Source: https://docs.servicestack.net/templates/empty

## Create Empty .NET 6 Web Apps

::include empty-projects.md::

## Empty ASP .NET Core and .NET Framework Templates

The templates below follow our recommended [physical project layout](/physical-project-structure) where **web** is our recommended empty starting project for Web Apps whilst **selfhost** is an empty project with the minimum dependencies.

<table class="table">
<tr>
    <th>.NET 6.0</th>
    <th>.NET Framework</th>
    <th>ASP .NET Core on FX</th>
    <th>Empty Project Templates</th>
</tr>
<tr>
    <td><a href="https://github.com/NetCoreTemplates/web">web</a></td>
    <td><a href="https://github.com/NetFrameworkTemplates/web-netfx">web-netfx</a></td>
    <td><a href="https://github.com/NetFrameworkCoreTemplates/web-corefx">web-corefx</a></td>
    <td align="center">
        <h3>Empty Web Template</h3>
        <a href="http://web.web-templates.io"><img src="https://raw.githubusercontent.com/ServiceStack/Assets/master/csharp-templates/web.png" width="500" /></a>
        <p><a href="http://web.web-templates.io">web.web-templates.io</a></p>
    </td>
</tr>
<tr>
    <td><a href="https://github.com/NetCoreTemplates/selfhost">selfhost</a></td>
    <td><a href="https://github.com/NetFrameworkTemplates/selfhost-netfx">selfhost-netfx</a></td>
    <td><a href="https://github.com/NetFrameworkCoreTemplates/web-corefx">selfhost-corefx</a></td>
    <td align="center">
        <h3>Empty SelfHost Console Template</h3>
        <a href="http://selfhost.web-templates.io"><img src="https://raw.githubusercontent.com/ServiceStack/Assets/master/csharp-templates/selfhost.png" width="500" /></a>
        <p><a href="http://selfhost.web-templates.io">selfhost.web-templates.io</a></p>
    </td>
</tr>
</table>


### Windows Service Template

You can use [winservice-netfx](https://github.com/NetFrameworkTemplates/winservice-netfx) to create a Windows Service but as this requires Visual Studio it's faster to continue creating new Windows Service projects within VS.NET using the **ServiceStack Windows Service Empty** Project Template.


# Website Project Templates
Source: https://docs.servicestack.net/templates/websites

There are 3 templates for each of the different technologies that can be used with ServiceStack to develop Server HTML Generated Websites and HTTP APIs which can be installed with [dotnet-new](/dotnet-new): 

```bash
$ dotnet tool install --global x 
```

```bash
$ x new mvc AcmeMvc
```

Which will create a new .NET 6.0 MVC Project called **AcmeMvc**. The Template Names, Source Code and Live Demos for each Website Template is available below:

<table class="not-prose table tpl">
<tr>
    <th>.NET 6.0</th>
    <th>.NET Framework</th>
    <th>Single Page App Templates</th>
</tr>
<tr>
    <td><a href="https://github.com/NetCoreTemplates/mvc">mvc</a></td>
    <td><a href="https://github.com/NetFrameworkTemplates/mvc-netfx">mvc-netfx</a></td>
    <th align="center">
        MVC Bootstrap Template
    </th>
</tr>
<tr>
    <td class="tpl-desc" colspan="2">
        The <code class="highlighter-rouge">mvc</code> template differentiates the most between .NET Core and ASP.NET versions as ASP.NET Core MVC and ASP.NET MVC 5 are completely different implementations. With <code class="highlighter-rouge">mvc</code> ServiceStack is configured within the same .NET Core pipeline and shares the same request pipeline and “route namespace” but in ASP.NET MVC 5, ServiceStack is hosted at the <code class="highlighter-rouge">/api</code> Custom Path. Use MVC if you prefer to create different Controllers and View Models for your Website UI independently from your HTTP APIs or if you prefer to generate <strong>server HTML validation errors</strong> within MVC Controllers.
    </td>
    <td align="center">
        <a href="http://mvc.web-templates.io"><img src="https://raw.githubusercontent.com/ServiceStack/Assets/master/csharp-templates/mvc.png" width="450" /></a>
        <p><a href="http://mvc.web-templates.io">mvc.web-templates.io</a></p>
    </td>
</tr>
<tr>
    <td><a href="https://github.com/NetCoreTemplates/razor">razor</a></td>
    <td><a href="https://github.com/NetFrameworkTemplates/razor-netfx">razor-netfx</a></td>
    <th align="center">
        ServiceStack.Razor Bootstrap Template
    </th>
</tr>
<tr>
    <td class="tpl-desc" colspan="2">
        The <code class="highlighter-rouge">razor</code> Template is configured to develop Websites using <a href="https://razor.netcore.io">ServiceStack.Razor</a> for developing server-generated Websites using Razor without MVC Controllers which lets you create Content Razor Pages that can be called directly or View Pages for generating HTML Views for existing Services. The source code for .NET Core and ASP.NET Framework projects are nearly identical despite being completely different implementations with the .NET Core version being retrofitted on top of .NET Core MVC Views. Use <code class="highlighter-rouge">razor</code> templates if you like Razor and prefer the <a href="/api-first-development">API First Development model</a> or plan on developing Websites for both .NET Core and ASP.NET and would like to be easily able to migrate between them.
    </td>
    <td align="center">
        <a href="http://razor.web-templates.io"><img src="https://raw.githubusercontent.com/ServiceStack/Assets/master/csharp-templates/razor.png" width="450" /></a>
        <p><a href="http://razor.web-templates.io">razor.web-templates.io</a></p>
    </td>
</tr>
<tr>
    <td><a href="https://github.com/NetCoreTemplates/script">script</a></td>
    <td><a href="https://github.com/NetFrameworkTemplates/script-netfx">script-netfx</a></td>
    <th align="center">
        ServiceStack #Script Pages Bootstrap Template
    </th>
</tr>
<tr>
    <td class="tpl-desc" colspan="2">
        The <code class="highlighter-rouge">script</code> Project Template is configured to develop Websites using <a href="https://sharpscript.net/docs/script-pages">#Script Pages</a>, a simpler and cleaner alternative to Razor that lets you utilize simple #Script Expressions for evaluating Server logic in <code class="highlighter-rouge">.html</code> pages. #Script doesn’t require any precompilation, is easier to learn and more intuitive for non-programmers that’s more suitable for a <a href="https://sharpscript.net/usecases/">number of use-cases</a>. Use <code class="highlighter-rouge">script</code> if you want an <a href="/releases/v4_5_14#why-templates">alternative to Razor</a> syntax and the heavy machinery required to support it.
    </td>
    <td align="center">
        <img src="https://raw.githubusercontent.com/ServiceStack/Assets/master/csharp-templates/templates.png" width="450" />
    </td>
</tr>
</table>

#### Hot Reloading

Both `razor` and `script` project enjoy Hot Reloading where in development a long poll is used to detect and reload changes in the current Template Page or static files in `/wwwroot`.

### Watched .NET Core builds

.NET Core projects can also benefit from [Live Coding using dotnet watch](https://dotnetcoretutorials.com/2017/01/31/live-coding-net-core-using-dotnet-watch/) which performs a "watched build" where it automatically stops, recompiles and restarts your .NET Core App when it detects source file changes. You can start a watched build from the command-line with:

```bash
$ dotnet watch run
```

### .NET 6.0 ServiceStack WebApp Template

The .NET 6.0 [bare-app](https://github.com/sharp-apps/bare-app) project template is a pre-built .NET 6.0 App that dramatically simplifies .NET Wep App development by enabling Websites and APIs to be developed instantly without compilation.

<table class="not-prose table">
<tr>
    <th>.NET 6.0</th>
    <th>Sharp App</th>
</tr>
<tr>
    <td><a href="https://github.com/sharp-apps/rockwind-app">rockwind-app</a></td>
    <td align="center">
        <a href="http://rockwind-app.web-templates.io/"><img src="https://raw.githubusercontent.com/ServiceStack/Assets/master/csharp-templates/bare-app.png" width="650" /></a>
        <p><a href="http://rockwind-app.web-templates.io/">rockwind-app.web-templates.io</a></p>
    </td>
</tr>
</table>

See [sharpscript.net/docs/sharp-apps](https://sharpscript.net/docs/sharp-apps) to learn the different use-cases made possible with Sharp Apps.


# MVC Project Templates
Source: https://docs.servicestack.net/templates/mvc

All ServiceStack Projects can be created from ServiceStack's Start Page:

<div class="not-prose">
<h3 class="m-0 py-8 text-4xl text-center text-blue-600"><a href="https://servicestack.net/start">servicestack.net/start</a></h3>
</div>

Or using the .NET [x dotnet tool](/dotnet-new):

:::sh
dotnet tool install --global x
:::


## mvc

.NET 6.0 MVC Website with ServiceStack APIs

[![](https://raw.githubusercontent.com/ServiceStack/Assets/master/csharp-templates/mvc.png)](https://github.com/NetCoreTemplates/mvc)

:::sh
x new mvc ProjectName
:::

## MVC with Integrated Auth

### mvcauth

.NET 6.0 MVC Website integrated with ServiceStack Auth

[![](/img/pages/auth/signin/mvcauth.png)](https://github.com/NetCoreTemplates/mvcauth)

:::sh
x new mvcauth ProjectName
:::

::: tip
Learn about [using ServiceStack Auth in MVC](/auth/identity-servicestack)
:::


### mvcidentityserver

.NET 6.0 MVC Website integrated with ServiceStack using IdentityServer4 Auth

[![](/img/pages/auth/signin/mvcidentityserver.png)](https://github.com/NetCoreTemplates/mvcidentityserver)

:::sh
x new mvcidentityserver ProjectName
:::

::: tip
Learn about [using IdentityServer4 Auth in ServiceStack](/auth/identity-aspnet)
:::


# Single Page App Project Templates
Source: https://docs.servicestack.net/templates/single-page-apps

The [ServiceStackVS VS.NET extension](https://github.com/ServiceStack/ServiceStackVS) contains a pre-configured Single Page App VS.NET template for each of the popular JavaScript frameworks:

The Single Page App (SPA) project templates can also be created using the [dotnet-new](/dotnet-new) command line tool:

:::sh
dotnet tool install --global x
:::

```bash
$ dotnet-new <template-name> ProjectName
```

Click on the template name below to view a Live Demo and contents of each project template:

| .NET C# Templates                                                |                                             |
|------------------------------------------------------------------|---------------------------------------------|
| [angular-spa](https://github.com/NetCoreTemplates/angular-spa)   | .NET 8.0 Angular Identity Auth Tailwind SPA |
| [react-spa](https://github.com/NetCoreTemplates/react-spa)       | .NET 8.0 React Identity Auth Tailwind SPA   |
| [vue-spa](https://github.com/NetCoreTemplates/vue-spa)           | .NET 8.0 Vue Identity Auth Tailwind SPA     |


The .NET 8.0 project templates utilizes MSBuild's newer and human-friendly format which can be developed using your preferred C# IDE of VS.NET, VS Code or Rider.

| .NET Framework C# Templates                                                                   |                                                     |
|-----------------------------------------------------------------------------------------------|-----------------------------------------------------|
| [angular-spa-netfx](https://github.com/NetFrameworkTemplates/angular-spa-netfx)               | .NET Framework Angular Bootstrap cli.angular.io App |
| [aurelia-spa-netfx](https://github.com/NetFrameworkTemplates/aurelia-spa-netfx)               | .NET Framework Aurelia Bootstrap Webpack App        |
| [react-desktop-apps-netfx](https://github.com/NetFrameworkTemplates/react-desktop-apps-netfx) | .NET Framework React Desktop Apps                   |
| [react-spa-netfx](https://github.com/NetFrameworkTemplates/react-spa-netfx)                   | .NET Framework React Bootstrap Webpack App          |
| [vue-nuxt-netfx](https://github.com/NetFrameworkTemplates/vue-nuxt-netfx)                     | .NET Framework Vue Nuxt.js SPA Web App              |
| [vue-spa-netfx](https://github.com/NetFrameworkTemplates/vue-spa-netfx)                       | .NET Framework Vue Bootstrap Webpack App            |
| [vuetify-nuxt-netfx](https://github.com/NetFrameworkTemplates/vuetify-nuxt-netfx)             | .NET Framework Vuetify Material Nuxt.js SPA Web App |
| [vuetify-spa-netfx](https://github.com/NetFrameworkTemplates/vuetify-spa-netfx)               | .NET Framework Vuetify Material Webpack App         |

| ASP.NET Core Framework Templates                                                    |                                                                        |
|-------------------------------------------------------------------------------------|------------------------------------------------------------------------|
| [react-lite-corefx](https://github.com/NetFrameworkCoreTemplates/react-lite-corefx) | .NET Framework ASP.NET Core lite (npm-free) React SPA using TypeScript |
| [vue-lite-corefx](https://github.com/NetFrameworkCoreTemplates/vue-lite-corefx)     | .NET Framework ASP.NET Core lite (npm-free) Vue SPA using TypeScript   |


.NET Framework Templates utilize MSBuild's classic project format which can be developed using either VS.NET or Rider.

[![](/img/pages/ssvs/spa-templates-overview.png)](/img/pages/ssvs/spa-templates-overview.png)

Please refer to the documentation in each Project Template for info, scripts and features that's specific to each project template. We'll cover common features
available in most SPA Templates.

Available SPA Project Templates have been bootstrapped with latest CLI tools and are each pre-configured with npm scripts which takes care of all 
packaging and bundling requirements. Gulp is primarily used to provide a GUI to run the 
[templates npm scripts](https://github.com/NetCoreTemplates/vue-spa/blob/9f4c81c9f6dc5e1e812238357853eb0ea08bac51/MyApp/package.json#L7-L15) 
in VS.NET's Task Runner Explorer so all templates features can be accessed without leaving VS.NET, or if preferred each npm script can also be run 
on the command-line with:
 
```bash
$ npm run {script name}
```

All templates also follow our [Recommended Physical Project Structure](/physical-project-structure) ensuring ServiceStack projects starts off from 
an optimal logical project layout, laying the foundation for growing into a more maintainable, cohesive and reusable code-base.

### End-to-end Typed APIs
 
![](/img/pages/ssvs/servicestack-ts.png)
 
Each template is seamlessly integrated with ServiceStack's [TypeScript Add Reference](/typescript-add-servicestack-reference) and generic TypeScript [@servicestack/client](https://github.com/ServiceStack/servicestack-client) to provide an end-to-end Typed API to call your Services that can be synced with your Server DTOs by running the npm (or Gulp) `dtos` script. 

The [Typed API request below](https://github.com/NetCoreTemplates/vue-spa/blob/master/MyApp/src/home/Home.vue) uses the Server Generated 
[dtos.ts](https://github.com/NetCoreTemplates/vue-spa/blob/master/MyApp/src/dtos.ts) and generic `JsonServiceClient` to display a Welcome message on each key-press:
 
```ts
import { client } from '../shared';
import { Hello } from '../dtos';
 
async nameChanged(name: string) {
    if (name) {
        let request = new Hello();
        request.name = name;
        let r = await client.get(request);
        this.result = r.result;
    } else {
        this.result = '';
    }
}
```
 
The imported `client` is an instance of `JsonServiceClient` declared in [shared.ts](https://github.com/NetCoreTemplates/vue-spa/blob/master/MyApp/src/shared.ts) module, configured with the BaseUrl at `/`:
 
```ts
export var client = new JsonServiceClient(global.BaseUrl || '/');
```
 
The `global.BaseUrl` is defined in [package.json](https://github.com/NetCoreTemplates/vue-spa/blob/9f4c81c9f6dc5e1e812238357853eb0ea08bac51/MyApp/package.json#L19) and injected by [Jest](https://facebook.github.io/jest/) or [Karma](https://karma-runner.github.io/2.0/index.html) in order to be able to run end-to-end Integration tests.
 
### Angular 5 HTTP Client

The Angular 5 template is also configured to use Angular's built-in Rx-enabled HTTP Client with ServiceStack's ambient TypeScript declarations, as it's often preferable to utilize Angular's built-in dependencies when available. 

ServiceStack's ambient TypeScript interfaces are leveraged to enable a Typed API, whilst the `createUrl(route,args)` helper lets you reuse your APIs Route definitions (emitted in comments above each Request DTO) to provide a pleasant UX for making API calls using Angular's HTTP Client:

```ts
import { createUrl } from '@servicestack/client';
...

this.http.get<HelloResponse>(createUrl('/hello/{Name}', { name })).subscribe(r => {
    this.result = r.result;
});
```

### TypeScript and Sass
 
![](/img/pages/ssvs/sass-ts.png)
 
All templates are configured with TypeScript which we believe provides the greatest value in enabling a highly-productive and maintainable code-base. TypeScript lets you utilize the latest ES6/7 features including terse ES6 modules and async/await support whilst being able to target down-level browsers. Other benefits include better documented typed APIs, instant compiler feedback, rich intellisense and refactoring support in a graceful superset of JavaScript that scales well to be able develop prototypes quickly then easily go back to harden existing code-bases with optional Type information, catching common errors at compile-time whilst annotating modules with valuable documentation other developers can benefit from.
 
Whilst CSS is a powerful language for styling Web Apps it lacks many of the DRY and reuse features we take for granted in a general purpose programming language. [SASS](http://sass-lang.com/) is designed to close that gap with a number of useful extensions to CSS aimed at enabling a highly-maintainable, modular and configurable css code-base. If you prefer to avoid learning SASS you can continue using vanilla css which has been enhanced with [autoprefixer](https://github.com/postcss/autoprefixer) [online version](https://goonlinetools.com/autoprefixer/) and [precss](https://github.com/jonathantneal/precss) support.

### Optimal Dev Workflow with Hot Reloading

The templates include a hot-reload feature which works similar to [Sharp Pages hot-reloading](https://sharpscript.net/docs/hot-reloading) where in **DebugMode** it will long poll the server to watch for any modified files in `/wwwroot` and automatically refresh the page. 

Hot Reloading works by leveraging [ServiceStack Sharp Pages](https://sharpscript.net/docs/script-pages) which works seamlessly with Webpack's generated `index.html` where it evaluates server Template Expressions when returning the SPA home page. This is leveraged to enable Hot Reloading support by [including the expression](https://github.com/NetCoreTemplates/vue-spa/blob/0c13183b6a5ae20564f650e50d29b9d4e36cbd0c/MyApp/index.template.ejs#L8):

```html
<i hidden>{{ '/js/hot-fileloader.js' | ifDebugIncludeScript }}</i>
```

Which renders the contents of [/js/hot-fileloader.js](https://github.com/ServiceStack/ServiceStack/blob/master/src/ServiceStack/js/hot-fileloader.js) when running the Web App during development.

Although optional, `#Script` is useful whenever you need to render any server logic in the SPA home page, e.g:

```html 
<div>Copyright &copy; {{ now | dateFormat('yyyy') }}</div>
```

Will be evaluated on the server and render the expected:
 
```
Copyright © 2022
```

### [Quick tour of Webpack](/templates/webpack)

Most SPA projects are pre-configured with tooling to manage their own Webpack app builds, but if you want to learn more please see the [Tour of Webpack](/templates/webpack).

### Watched .NET Core builds

.NET Core projects can also benefit from [Live Coding using dotnet watch](https://dotnetcoretutorials.com/2017/01/31/live-coding-net-core-using-dotnet-watch/) which performs a "watched build" where it automatically stops, recompiles and restarts your .NET Core App when it detects source file changes. You can start a watched build from the command-line with:

```bash
$ dotnet watch run
```

## Single Page App Features
 
Our goals with the Single Page Templates is to provide a highly productive base that's ideal for developing small to medium-sized JavaScript Web Apps including just the core essentials that pack the most productive punch whilst adding minimal complexity and required configuration, whilst still remaining open-ended to easily plug-in other tools into your Webpack configuration you believe will improve your development workflow. 
 
With these goals in mind we've hand-picked and integrated a number of simple best-of-breed technologies so you'll be immediately productive:
 
### Integrated UI framework and Vector Icons
 
![](/img/pages/ssvs/bootstrap-fontawesome-material.png)
 
Vue, React, Angular 5 and Aurelia are pre-configured with [Bootstrap v4](https://getbootstrap.com/) and [font-awesome vector font icons](http://fontawesome.io/icons/) whilst Angular 4 is preconfigured to use [Material Design Lite](https://getmdl.io/) and [Material Design Icons](https://material.io/icons/) providing a solution for utilizing resources which are all developed and maintained by Google.

#### Updating Server TypeScript DTOs
 
To get the latest Server DTOs, build the ASP.NET Web App then either right-click on `dtos.ts` and select **Update ServiceStack Reference** from the Context Menu:
 
![](/img/pages/servicestack-reference/typescript-update-reference.png)
 
Or alternatively you can run the `dtos` Gulp task in Task Runner Explorer GUI, or if preferred, run the script on the command-line with:
 
```bash
$ npm run dtos
```
 
### Routing Enabled, Multi-page Layout
  
All templates have multiple views with Routing enabled so they're all setup to develop multi-page navigable Single Page Apps out-of-the-gate. All templates are designed to be functionally equivalent utilizing a 3 page tabbed layout but implemented using their own idiomatic style so you'll be able to easily inspect and compare the structure and ergonomics of each JavaScript framework to evaluate the one you like best.
 
![](/img/pages/ssvs/routing-overview.png)
 
### Deep linkable Pretty URLs
 
All Single Page Apps are configured to use Pretty URLs (i.e. without `#!`) and are deep-linkable so they behave similarly to server-generated websites in that they support the back button and full-page reloads to refresh the current page. This works behind the scenes using a `[FallbackRoute]` to have all unknown routes return the home page so the route can be handled on the client to load the appropriate view.
 
### JavaScript Unit Testing
 
Aurelia, React and React Desktop Apps are configured to use [Facebook's Jest Testing Framework](https://facebook.github.io/jest/) with the React Templates configured to use [Airbnb's enzyme virtual React DOM](https://github.com/airbnb/enzyme) to enable fast, browser-less tests and includes a few different examples of client/server integration tests.
 
Angular and Vue are configured to use the [Karma test runner](https://karma-runner.github.io/1.0/index.html) with the headless phantomjs WebKit browser so the behavior of Components are tested in a real browser.
 
Tests can be run with the `tests-run` gulp task, or on the command-line using any of npm's testing conventions:
 
```bash
$ npm test
$ npm t
```
 
#### Live Testing
 
Each template also includes support for Live Testing which can be run in the background by clicking the `tests-watch` Gulp task or on the command-line with:
 
```bash
$ npm run test-watch
```
 
Live testing automatically re-runs JavaScript tests after each change to provide instant feedback to detect when changes causes existing tests to fail.
 
![](/img/pages/ssvs/gulp-tests-watch.png)
 
### Track progress whilst templates are being created

The Single Page App templates sources their client dependencies from npm which can take up to few minutes to finish downloading and installing. You'll be able to see its progress by looking at the `Bower/npm` Output Window in VS.NET:

![](/img/pages/ssvs/npm-progress.png)

You'll be able to detect when it's finished by waiting for the original contents of **wwwroot/index.html**:

```html
<!-- auto-generated by webpack -->
```

to be replaced with a [Webpack generated html template](https://github.com/NetCoreTemplates/vue-spa/blob/master/MyApp/wwwroot/index.html).

### Keep Desktop node and VS.NET in sync
 
Unfortunately VS.NET 2017 ships with an outdated version of **node.exe** which can be problematic when trying to run scripts from the command-line with a locally installed version of node as native module packages like **node-sass** are coupled to the specific node version and platform they were installed with. This can easily be resolved by configuring VS.NET to use your Desktop version of node instead by adding its the **C:\Program Files\nodejs** folder as the first path in: 
 
```
Tools > Options > Projects and Solutions > External Web Tools
```
 
![](/img/pages/ssvs/node-external-tools.png)
 
## SPA Project Templates Overview

All templates can be installed using our [dotnet-new](/dotnet-new) tool, which if not already can be installed with:

```bash
$ dotnet tool install --global x 
```

The SPA Project Templates below have been bootstrapped with the latest CLI tools from their respective JS Frameworks:

### [vue-spa](https://github.com/NetCoreTemplates/vue-spa)

Bootstrapped with [Vue CLI 3](https://cli.vuejs.org/).

[![](https://raw.githubusercontent.com/ServiceStack/Assets/master/csharp-templates/vue-spa.png)](https://github.com/NetCoreTemplates/vue-spa)

Create new Vue 2.5 Project for .NET 8.0:

```bash
$ x new vue-spa ProjectName
```

Create new Vue 2.5 Project for .NET Framework:

```bash
$ x new vue-spa-netfx ProjectName
```

### [react-spa](https://github.com/NetCoreTemplates/react-spa)

Bootstrapped with [create-react-app](https://github.com/facebook/create-react-app).

[![](https://raw.githubusercontent.com/ServiceStack/Assets/master/csharp-templates/react-spa.png)](https://github.com/NetCoreTemplates/react-spa)

Create new React 16 Project for .NET 8.0:

```bash
$ x new react-spa ProjectName
```

Create new React 16 Project for .NET Framework:

```bash
$ x new react-spa-netfx ProjectName
```

### [angular-spa](https://github.com/NetCoreTemplates/angular-spa)

Bootstrapped with [Angular CLI](https://cli.angular.io).

[![](https://raw.githubusercontent.com/ServiceStack/Assets/master/csharp-templates/angular-spa-bootstrap.png)](https://github.com/NetCoreTemplates/angular-spa)

Create new Angular Project for .NET 8.0:

```bash
$ x new angular-spa ProjectName
```

Create new Angular Project for .NET Framework:

```bash
$ x new angular-spa-netfx ProjectName
```

### [vuetify-spa](https://github.com/NetCoreTemplates/vuetify-spa)

Bootstrapped with [Vue CLI 3](https://cli.vuejs.org/) and the [vuetify cli plugin](https://github.com/vuetifyjs/vue-cli-plugin-vuetify).

[![](https://raw.githubusercontent.com/ServiceStack/Assets/master/csharp-templates/vuetify-spa.png)](https://github.com/NetCoreTemplates/vuetify-spa)

Create new Vuetify Project for .NET 8.0:

```bash
$ x new vuetify-spa ProjectName
```

Create new Vuetify Project for .NET Framework:

```bash
$ x new vuetify-spa-netfx ProjectName
```

### [vue-nuxt](https://github.com/NetCoreTemplates/vue-nuxt)

Bootstrapped with [Nuxt.js starter template](https://nuxtjs.org/guide/installation).

[![](https://raw.githubusercontent.com/ServiceStack/Assets/master/csharp-templates/vue-nuxt.png)](https://github.com/NetCoreTemplates/vue-nuxt)

Create new Nuxt.js v1.4.2 Project for .NET 8.0:

```bash
$ x new vue-nuxt ProjectName
```

Create new Nuxt.js v1.4.2 Project for .NET Framework:

```bash
$ x new vue-nuxt-netfx ProjectName
```

### [vuetify-nuxt](https://github.com/NetCoreTemplates/vuetify-nuxt)

Bootstrapped with [Nuxt.js + Vuetify.js starter template](https://github.com/vuetifyjs/nuxt).

[![](https://raw.githubusercontent.com/ServiceStack/Assets/master/csharp-templates/vuetify-nuxt.png)](https://github.com/NetCoreTemplates/vuetify-nuxt)

Create new Nuxt Vuetify Project for .NET 8.0:

```bash
$ x new vuetify-nuxt ProjectName
```

Create new Nuxt Vuetify Project for .NET Framework:

```bash
$ x new vuetify-nuxt-netfx ProjectName
```

### SPA Project Templates Dev Workflow 

Whilst the client Application has been generated by the official CLI tool from each project, all templates continue to enjoy seamless integration 
with ServiceStack and follows its recommended [Physical Project Structure](/physical-project-structure). 
As the npm scripts vary slightly between projects, you'll need to refer to the documentation in the GitHub project of each template for 
the functionality available, but they all typically share the same functionality below to manage your projects development lifecycle:

Start a watched client build which will recompile and reload web assets on save:

```bash
$ npm run dev
```

Start a watched .NET Core build which will recompile C# `.cs` source files on save and restart the ServiceStack .NET Core App:

```bash
$ dotnet watch run
```

Leaving the above 2 commands running takes care of most of the development workflow which handles recompilation of both modified client and server source code.

Regenerate your client TypeScript DTOs after making a change to any Services:

```bash
$ npm run dtos
```

Create an optimized client and package a Release build of your App:

```bash
$ npm run publish
```

Which will publish your App to `bin/Release/netcoreapp3.1/publish` ready for deployment.

#### Testing

The major JS Framework Templates are also pre-configured with their preferred unit testing solution which are run with npm's `test` command:

```bash
$ npm test
```

Whilst Vue and Angular also include support for running end-to-end integration tests in a browser:

```bash
$ npm run e2e
```

This also highlights one of the benefits of utilizing npm's vibrant ecosystem where it benefits from significant investments like [cypress.io](https://www.cypress.io) which provides a complete solution for running integration tests:

![](/img/pages/ssvs/vue/cypress.png)

### Parcel SPA Template

[![](https://raw.githubusercontent.com/ServiceStack/Assets/master/csharp-templates/parcel.png)](https://github.com/NetCoreTemplates/parcel)

Create new Parcel Template:

```bash
$ x new parcel ProjectName
```

[Parcel](https://parceljs.org) aims to provide the simplest out-of-the-box development experience for creating modern npm-powered 
Web Apps by getting out of your way and letting you develop Websites without regard for a bundling solution or JS Framework. 

To enlist its functionality you just point `parcel` to your home page:

```bash
$ parcel index.html
```

This starts a Live Hot Reload Server which inspects all linked `*.html`, script and stylesheet resources to find all dependencies which it automatically 
monitors for changes where it will automatically rebuild and reload your webpage. Then when it's time for deployment you can perform a production build
for your website with the `build` command:

```bash
$ parcel build index.html
```

Where it creates an optimized bundle using advanced minification, compilation and bundling techniques. Despite its instant utility and zero configuration,
it comes pre-configured with [popular auto transforms](https://parceljs.org/transforms.html) for developing modern Web Apps which lets you utilize 
PostCSS transforms and advanced transpilers like TypeScript which the new Parcel Template takes advantage of to enable a pleasant development experience 
by enabling access to the latest ES7/TypeScript language features.

This template starts from a clean slate and does not use any of the [popular JavaScript frameworks](https://github.com/NetCoreTemplates) making it 
ideal when wanting to use any other [micro JS libraries](http://microjs.com) that can be referenced using a simple script include - reminiscent of 
simpler times.

Or [develop without a JS framework](https://twitter.com/mislav/status/1022058279000842240), e.g. [index.ts](https://github.com/NetCoreTemplates/parcel/blob/master/MyApp/src/index.ts) below uses TypeScript and the native HTML DOM APIs for its functionality:

```ts
import { client } from "./shared";
import { Hello } from "./dtos";

const result = document.querySelector("#result")!;

document.querySelector("#Name")!.addEventListener("input", async e => {
  const value = (e.target as HTMLInputElement).value;
  if (value != "") {
    const request = new Hello();
    request.name = value;
    const response = await client.get(request);
    result.innerHTML = response.result;
  } else {
    result.innerHTML = "";
  }
});
```

The Parcel Template also includes customizations to integrate it with .NET Core Project conventions and 
[Sharp Pages](https://sharpscript.net/docs/script-pages) Website enabling access to additional flexibility like dynamic Web Pages and server-side rendering
when needed. See the [Parcel Template docs](https://github.com/NetCoreTemplates/parcel#development-workflow) for information on the
available `dev`, `build`, `dtos` and `publish` npm scripts used to manage the Development workflow.

Seamless Parcel integration is another example of the benefits of `#Script` layered approach and non-intrusive handlebars syntax which 
can be cleanly embedded in existing `.html` pages without interfering with static HTML analyzers like parcel and Webpack HTML plugins and their 
resulting HTML minification in optimized production builds - enabling simplified development workflows and integration that's not possible with Razor.

### Running .NET Core Templates in Visual Studio IIS Express

Currently VS.NET doesn't support .NET 8.0 multiple bindings i.e. `http://localhost:5000/;https://localhost:5001/` which all .NET Core Templates
are configured with. To run in IIS Express change it to specify only 1 binding:

![](https://forums.servicestack.net/uploads/default/931/0a2191581d2774c6.png)

Also if you wanted to re-use an existing registered port like `5000` you will need to run VS.NET in **Administrator** mode where it will let you override
any existing registrations, alternatively you can replace the port with an unused port number which will let you run it as normal.


# Nuxt Project Templates
Source: https://docs.servicestack.net/templates/nuxt

<div class="not-prose my-8 ml-20 flex justify-center"><svg style="max-width:200px" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 400 298"><g fill="none" fill-rule="nonzero"><path fill="#00C58E" d="M227.92099 82.07407l-13.6889 23.7037-46.8148-81.08641L23.7037 273.58025h97.3037c0 13.0912 10.61252 23.7037 23.70371 23.7037H23.70371c-8.46771 0-16.29145-4.52017-20.5246-11.85382-4.23315-7.33366-4.23272-16.36849.00114-23.70174L146.89383 12.83951c4.23415-7.33433 12.0596-11.85252 20.5284-11.85252 8.46878 0 16.29423 4.51819 20.52839 11.85252l39.97037 69.23456z"/><path fill="#2F495E" d="M331.6642 261.7284l-90.05432-155.95062-13.6889-23.7037-13.68888 23.7037-90.04445 155.95061c-4.23385 7.33325-4.23428 16.36808-.00113 23.70174 4.23314 7.33365 12.05689 11.85382 20.5246 11.85382h166.4c8.46946 0 16.29644-4.51525 20.532-11.84955 4.23555-7.3343 4.23606-16.37123.00132-23.706h.01976zM144.7111 273.58024L227.921 129.48148l83.19012 144.09877h-166.4z"/><path fill="#108775" d="M396.04938 285.4321c-4.23344 7.33254-12.05656 11.85185-20.52345 11.85185H311.1111c13.0912 0 23.7037-10.6125 23.7037-23.7037h40.66173L260.09877 73.74815l-18.4889 32.02963-13.68888-23.7037L239.5753 61.8963c4.23416-7.33433 12.0596-11.85252 20.5284-11.85252 8.46879 0 16.29423 4.51819 20.52839 11.85252l115.41728 199.8321c4.23426 7.33395 4.23426 16.36975 0 23.7037z"/></g></svg></div>

[Nuxt.js](https://nuxtjs.org) is an exciting opinionated structured framework for rapidly developing Web Applications in a single unified solution pre-configured with Vue's high-quality components that abstracts away the complex build systems of Webpack powered JS Apps.

If you've been intimidated with amount of complexity and knowledge required to develop an App using one of the major JS frameworks, we highly recommend evaluating Nuxt.js. Nuxt is an opinionated framework that integrates the most popular Vue components together in a pre-configured solution. It's like developing within guard rails where it lets you develop entire websites using just [Vue Single File Components](https://vuejs.org/v2/guide/single-file-components.html) placed in a [conventional file and directory structure](https://nuxtjs.org/guide/routing) where Nuxt will take care of managing the routing and abstracts away the build configuration to generate optimal production builds where it employs advanced packaging techniques like automatic code splitting, link prefetching, SPA navigation of statically-generated cacheable assets and integrated support for ES6/7 transpilation, linting and js/css bundling and minification.

Its watched builds enables Hot Module Replacement to enable the optimal development experience where it you will be able to see changes in real-time without needing to manually build or refresh pages. The Nuxt templates are also configured to support [.NET Core's watched builds](/templates/websites#watched-net-core-builds) which automatically detects changes to your .NET Core App and re-compiles and restarts them with the new changes. 

[![](https://raw.githubusercontent.com/ServiceStack/Assets/master/csharp-templates/vue-nuxt.png)](https://github.com/NetCoreTemplates/vue-nuxt)

### ServiceStack Integration

Whilst Nuxt and ServiceStack are 2 different frameworks, we've combined them in a single seamlessly integrated .NET Core project. ServiceStack shines here where as the [TypeScript JsonServiceClient](/typescript-add-servicestack-reference#typescript-serviceclient) utilizes ServiceStack's [pre-defined Routes](/routing#pre-defined-routes) we can proxy all JSON API requests to our .NET Core App with a single config in [nuxt.config.js](https://github.com/NetCoreTemplates/vue-nuxt/blob/master/MyApp/nuxt.config.js) and an additional entry to proxy links to any configured [OAuth Providers](/auth/authentication-and-authorization#oauth-providers):

```js
  proxy: {
    '/json': 'http://localhost:5000/',
    '/auth': 'http://localhost:5000/',
  },
```

This lets us use Nuxt's Web Dev Server during development to take advantage of its incremental compilation, Live Reloading and instant UI updates. 

### Nuxt Templates 

There are 2 variants of Nuxt templates available for both .NET Core and .NET Framework:

[![](https://raw.githubusercontent.com/ServiceStack/Assets/master/csharp-templates/vue-nuxt.png)](https://github.com/NetCoreTemplates/vue-nuxt)

#### .NET Core

  - [vue-nuxt](https://github.com/NetCoreTemplates/vue-nuxt) - Vue + Nuxt
  - [vuetify-nuxt](https://github.com/NetCoreTemplates/vuetify-nuxt) - Vue + Nuxt + Vuetify

#### .NET Framework

  - [vue-nuxt-netfx](https://github.com/NetFrameworkTemplates/vue-nuxt-netfx) - Vue + Nuxt
  - [vuetify-nuxt-netfx](https://github.com/NetFrameworkTemplates/vuetify-nuxt-netfx) - Vue + Nuxt + Vuetify

### Getting Started 

To experience App development with Nuxt.js, create a new Nuxt Project using [x new](/web-new):

```bash
$ x new vue-nuxt ProjectName
```

Download npm and .NET Core dependencies:

```bash
$ npm install
$ dotnet restore
```

### Dev Workflow

Start a [watched .NET Core build](/templates/websites#watched-net-core-builds) in the background from the command-line with:

```bash
$ dotnet watch run
```

In a new terminal window start a watched Nuxt dev server build with:

```bash
$ npm run dev
```

Then open `http://localhost:3000` in your browser to view your App served directly from Nuxt's dev server which will proxy all Server requests to ServiceStack Server running on `http://localhost:5000`. Any changes you make to your front-end will be automatically re-compiled and reloaded by the watched `Nuxt` build whilst any changes to your Server app will be automatically be rebuilt and restarted by the watched `dotnet` process.

### Update DTOs

Whilst Nuxt is a JavaScript (ES 6/7) App it still benefits from ServiceStack's [TypeScript Add Reference feature](/typescript-add-servicestack-reference) where you can generate typed DTOs with the `dtos` npm script:

```bash
$ npm run dtos
```

This will update the Servers `dtos.ts` and generate its corresponding `dtos.js` which can be natively imported as seen in 
[gateway.js](https://github.com/NetCoreTemplates/vue-nuxt/blob/master/MyApp/src/shared/gateway.js#L3). Despite the App not being built with TypeScript, developing using a "TypeScript-aware" IDE like VS Code will still be able to utilize the generated `dtos.ts` to provide a rich intelli-sense experience.

### Generate Static Production Build

Most of the time during development you'll be viewing your App through Nuxt's dev server to take advantage of it's instant UI updates. At any time you can also view a production build of your App with:

```bash
$ npm run build
```

This will generate a static encapsulated production build of your App in .NET Core's `/wwwroot` which you can view served from your ServiceStack Server App directly at:

    http://localhost:5000


### Publishing App for Deployment

To create a complete client and server build of your App run:

```bash
$ npm run publish
```

This publishes your App to `bin/Release/netcoreapp3.1/publish` that can then be deployed like any normal .NET Core App.

### Host static content on Netlify's CDN for free

One of the advantages of using Nuxt is that it generates a front-end UI with static `.html` files for all pages. This allows the static content of your Web App to be cleanly decoupled from your back-end your Server App and hosted independently on a CDN. Netlify makes this effortless where you can [Sign In with your GitHub account](https://app.netlify.com/signup) and get it to create a new Site from a GitHub repository where you can tell it to host the static content in your .NET Core Apps `/wwwroot` folder on its CDN. It also synchronizes updates with every check-in so it automatically updates whenever you check-in a new version of your .NET Core project. 

Netlify has built first-class support for hosting Single Page Apps like Nuxt where it lets you check-in a [simple _redirects file](https://www.netlify.com/docs/redirects/) with all routes you want to be served by your .NET Core App and it will transparently proxy any API requests to your back-end server without needing to enable CORS. So the same .NET Core App that runs locally will be able to run without code changes when deployed despite having all its bandwidth intensive content served directly from Netlify's CDN. This opens up a nice scalability option for your App Servers, maximizing their efficiency as .NET Core Apps just ends up serving dynamic JSON API requests.


# Svelte Project Templates
Source: https://docs.servicestack.net/templates/svelte

<div class="not-prose my-8 ml-20 flex justify-center"><svg style="max-width:200px" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" x="0px" y="0px"
	 viewBox="0 0 98.1 118" xml:space="preserve">
<path fill="#FF3E00" d="M91.8,15.6C80.9-0.1,59.2-4.7,43.6,5.2L16.1,22.8C8.6,27.5,3.4,35.2,1.9,43.9c-1.3,7.3-0.2,14.8,3.3,21.3
	c-2.4,3.6-4,7.6-4.7,11.8c-1.6,8.9,0.5,18.1,5.7,25.4c11,15.7,32.6,20.3,48.2,10.4l27.5-17.5c7.5-4.7,12.7-12.4,14.2-21.1
	c1.3-7.3,0.2-14.8-3.3-21.3c2.4-3.6,4-7.6,4.7-11.8C99.2,32.1,97.1,22.9,91.8,15.6"/>
<path fill="#FFFFFF" d="M40.9,103.9c-8.9,2.3-18.2-1.2-23.4-8.7c-3.2-4.4-4.4-9.9-3.5-15.3c0.2-0.9,0.4-1.7,0.6-2.6l0.5-1.6l1.4,1
	c3.3,2.4,6.9,4.2,10.8,5.4l1,0.3l-0.1,1c-0.1,1.4,0.3,2.9,1.1,4.1c1.6,2.3,4.4,3.4,7.1,2.7c0.6-0.2,1.2-0.4,1.7-0.7L65.5,72
	c1.4-0.9,2.3-2.2,2.6-3.8c0.3-1.6-0.1-3.3-1-4.6c-1.6-2.3-4.4-3.3-7.1-2.6c-0.6,0.2-1.2,0.4-1.7,0.7l-10.5,6.7
	c-1.7,1.1-3.6,1.9-5.6,2.4c-8.9,2.3-18.2-1.2-23.4-8.7c-3.1-4.4-4.4-9.9-3.4-15.3c0.9-5.2,4.1-9.9,8.6-12.7l27.5-17.5
	c1.7-1.1,3.6-1.9,5.6-2.5c8.9-2.3,18.2,1.2,23.4,8.7c3.2,4.4,4.4,9.9,3.5,15.3c-0.2,0.9-0.4,1.7-0.7,2.6l-0.5,1.6l-1.4-1
	c-3.3-2.4-6.9-4.2-10.8-5.4l-1-0.3l0.1-1c0.1-1.4-0.3-2.9-1.1-4.1c-1.6-2.3-4.4-3.3-7.1-2.6c-0.6,0.2-1.2,0.4-1.7,0.7L32.4,46.1
	c-1.4,0.9-2.3,2.2-2.6,3.8s0.1,3.3,1,4.6c1.6,2.3,4.4,3.3,7.1,2.6c0.6-0.2,1.2-0.4,1.7-0.7l10.5-6.7c1.7-1.1,3.6-1.9,5.6-2.5
	c8.9-2.3,18.2,1.2,23.4,8.7c3.2,4.4,4.4,9.9,3.5,15.3c-0.9,5.2-4.1,9.9-8.6,12.7l-27.5,17.5C44.8,102.5,42.9,103.3,40.9,103.9"/>
</svg></div>

[Svelte](https://svelte.dev/) is a radical new approach to building user interfaces. Whereas traditional frameworks like React and Vue do the bulk of their work in the browser, Svelte shifts that work into a compile step that happens when you build your app.

Instead of using techniques like virtual DOM diffing, Svelte writes code that surgically updates the DOM when the state of your app changes.

[Read the introductory blog post](https://svelte.dev/blog/svelte-3-rethinking-reactivity) to learn more.

## Svelte .NET Core Single Page App Templates

.NET 6.0 svelte v3 rollup App Project Template integrated with ServiceStack Services and built-in Routing, User Registration and Sign Up forms.

![](https://raw.githubusercontent.com/ServiceStack/Assets/master/csharp-templates/svelte-spa.png)

> Browse [source code](https://github.com/NetCoreTemplates/svelte-spa) and install with [dotnet-new](/dotnet-new):

```bash
$ dotnet tool install -g x
```

```bash
$ x new svelte-spa ProjectName
```

## Development workflow

[![](https://raw.githubusercontent.com/ServiceStack/Assets/master/img/screencasts/svelte-spa-youtube.png)](https://youtu.be/cKlFABFECnQ)

::: info YouTube
[youtu.be/cKlFABFECnQ](https://youtu.be/cKlFABFECnQ)
:::

Run the `dev` npm script or Gulp task and leave it running in the background:

```bash
$ npm run dev
```

This initially generates a full development build of your Web App then stays running in the background to process files as they’re changed. This enables the normal dev workflow of running your ASP.NET Web App, saving changes locally which are then reloaded using ServiceStack’s built-in hot reloading. Alternatively hitting `F5` will refresh the page and view the latest changes.

Each change updates the output dev resources so even if you stop the dev task your Web App remains in a working state that’s viewable when running the ASP.NET Web App.

### Watched .NET Core builds

.NET Core projects can also benefit from Live Coding using dotnet watch which performs a “watched build” where it automatically stops, recompiles and restarts your .NET Core App when it detects source file changes. You can start a watched build from the command-line with:

```bash
$ dotnet watch run
```

### Create a production build

Run the `build` npm script or gulp task to generate a static production build of your App saved to your .NET App's `/wwwroot` folder:

```bash
$ npm run build
```

This will let you run the production build of your App that's hosted by your .NET App.

### Updating Server TypeScript DTOs

Run the `dtos` npm script or Gulp task to update your server dtos in `/src/dtos.ts`:

```bash
$ npm run dtos
```

### Deployments

When your App is ready to deploy, run the `publish` npm (or Gulp) script to package your App for deployment:

```bash
$ npm run publish
```

Which will create a production build of your App which then runs `dotnet publish -c Release` to Publish a Release build of your App in the `/bin/netcoreapp3.1/publish` folder which can then copied to remote server or an included in a Docker container to deploy your App.

## Svelte template

This project was bootstrapped with [sveltejs/template](https://github.com/sveltejs/template). To learn more about Svelte we recommend going through 
[Svelte's interactive tutorial](https://svelte.dev/tutorial/basics).


# Angular Bootstrap Project Template
Source: https://docs.servicestack.net/templates/angular-bootstrap

<div class="not-prose my-8 ml-20 flex justify-center"><svg style="max-width:200px" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" x="0px" y="0px"
	 viewBox="0 0 250 250" xml:space="preserve">
<g>
	<polygon fill="#DD0031" points="125,30 125,30 125,30 31.9,63.2 46.1,186.3 125,230 125,230 125,230 203.9,186.3 218.1,63.2 	"/>
	<polygon fill="#C3002F" points="125,30 125,52.2 125,52.1 125,153.4 125,153.4 125,230 125,230 203.9,186.3 218.1,63.2 125,30 	"/>
	<path fill="#FFFFFF" d="M125,52.1L66.8,182.6h0h21.7h0l11.7-29.2h49.4l11.7,29.2h0h21.7h0L125,52.1L125,52.1L125,52.1L125,52.1
		L125,52.1z M142,135.4H108l17-40.9L142,135.4z"/>
</g>
</svg></div>

[Angular](https://angular.io) is the premier JavaScript framework developed by Google for building applications that live on the web, mobile, or the desktop.

## Angular .NET Core and .NET Framework Single Page App Templates

The templates below have been bootstrapped with the latest angular-cli tooling that's 
[seamlessly integrated](/templates/single-page-apps#end-to-end-typed-apis) into 
ServiceStack's [Recommended Physical Project Structure](/physical-project-structure). 

See the documentation in each project for more info on features of each template:

### [Angular 15 SPA Template](https://github.com/LegacyTemplates/angular-spa)

.NET 8.0 Angular 15 project generated with [Angular CLI](https://github.com/angular/angular-spa).

![](https://raw.githubusercontent.com/ServiceStack/Assets/master/csharp-templates/angular-spa-bootstrap.png)

> Browse [source code](https://github.com/LegacyTemplates/angular-spa) and install with [x new](/web-new):

Create new Angular Project for .NET 8.0:

:::sh
x new LegacyTemplates/angular-spa ProjectName
:::

Create new Angular Project for .NET Framework:

:::sh
x new angular-spa-netfx ProjectName
:::


#### Angular HTTP Client

The Angular template uses Angular's built-in Rx-enabled HTTP Client with ServiceStack's ambient TypeScript declarations, as it's often preferable to utilize Angular's built-in dependencies when available.

ServiceStack's ambient TypeScript interfaces are leveraged to enable a Typed API, whilst the `createUrl(route,args)` helper lets you reuse your APIs Route definitions (emitted in comments above each Request DTO) to provide a pleasant UX for making API calls using Angular's HTTP Client:

```ts
import { createUrl } from '@servicestack/client';
...

this.http.get<HelloResponse>(createUrl('/hello/{Name}', { name })).subscribe(r => {
    this.result = r.result;
});
```

# Angular Examples

## [TechStacks](https://github.com/ServiceStackApps/TechStacks)

TechStacks is an AngularJS App that lets you explore TechStacks of popular StartUps using your favorite technology

[![TechStacks](https://raw.githubusercontent.com/ServiceStack/Assets/master/img/livedemos/techstacks/screenshots/techstacks.png)](https://github.com/ServiceStackApps/TechStacks)

#### Features 

TechStacks is based on a [Bootstrap template](http://getbootstrap.com) with client-side features:

 - HTML5 Routing to enable pretty urls, also supports full page reloads and back button support
 - Same Services supporting both human-readable Slugs or int primary keys
 - Responsive design supporting iPad Landscape and Portrait modes
 - Preloading and background data fetching to reduce flicker and maximize responsiveness
 - [Disqus](https://disqus.com/) commenting system
 - [Chosen](http://harvesthq.github.io/chosen/) for UX-friendly multi combo boxes

and some of TechStacks back-end features include: 

 - [SEO-optimized, Server HTML generated, read-only version of the website](https://techstacks.io/?html=server)
   - Dynamically generated [sitemaps.xml](https://techstacks.io/sitemap.xml)
 - Page-level Locking
 - Record and Restore Page Content Versioning
 - [Twitter and GitHub OAuth Providers](/auth/authentication-and-authorization)
 - Substitutable [OrmLite](https://github.com/ServiceStack/ServiceStack.OrmLite) RDBMS [PostgreSQL and Sqlite](https://github.com/ServiceStackApps/TechStacks/blob/875e78910e43d2230f0925b71d5990497216511e/src/TechStacks/TechStacks/AppHost.cs#L49-L56) back-ends
 - [Auto Query](/autoquery/) for automatic services of RDBMS tables
 - [RDBMS Sessions and In Memory Caching](/caching)
 - [Fluent Validation](/validation)


# AWS Project Templates
Source: https://docs.servicestack.net/templates/aws

<div class="not-prose my-8 ml-20 flex justify-center"><svg style="max-width:200px" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" x="0px" y="0px"
	 viewBox="0 0 364.707 364.707" enable-background="new 0 0 364.707 364.707"
	 xml:space="preserve">
<path fill="#F37B21" d="M223.864,272.729l-38.608-97.848l-56.603,89.184H93.166l79.052-127.654l-8.875-25.229h-30.781V81.12h52.691
	l60.521,153.899l26.608-8.668l8.867,29.813L223.864,272.729z"/>
<path fill="none" stroke="#F37B21" stroke-width="34" d="M337.623,182.198c0,85.579-69.363,154.934-154.934,154.934
	c-85.571,0-154.936-69.354-154.936-154.934c0-85.569,69.363-154.933,154.936-154.933C268.259,27.265,337.623,96.629,337.623,182.198 z"/>
</svg></div>

.NET 6.0 Amazon AWS Lambda Container Project Template

## aws-lambda

<lite-youtube class="w-full mx-4 my-4" width="560" height="315" videoid="8mpGNTsSlvE" style="background-image: url('https://img.youtube.com/vi/8mpGNTsSlvE/maxresdefault.jpg')"></lite-youtube>

> YouTube: [https://youtu.be/8mpGNTsSlvE](https://youtu.be/8mpGNTsSlvE)

This project lets you create a .NET 6 empty ServiceStack web project ready for deployment as a AWS Lambda Function wired with API GateWay and packaged via a Docker image.

Create new project with [x dotnet tool](/dotnet-new):

```bash
$ dotnet tool install -g x
$ x new aws-lambda ProjectName
```

### Prerequisites

- [.NET Core SDK 3.1 (runtime 5.0+) or higher](https://dotnet.microsoft.com/download/dotnet-core/3.1)
- [AWS .NET Core CLI](https://docs.aws.amazon.com/lambda/latest/dg/csharp-package-cli.html)
- [AWS account](https://aws.amazon.com/free/)

### Built with GitHub Actions

The above pre-requisites are setup ready to use with this template via GitHub Actions.

GitHub Actions need to authenticate with AWS required to deploy your application. To enable this you'll need to setup an IAM account specifically to enable this. This IAM account will need the permissions required to create and manage all the related AWS resources.

Below is an example of a IAM policy for a 'deploy' user that will be able to use the `serverless.template` CloudFormation file with AWS .NET Core CLI.

```json
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "VisualEditor0",
      "Effect": "Allow",
      "Action": [
        "lambda:CreateFunction",
        "lambda:TagResource",
        "lambda:AddPermission",
        "lambda:ListFunctions",
        "lambda:InvokeFunction",
        "lambda:InvokeAsync",
        "lambda:GetFunctionConfiguration",
        "lambda:GetFunction",
        "lambda:UpdateAlias",
        "lambda:UpdateFunctionCode",
        "lambda:DeleteAlias",
        "lambda:DeleteFunction",
        "lambda:PublishVersion",
        "lambda:CreateAlias",
        "iam:DeleteRole",
        "iam:CreateRole",
        "iam:AttachRolePolicy",
        "iam:GetRole",
        "iam:PassRole",
        "iam:DetachRolePolicy",
        "cloudformation:*",
        "apigateway:*",
        "ecr:UploadLayerPart",
        "ecr:CompleteLayerUpload",
        "ecr:DescribeRepositories",
        "ecr:BatchCheckLayerAvailability",
        "ecr:CreateRepository",
        "ecr:GetDownloadUrlForLayer",
        "ecr:GetAuthorizationToken",
        "ecr:PutImage",
        "ecr:SetRepositoryPolicy",
        "ecr:BatchGetImage",
        "ecr:InitiateLayerUpload",
        "ecr:GetRepositoryPolicy"
      ],
      "Resource": "*"
    }
  ]
}
```

### Use Case for ServiceStack App on AWS Lambda
AWS Lambda Containers allows the use of standard docker tooling with AWS serverless offering which for low traffic volume applications or APIs can be an extremely cost effective way of hosting an application.

AWS provides a Lambda [free-tier of 1M requests and 400,000GB-seconds of compute time per month](https://aws.amazon.com/lambda/pricing/). This can be enough traffic for many full ServiceStack APIs or applications.

### Deployment process
The provided GitHub Action YAML configures a workflow to build, test, package and deploy your ServiceStack Application with AWS Lambda and API GateWay.

Additional configuration is needed to get your application accessible from a friendly name subdomain. This can be done with API GateWay Mapping and Route 53.

### Public access via custom subdomain
If you want to use this ServiceStack app external from AWS, you'll need create a "Custom Domain" within API GateWay and setup an `A` record in Route53 to a hosted zone.

 - Navigate to [API GateWay AWS Console](https://console.aws.amazon.com/apigateway/main/publish/domain-names).
 - Select "Create" and specify the domain name and provide associated TLS certificate. If you don't yet have one, one can be created via AWS Certificate Manager or provided directly to this UI.
 - Once created, configure an API Mapping.
 - Specify the API Gateway and Stage.
 - View configuration and look for `API Gateway domain name`, copy this value ready for use in Route 53 configuration.
 - Select the hosted zone related to your subdomain in Route 53
 - Create an `A` record pointing to your `API Gateway domain name` copied from previous step

Your application should now be viewable from your custom domain!

### AWS Lambda Cold starts
Just like any AWS Lambda application or function, the latency impacts of 'cold starts' are something that can impact user experience significantly depending on your expected traffic load. When your function hasn't received any traffic for while, AWS Lambda will stop your container. Once a new request comes in, AWS Lambda needs to start up your application and wait for it to be ready to take your request. This creates the cold start latency problem. This also happens when there are already too many concurrent requests, to handle the increased load AWS Lambda will create new instances of your container to handle those requests.

If your load is low and expected, you can use tools like uptimerobot or others to periodically hit your application endpoint to keep at least one container alive to reduce this cold start latency.

Alternatively [AWS Provisioned Capacity](https://aws.amazon.com/blogs/aws/new-provisioned-concurrency-for-lambda-functions/) can be used (at additional cost) to mitigate these limitations.


# Desktop Project Templates
Source: https://docs.servicestack.net/templates/desktop

<div class="not-prose my-8 ml-20 flex justify-center"><svg xmlns:dc="http://purl.org/dc/elements/1.1/"
    xmlns:cc="http://creativecommons.org/ns#"
    xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
    xmlns:svg="http://www.w3.org/2000/svg"
    xmlns="http://www.w3.org/2000/svg"
    xmlns:xlink="http://www.w3.org/1999/xlink" version="1.1" width="256" height="256" id="svg3039">
    <defs id="defs3043">
        <linearGradient id="linearGradient3803">
            <stop style="stop-color:#d7def0;stop-opacity:1;" offset="0" id="stop3805" />
            <stop id="stop3811" offset="0.5" style="stop-color:#ffffff;stop-opacity:1" />
            <stop style="stop-color:#d5def0;stop-opacity:1" offset="1" id="stop3807" />
        </linearGradient>
        <linearGradient id="linearGradient3776">
            <stop id="stop3778" offset="0" style="stop-color:#b2cde9;stop-opacity:1" />
            <stop id="stop3780" offset="1" style="stop-color:#c4dbee;stop-opacity:1" />
        </linearGradient>
        <linearGradient id="linearGradient3750">
            <stop id="stop3752" offset="0" style="stop-color:#d0e2f1;stop-opacity:1" />
            <stop style="stop-color:#cadef0;stop-opacity:1" offset="0.85580856" id="stop3756" />
            <stop id="stop3754" offset="1" style="stop-color:#95bee3;stop-opacity:1" />
        </linearGradient>
        <linearGradient id="linearGradient3708">
            <stop style="stop-color:#658db6;stop-opacity:1" offset="0" id="stop3710" />
            <stop id="stop3716" offset="0.76777935" style="stop-color:#527fab;stop-opacity:1;" />
            <stop style="stop-color:#4071a0;stop-opacity:1" offset="1" id="stop3712" />
        </linearGradient>
        <linearGradient id="linearGradient3698">
            <stop style="stop-color:#96d0e1;stop-opacity:1" offset="0" id="stop3700" />
            <stop id="stop3706" offset="0.67819428" style="stop-color:#89b7e1;stop-opacity:1" />
            <stop style="stop-color:#699dd3;stop-opacity:1" offset="1" id="stop3702" />
        </linearGradient>
        <linearGradient id="linearGradient3647">
            <stop style="stop-color:#3b79bc;stop-opacity:1;" offset="0" id="stop3649" />
            <stop style="stop-color:#94b8e0;stop-opacity:1" offset="1" id="stop3651" />
        </linearGradient>
        <linearGradient id="linearGradient3588">
            <stop style="stop-color:#ffffff;stop-opacity:1" offset="0" id="stop3590" />
            <stop style="stop-color:#000000;stop-opacity:0;" offset="1" id="stop3592" />
        </linearGradient>
        <radialGradient xlink:href="#linearGradient3588" id="radialGradient3594" cx="-118.77966" cy="121.49152" fx="-118.77966" fy="121.49152" r="25.491526" gradientUnits="userSpaceOnUse" gradientTransform="matrix(0.02177942,-0.95743591,0.97872327,0.02221687,-235.0993,5.0684454)" />
        <linearGradient xlink:href="#linearGradient3647" id="linearGradient3653" x1="-397.81323" y1="149.18764" x2="-397.55933" y2="51.355946" gradientUnits="userSpaceOnUse" />
        <radialGradient xlink:href="#linearGradient3698" id="radialGradient3704" cx="-383.2746" cy="217.91029" fx="-383.2746" fy="217.91029" r="59.401995" gradientTransform="matrix(-1.2861568,-0.08596317,0.11453678,-1.7136762,-425.01982,469.50099)" gradientUnits="userSpaceOnUse" />
        <radialGradient xlink:href="#linearGradient3708" id="radialGradient3714" cx="-123.5" cy="-11.570732" fx="-123.5" fy="-11.570732" r="95.627118" gradientTransform="matrix(-0.00756512,0.55751399,-1.0314585,-0.01398286,113.23967,103.212)" gradientUnits="userSpaceOnUse" />
        <radialGradient xlink:href="#linearGradient3750" id="radialGradient3748" cx="-94.87291" cy="165.27281" fx="-94.87291" fy="165.27281" r="60.481357" gradientTransform="matrix(0.81293878,1.6998003,-2.1519091,1.0291615,564.39485,118.47915)" gradientUnits="userSpaceOnUse" />
        <linearGradient xlink:href="#linearGradient3776" id="linearGradient3774" x1="162.07127" y1="85.239708" x2="220.76114" y2="78.875748" gradientUnits="userSpaceOnUse" gradientTransform="translate(3.3917128,7.418629)" />
        <linearGradient xlink:href="#linearGradient3803" id="linearGradient3809" x1="-382.04123" y1="37.280548" x2="-381.39438" y2="165.56691" gradientUnits="userSpaceOnUse" />
    </defs>
    <path style="fill:url(#radialGradient3594);fill-opacity:1;fill-rule:nonzero;stroke:none" id="path2814" d="m -92.745764,122.57627 a 25.491526,25.491526 0 1 1 -50.983056,0 25.491526,25.491526 0 1 1 50.983056,0 z" transform="matrix(4.680851,0,0,4.7978723,685.10478,-449.69946)" />
    <path style="fill:url(#linearGradient3774);fill-opacity:1;fill-rule:nonzero;stroke:none" d="m 232.17258,88.120422 c 0,15.673918 -19.79135,34.931518 -45.84395,34.931518 -26.0526,0 -59.92241,-16.08123 -59.92241,-31.755152 0,-15.673924 21.11981,-28.38015 47.17241,-28.38015 19.90254,0 46.36122,18.293224 56.45971,20.3521 0.79179,1.710571 1.36862,2.925087 2.13424,4.851684 z" id="path3655" />
    <path style="fill:#2e5c91;fill-opacity:1;fill-rule:nonzero;stroke:none" d="m 38.822019,65.971523 c 12.38148,-9.610993 35.314514,-1.245318 51.289554,19.334679 15.975027,20.579998 17.694937,51.065068 5.31349,60.676058 -12.38147,9.61099 -34.17571,-5.29155 -50.15074,-25.87156 -12.20392,-15.72181 -4.05062,-41.19089 -8.61646,-50.430553 0.61589,-1.122052 1.381696,-2.456607 2.164156,-3.708624 z" id="path3655-4-8" />
    <path style="fill:url(#radialGradient3714);fill-opacity:1;fill-rule:nonzero;stroke:none" d="m 230.04347,83.261765 c -7.0081,-0.03265 -61.07025,0.289575 -107.66568,0.0654 -17.371,5.108098 -31.704627,13.258827 -39.181777,29.154945 -5.33639,-4.54237 -40.74576,-42.215609 -44.40678,-46.440684 31.38983,-41.648805 74.528017,-45.559321 82.915257,-45.559321 8.38724,0 70.64407,-8.631855 108.33898,62.77966 z" id="path3596" sodipodi:nodetypes="ccccsc" />
    <path style="fill:#699dd3;fill-opacity:1;fill-rule:nonzero;stroke:none" d="m 117.12454,243.96815 c -12.49835,-9.45851 -14.5752,-36.93927 1.14635,-57.71356 15.72155,-20.77428 41.03582,-34.94753 53.53417,-25.48904 12.49834,9.4585 7.44792,38.96701 -8.27364,59.74129 -12.01027,15.87024 -35.4911,16.88498 -43.22681,23.69505 -1.23894,-0.0455 -1.95523,-0.0605 -3.18007,-0.23374 z" id="path3655-4" />
    <path style="fill:url(#radialGradient3748);fill-opacity:1;fill-rule:nonzero;stroke:none" d="m 120.3032,244.20103 c 3.58354,-6.02268 28.85859,-52.8991 52.69131,-92.9389 4.41104,-17.56095 5.34663,-33.64185 -4.5584,-48.14993 6.62173,-2.29412 58.23852,-13.976353 63.73684,-14.987686 19.9656,48.180076 1.44992,87.338276 -2.80522,94.565966 -4.25515,7.22768 -28.40179,65.25666 -109.06453,61.51055 z" id="path3596-1" sodipodi:nodetypes="ccccsc" />
    <path style="fill:url(#radialGradient3704);fill-opacity:1;fill-rule:nonzero;stroke:none" d="m 36.696853,69.642524 c 3.46858,6.089612 30.72312,52.780196 53.77852,93.272576 13.094367,12.50527 27.684997,19.48512 45.191737,18.03328 -1.2738,6.89113 -16.62898,57.75037 -18.4638,63.03126 -51.756237,-6.42158 -76.669777,-41.85476 -80.854757,-49.1233 -4.18497,-7.26855 -42.7297502,-56.91452 0.3483,-125.213816 z" id="path3596-1-7" sodipodi:nodetypes="ccccsc" />
    <path transform="matrix(0.77294737,0,0,0.77619098,435.90647,53.275706)" style="fill:url(#linearGradient3653);fill-opacity:1;stroke:url(#linearGradient3809);stroke-width:10.07013607;stroke-miterlimit:4;stroke-opacity:1" d="m -338.44068,101.42373 c 0,32.65032 -26.46832,59.11864 -59.11865,59.11864 -32.65032,0 -59.11864,-26.46832 -59.11864,-59.11864 0,-32.650327 26.46832,-59.118646 59.11864,-59.118646 32.65033,0 59.11865,26.468319 59.11865,59.118646 z" id="path3645" />
    <path style="fill:#ffffff;fill-opacity:1;fill-rule:nonzero;stroke:none" d="m 163.54619,108.89582 c 18.52979,17.09836 16.03302,29.55794 10.0625,44 -3.10892,-22.25001 -2.34478,-32.42697 -10.0625,-44 z" id="rect3782" />
    <path style="fill:#ffffff;fill-opacity:1;fill-rule:nonzero;stroke:none" d="m 101.42092,173.63924 c -22.645593,-14.47335 -29.809884,-45.71983 -8.813354,-62.99032 -10.847561,19.77514 -6.225429,32.39863 8.813354,62.99032 z" id="rect3782-4" />
</svg>
</div>

## Vue .NET Core Windows Desktop App Template

The [vue-desktop](https://www.vuedesktop.com) Project Template lets you create .NET Core Vue Single Page Apps 
that can also be packaged & deployed as [Gist Desktop Apps](https://sharpscript.net/sharp-apps/gist-desktop-apps) which is 
ideal for quickly & effortlessly creating & deploying small to medium .NET Core Windows Desktop Apps packaged within a 
Chromium Web Vue UI within minutes!

Create new project with [app dotnet tool](/netcore-windows-desktop):

```bash
$ dotnet tool install -g app
$ app new vue-desktop ProjectName
```

> YouTube: [youtu.be/kRnQSWdqH6U](https://youtu.be/kRnQSWdqH6U)

[![](/img/pages/app/vue-desktop/vuedesktop-screenshot.png)](https://youtu.be/kRnQSWdqH6U)

### Why Chromium Desktop Apps?

With the investment into advancing Web Browsers & Web technologies, many new modern Desktop Apps developed today like: 
Spotify, VS Code, GitHub Desktop, Skype, Slack, Discord, Whats App, Microsoft Teams, etc.
are being built using Web Technologies and rendered with a Chromium webview, using either the popular [Electron Framework](https://www.electronjs.org/) 
or the [Chromium Embedded Framework (CEF)](http://opensource.spotify.com/cefbuilds/index.html) directly.

Following [VS Code frequent releases](https://code.visualstudio.com/updates/) makes it clear why they've decided on 
developing it with Web Technologies using Electron where they've been able to iterate faster and ship new features at 
an unprecedented pace. In addition to its superior productivity, they're able to effortlessly support multiple Operating Systems
as well as enable reuse for running on the Web as done with its [Monaco Editor](https://microsoft.github.io/monaco-editor/)
powering VS Code as well as innovative online solutions like [GitHub Code Spaces](https://github.com/features/codespaces).

These attributes in addition to the amount of investment that major technology companies like Google, Apple, Microsoft & 
Firefox invest each year in improving Web & browser technologies will ensure the platform will be continually supported
& improved unlike most Desktop UI Technologies. 

## Comparison with Blazor WASM

What technology to use for Chromium Desktop Apps?

The latest solution for building Single Page Apps being promoted for .NET is https://blazor.net/ where for Client Apps
suggests to use Blazor WASM which in an overview lets you run C# in the browser by running linked/tree-shaken .dll's in 
[interpreted mode](https://blog.stevensanderson.com/2018/02/06/blazor-intro/#interpreted-mode) by the dotnet runtime 
which is itself compiled & running as WASM. We can see a glimpse of this in action by viewing .dll's being loaded in the 
JS Debug Inspector: 

![](/img/pages/app/vue-desktop/blazor-jsdebug.png)

### Disadvantages of Blazor

The main value proposition of Blazor appears to be running C# in the browser, which while a technically impressive feat,
requires a tonne of complexity to achieve that results in worse end-user UX. It works using a development model based on 
Razor - a technology [we're not fond of](/why-not-razor) due to its reliance on 
heavy/complicated tooling and should be noted that historically whenever .NET invented their own development model
for the Web in ASP.NET Web Forms or Silverlight, they've ended up being abandoned.

Another reason we're not fond of technologies like Blazor is from experience in having to support "crippled" .NET Runtimes 
on platforms where only a subset of functionality of .NET is available, where we've lost untold time & effort trying to 
diagnose & track down runtime issues in Windows Phone, Silverlight & Xamarin iOS due to platform restrictions
([we're already seeing](https://forums.servicestack.net/t/possible-to-allow-setting-of-usecookies-property-in-jsonhttpclient/8618) reported in Blazor), 
differing implementation behavior or .NET libraries heavy use of reflection that's problematic in AOT environments.

Even without the drawbacks, going against the momentum of established Web UI Technologies like [Vue](https://github.com/vuejs/vue) 
& [React](https://github.com/facebook/react), their vibrant communities & [awesome ecosystems](https://github.com/vuejs/awesome-vue)
in favor of an uncertain foreign development model reliant on heavy/complex tooling that only a single vendor can provide 
serving only a single language ecosystem just to be able to use C# in the browser isn't a desirable goal as modern JS/TypeScript 
offer a more productive & enjoyable Reactive UI development model than any C#/XAML UI Framework we've used.

Ultimately as [staunch enemy's of complexity](/service-complexity-and-dto-roles) we're
philosophically against reliance on heavy complicated tooling and instead have adopted a Vue Chromium Desktop approach
for the development of [ServiceStack Studio](/studio) - an App that 
[wouldn't have been feasible](/releases/v5_9#highly-productive-live-reloading-development-experience)
if needing to use any C# & XAML UI FX or WinForms historically used to develop .NET Desktop Apps.  

### Blazor WASM Starting Project Template

But as it's the latest technology developed & promoted by .NET PR it's going to be the Web UI technology compared to most,
so this project template is based on the UI of an empty Blazor WASM project, rewritten to use Vue SPA UI & a back-end 
.NET Core App. It's an enhanced version that also includes examples of commonly useful features: 

  1. [Home page](https://github.com/NetCoreTemplates/vue-desktop/blob/master/src/components/Home.ts) includes example of using 
[TypeScript Service Reference](/typescript-add-servicestack-reference) to consume typed APIs  
  2. [Fetch data page](https://github.com/NetCoreTemplates/vue-desktop/blob/master/src/components/FetchData.ts) sources it's
data from an embedded SQLite database querying an [AutoQuery Service](/autoquery/rdbms)
  3. Utilizes [built-in SVG support](/svg) for using Material Design & Custom SVG Icons 
  4. Utilizes [Win 32 Integration](https://sharpscript.net/sharp-apps/win32) showcasing how to call Win32 APIs from the UI

#### Distributed App Size

The first comparison is a direct result of the approaches used in each technology, where in addition to all your App's 
assets Blazor WASM has to also bundle a dotnet WASM runtime & linked/tree-shaken .dll's. Whilst `app` Desktop Apps
is on opposite side of the spectrum where it only requires distribution of **App-specific functionality** as all popular 
Vue JS libraries, Bootstrap CSS, Material Design SVG icons or ServiceStack .dll's used are pre-bundled with the global `app` dotnet tool.

For the comparison we ran the `publish-app` script & Blazor's **Publish to Folder** tool & compared the **.zip** of each folder which resulted in:

#### `15kb` Vue Desktop App vs `6207kb` Blazor WASM (413x smaller)

The end result that even our **enhanced** Blazor WASM starting project template is **413.8x** or **2.6x** orders of magnitude smaller than Blazor WASM.
A more apt comparison of its tiny footprint, is the enhanced Vue Desktop App is roughly equivalent to 
[Blazor WASM's 12kb partial screenshot of its App](https://docs.microsoft.com/en-us/aspnet/core/blazor/?view=aspnetcore-3.1): 

![](https://docs.microsoft.com/en-us/aspnet/core/blazor/index/_static/dialog.png?view=aspnetcore-3.1)

In addition, the `app` tool also bundles a Chromium Desktop App shell in order for your Vue Desktop Apps to appear like Native Desktop Apps, 
to get the same experience with Blazor WASM App you would also need to manage the installation of a Chromium wrapper like 
[Chromely](https://github.com/chromelyapps/Chromely). 

When App sizes are this small you have a lot more flexibility in how to distribute & manage the App, which is how Vue Desktop Apps
can be published to Gists and always download & open the latest released version - enabling **transparent updates by default**.  

#### Live Reload

A notable omission from a modern UI FX is there doesn't to be any kind of Live Reload capability for any page, including static **.html** or **.css** resources.

Vue Desktop Apps naive live reload feature works as you'd expect where the UI automatically refreshes on each file change, e.g:

![](/img/pages/app/vue-desktop/vuedesktop-livereload.gif)

This is a good example of why we prefer to avoid complex tooling as what's normally a [trivially implementable feature](/hot-reloading) 
requires much more effort & time to implement when you're reliant on a complex architecture & heavy tooling.

The only build tool required to enable Live Reload in Vue Desktop Apps is TypeScript's watch feature which monitors and automatically 
transpiles all `*.ts` file changes: 

```bash
$ tsc -w
```

#### Reload Time

The lack of a live reload feature is exacerbated when having to manually reload your App to view every change which has
noticeable delay in Blazor WASM which is otherwise instant in a normal .NET Core Web App:

#### Blazor WASM
![](/img/pages/app/vue-desktop/blazorwasm-refresh.gif)

#### Vue Desktop
![](/img/pages/app/vue-desktop/vuedesktop-refresh.gif)

### Opinionated App Launcher

The `app` dotnet tool is essentially just a .NET Core Desktop App launcher hosted within a Chromium Desktop Shell, 
whether it's launching our [app Desktop Apps](https://sharpscript.net/sharp-apps/) or existing 
[.NET Core Web App .dll or .exe's](/netcore-windows-desktop#launch-net-core-app-inside-a-windows-chromium-desktop-app).

It's opinionated in the shared libraries it includes, namely:
 - Vue, React & jQuery
 - Bootstrap CSS
 - Material Design & Fontawesome SVG icons
 - [ServiceStack .NET Packages](https://www.nuget.org/profiles/servicestack) & Dependencies

::: info
You can use your own client/server libraries but they'd need to be distributed with the App  
:::

Intended for developing small/medium Desktop Apps that can be published to a GitHub Gist (or repo) & opened over a URL, e,g:
[Redis Admin UI](https://sharpscript.net/sharp-apps/redis), generic [DB Viewer](https://sharpscript.net/sharp-apps/sharpdata)
or our [ServiceStack Studio](/studio) API Management tool which all package down to small footprints. 

Given you can [build & distribute an App within minutes](https://youtu.be/kRnQSWdqH6U), it's suitable for quick UI's around 
a single purpose Task you may want to distribute internally, e.g. a dynamic reporting viewer, edit forms, surveys, email composer, or
see the [Desktop App Index](https://sharpscript.net/sharp-apps/app-index) for other examples.

### FREE!

To remove friction & barriers to adoption all [app](/netcore-windows-desktop) and 
[x](/dotnet-tool) dotnet tools used to run all [Sharp and Gist Desktop Apps](https://sharpscript.net/sharp-apps/) 
utilize an unrestricted suite of [ServiceStack](https://servicestack.net) Software that can be developed & distributed free without a commercial license.

Should it be needed if exceeding [free-quotas](https://servicestack.net/download#free-quotas) (most [Sharp Apps](https://sharpscript.net/) don't) 
when developing locally as a .NET Core Web App (i.e. instead of running using the `app` tool), you can bypass any restrictions 
(from referencing ServiceStack's commercial NuGet packages) with a [Trial License Key](https://servicestack.net/trial).

#### Alternative Modern Desktop Solutions

We don't recommend this template for flagships Desktop App worked on by large teams, in that case you're better off building your own 
custom Chromium Desktop App bundle [as Spotify does](https://engineering.atspotify.com/2019/03/25/building-spotifys-new-web-player/) where
you're able to access full control over CEF APIs, it's rendering, integration and Chromium features.
If you're looking looking to Chromotize a .NET Core Desktop App you can use our [ServiceStack.CefGlue](https://github.com/ServiceStack/ServiceStack.CefGlue)
.NET Standard 2.0 NuGet package of the [CefGlue](https://gitlab.com/xiliumhq/chromiumembedded/cefglue) C# CEF Bindings project.

If you're not using .NET Core, [Electron](https://www.electronjs.org/) is the most likely best choice for building Desktop Apps with Web Technologies.  

If you'd also want to develop native iOS / Android Apps from a shared code-base then [Flutter Desktop](https://medium.com/flutter/flutter-and-desktop-3a0dd0f8353e)
is looking like the most promising technology under active development in that space.

## Overview of Gist Desktop Apps 

Whilst on the face of it [Gist Desktop Apps](https://sharpscript.net/sharp-apps/gist-desktop-apps) appear to be similar to 
Electron Apps that utilizes a .NET Core backend instead of Node.js, it employs a shared architecture where
all Apps are run with the same [app dotnet tool](/netcore-windows-desktop) installable with:

```bash
$ dotnet tool install -g app
```

Where it enables a number of unique features: 

### Ultra Lightweight Desktop Apps

Unlike Electron which bundles Chromium with every install, all [Sharp Desktop Apps](https://sharpscript.net/sharp-apps/) utilize the same 
[app dotnet tool](/netcore-windows-desktop) which in addition to the 
latest version of Chromium, also includes many popular .NET server + client JS/CSS framework libraries - 
saving Vue Desktop Apps from having to include them. This effectively reducing their footprint to just App-specific Server + Client logic, 
so whilst a Hello World Electron App can require **>100MB**, this Vue Desktop Project Template bundles down 
to a **15kb .zip** - which includes the 14kb uncompressed .NET Server **.dll**. 

### Launch Desktop Apps from URLs

Thanks to their light footprint Desktop Apps can be launched directly from URLs using the `app://` URL Scheme, e.g.
a modified version of this Project Template can be launched from:

<h4 id="app-vuedesktop" tabindex="-1"><a href="app://vuedesktop">app://vuedesktop</a> <a class="header-anchor" href="#app-vuedesktop" aria-hidden="true">#</a></h4>

Which uses the unique [global alias your app was published with](https://sharpscript.net/sharp-apps/gist-desktop-apps#publishing-gist-apps). 

### Deep Links

It's also possible to pass additional params to enable deep links into Apps 
[ServiceStack Studio utilizes](/studio#starting-servicestack-studio)
to be able download, run & immediately invoke App specific functionality like connecting to a remote site, e.g:

<h3><a href="app://studio?connect=https://localhost:5001">app://studio?connect=https://localhost:5001</a></h3>

### Create customized Apps by mixing in Gists

Another unique feature of Gist Desktop Apps is being able to mix in multiple files into the App's directory to
create custom App builds, e.g. the [SharpData](https://sharpscript.net/sharp-apps/sharpdata) generic RDBMS UI viewer
utilizes this feature to copy & immediately open an embedded SQLite database for querying: 

<ul>
    <li>
        <a href="app://sharpdata?mix=northwind.sharpdata">app://sharpdata?mix=northwind.sharpdata</a></li><li><a href="app://sharpdata?mix=chinook.sharpdata">app://sharpdata?mix=chinook.sharpdata</a>
    </li>
</ul>

### Launch from public or private GitHub Repos

If preferred Desktop Apps can also be published & launched directly from your GitHub Repo which can be launched with `app://{user}/{repo}`, e.g`:

<ul>
<li><strong><a href="app://sharp-apps/redis">app://sharp-apps/redis</a></strong> - Redis Admin App</li>
<li><strong><a href="app://sharp-apps/blog">app://sharp-apps/blog</a></strong> - SQLite powered Blog App</li>
<li><strong><a href="app://sharp-apps/spirals">app://sharp-apps/spirals</a></strong> - SVG Spirals App</li>
<li><strong><a href="app://sharp-apps/rockwind">app://sharp-apps/rockwind</a></strong> - Multi Layout CMS + DB Admin UI Example</li>
</ul>

> Can open by pasting above links in browsers URL as GitHub doesn't render links with custom URL Schemes

If your repo has published releases it will use your most recent release, otherwise it uses the master archive. 

### Private Repos & Gists

Apps can also be launched from private Gists and Repos by either having end users configure the GitHub Access Token
with access to the private gist or repo in the `GITHUB_TOKEN` Environment variable or can be specified in the URL
or command-line with: 

```bash
app://user/repo?token={GITHUB_TOKEN}
$ app open user/repo -token {GITHUB_TOKEN}
```

### Copy Directory

Another way to distribute & run Apps is to **XCOPY** the `/dist` folder which users can launch by running `app` command in 
the App's folder or by specifying the path to the app's `app.settings`, e.g: 

```bash
$ app C:\path\to\app\app.settings
```

Where you can also [create a Windows Shortcut](/netcore-windows-desktop#create-windows-desktop-shortcuts) 
for a more integrated Desktop App: 

```bash
$ cd C:\path\to\app
$ app shortcut
```

::: info Tip
Add `favicon.ico` to use your own icon in the shortcut
:::

### Cross Platform Support

Whilst the `app` dotnet tool is Windows-only, all Sharp Apps can also be run cross-platform on macOS/Linux with the 
[x dotnet tool](/dotnet-tool) where it will open in the users preferred browser, e.g:

```bash
$ x open vuedesktop 
```

### Always uses latest version

Thanks to their tiny footprints the default behavior is to always download & run the latest version of the App when 
published to a Gist or Repo which automatically happens when launching Apps using the `app://` URL Scheme or `app open` command.

If preferred you can save 1-3 seconds on an App's launch time by using the `app:` URL scheme or `app run` command where
it will instead load the previously downloaded version, e.g:

<h3><a href="app:vuedesktop">app:vuedesktop</a></h3>

```bash
$ app run vuedesktop
```

### Native Win32 API Interop

As [#Script](https://sharpscript.net/) is a scripting language utilizing JS syntax to invoke .NET APIs, the 
[Win 32 support](https://sharpscript.net/sharp-apps/win32) ends up being both simple & intuitive.

Where it calls the [CustomMethods.cs](https://github.com/NetCoreTemplates/vue-desktop/blob/master/CustomMethods.cs) .NET Win 32 APIs
(wrapped in a [#Script method](https://sharpscript.net/docs/methods)) directly from JS as done in 
[App.ts](https://github.com/NetCoreTemplates/vue-desktop/blob/master/src/App.ts) which can be invoked using JS syntax
using the `evaluateCode` TypeScript API, e.g:

```ts
import { evaluateCode } from '@servicestack/desktop';

await evaluateCode(`chooseColor()`);
await evaluateCode(`chooseColor('#336699')`);
```

The `app` dotnet tool already includes these [dotnet/pinvoke](https://github.com/dotnet/pinvoke) .NET Wrapper API NuGet packages
below so they can be used within your App without needing to distribute them with your App:

```xml
<PackageReference Include="PInvoke.AdvApi32" Version="0.6.49" />
<PackageReference Include="PInvoke.BCrypt" Version="0.6.49" />
<PackageReference Include="PInvoke.Crypt32" Version="0.6.49" />
<PackageReference Include="PInvoke.DwmApi" Version="0.6.49" />
<PackageReference Include="PInvoke.Gdi32" Version="0.6.49" />
<PackageReference Include="PInvoke.Hid" Version="0.6.49" />
<PackageReference Include="PInvoke.Kernel32" Version="0.6.49" />
<PackageReference Include="PInvoke.Magnification" Version="0.6.49" />
<PackageReference Include="PInvoke.MSCorEE" Version="0.6.49" />
<PackageReference Include="PInvoke.Msi" Version="0.6.49" />
<PackageReference Include="PInvoke.Fusion" Version="0.6.49" />
<PackageReference Include="PInvoke.NCrypt" Version="0.6.49" />
<PackageReference Include="PInvoke.NetApi32" Version="0.6.49" />
<PackageReference Include="PInvoke.NTDll" Version="0.6.49" />
<PackageReference Include="PInvoke.Psapi" Version="0.6.49" />
<PackageReference Include="PInvoke.SetupApi" Version="0.6.49" />
<PackageReference Include="PInvoke.Shell32" Version="0.6.49" />
<PackageReference Include="PInvoke.SHCore" Version="0.6.49" />
<PackageReference Include="PInvoke.User32" Version="0.6.49" />
<PackageReference Include="PInvoke.Userenv" Version="0.6.49" />
<PackageReference Include="PInvoke.UxTheme" Version="0.6.49" />
<PackageReference Include="PInvoke.WtsApi32" Version="0.6.49" />
```

See [Win32 App](https://sharpscript.net/sharp-apps/win32) for more info & examples on Win32 integration.

## Desktop or Server Deployments

Whilst this project template is intended for creating Desktop Apps, it's essentially just a .NET Core Web App wrapped 
in a shared Chromium Desktop Shell which means it can also be deployed the same as any other .NET Core Web App by
generating a published build:

```bash
$ dotnet publish -c Release
```

Then [copying the published release builds for Server deployments](/netcore-deploy-rsync).

### Development Model

To avoid needing to use webpack, npm or any other build tooling, Vue components are written in TypeScript
[Class-Style Vue Components](https://vuejs.org/v2/guide/typescript.html#Class-Style-Vue-Components)
utilizing annotations in [vue-class-component](https://github.com/vuejs/vue-class-component) & 
[vue-property-decorator](https://github.com/kaorun343/vue-property-decorator), e.g. here's Blazor WASM Counter Page:

```html
@page "/counter"

<h1>Counter</h1>

<p>Current count: @currentCount</p>

<button class="btn btn-primary" @onclick="IncrementCount">Click me</button>

@code {
    private int currentCount = 0;

    private void IncrementCount()
    {
        currentCount++;
    }
}
```

Written as a TypeScript Class-Style Vue Component:

```ts
@Component({ template:`
<div>
    <h1>Counter</h1>
    
    <p>Current count: {{currentCount}}</p>
    
    <button class="btn btn-primary" @click="incrementCount()">Click me</button>
</div>`})
export class Counter extends Vue {
    currentCount = 0;

    incrementCount() {
        this.currentCount++;
    }
}
```

::: info
Vue's integration with TypeScript is set to improve in Vue 3 which will be written in TypeScript
:::

### Typed DTOs

The typing benefits of C# is also available when using TypeScript with 
[type definitions](https://github.com/NetCoreTemplates/vue-desktop/tree/master/typings) available for all libraries
which provides rich intelli-sense & type checking during development. 

Thanks to ServiceStack's [Add TypeScript Reference](/typescript-add-servicestack-reference)
feature, Types are also available for your C# Services which can be updated by running 
[npm run dtos](https://github.com/NetCoreTemplates/vue-desktop/blob/master/package.json#L4) or `app ts` directly, e.g: 

    $ app ts

Which will update all [dtos.ts](https://github.com/NetCoreTemplates/vue-desktop/blob/master/src/shared/dtos.ts) TypeScript
Reference DTOs with the latest changes which can be used together with the [@servicestack/client](https://github.com/ServiceStack/servicestack-client)
generic Service Client to provide both a terse & typed API for consuming back-end end-to-end Typed C# APIs: 

```ts
import { Hello } from "../shared/dtos";
import { client } from "../shared";

@Component({ template:`
<div>
    <h1>Hello, world!</h1>
    Welcome to your new app.
    
    <div class="row mt-4 p-0">
        <div class="col col-3">
            <v-input placeholder="Your name" v-model="txtName" />
        </div>
        <h3 class="col col-5 result mt-2">{{ result }}</h3>
    </div>
</div>`})
export class Home extends Vue {
    public txtName: string = '';
    public result: string = '';

    @Watch('txtName')
    async onNameChanged(value: string, oldValue: string) {
        await this.nameChanged(value);
    }

    async nameChanged(name: string) {
        if (name) {
            const r = await client.get(new Hello({ name }));
            this.result = r.result;
        } else {
            this.result = '';
        }
    }
}
```

### AutoQuery Services

Another major productivity boost for rapidly developing data-driven APIs is [AutoQuery RDBMS](/autoquery/rdbms)
where you can simply **create queryable APIs by just declaratively defining** which fields you want to query using any of the 
[registered conventions](/autoquery/rdbms#implicit-conventions), e.g:

```csharp
[Route("/forecasts")]
[Route("/forecasts/{Id}")]
public class QueryWeatherForecasts : QueryDb<WeatherForecast>
{
    public int? Id { get; set; }
    public DateTime? BeforeDate { get; set; }
    public DateTime? AfterDate { get; set; }
    public int? BelowTemperatureC { get; set; }
    public int? AboveTemperatureC { get; set; }
}

public class WeatherForecast
{
    [AutoIncrement]
    public int Id { get; set; }
    public DateTime Date { get; set; }
    public int TemperatureC { get; set; }
    public string Summary { get; set; }
    public int TemperatureF => 32 + (int)(TemperatureC / 0.5556);
}
```

Which is all that's required for ServiceStack to automatically implement the Service where it has access to all standard Typed API metadata services 
like being included in the generated TypeScript client DTOs: 

```bash
$ npm run dtos 
```

Which [FetchData.ts](https://github.com/NetCoreTemplates/vue-desktop/blob/master/src/components/FetchData.ts) uses to power its 
dynamic Queryable UI by sending a populated `QueryWeatherForecasts` Request DTO configured with any filters and re-executed 
on every input change:

![](/img/pages/app/vue-desktop/vuedesktop-fetchdata.png)

```html
<form class="form-inline mb-2" @submit.prevent="">
    <label for="txtId">Filters: </label>
    <input class="form-control form-control-sm mx-1" type="number" placeholder="[Id]" v-model="id" @input="filter"> 
    <input type="date" v-model="afterDate" @change="filter">
    <input type="date" v-model="beforeDate" @change="filter">
    <input class="form-control form-control-sm mx-1" type="number" placeholder="Above (C)" v-model="aboveTemp" @input="filter">
    <input class="form-control form-control-sm mr-1" type="number" placeholder="Below (C)" v-model="belowTemp" @input="filter"> 
    <button class="btn btn-secondary btn-sm" @click="reset">reset</button>
</form>
```

Triggering a call to `filter()` to populate and resend the `QueryWeatherForecasts` Request DTO with the latest filters and update the `forecasts` Reactive UI Model: 

```ts
export class FetchData extends Vue {
    forecasts:WeatherForecast[]|null = null;

    id = '';
    beforeDate = '';
    afterDate = '';
    belowTemp = '';
    aboveTemp = '';

    async filter() {
        const request = new QueryWeatherForecasts();
        if (this.id) request.id = parseInt(this.id);
        if (this.beforeDate) request.beforeDate = this.beforeDate;
        if (this.afterDate) request.afterDate = this.afterDate;
        if (this.belowTemp) request.belowTemperatureC = parseInt(this.belowTemp);
        if (this.aboveTemp) request.aboveTemperatureC = parseInt(this.aboveTemp);
        this.forecasts = (await client.get(request)).results;
    }
}
```


### React Desktop Apps Template

[![React Desktop Apps](https://raw.githubusercontent.com/ServiceStack/Assets/master/img/gap/react-desktop-splash.png)](https://github.com/ServiceStackApps/ReactDesktopApps)

The React Desktop Template lets you take advantage the adaptiveness, navigation and deep-linking benefits of a 
Web-based UI, the productivity and responsiveness of the 
[React framework](https://reactjs.org) in a rich 
native experience and OS Integration possible from a Native Desktop App - all in a single VS .NET template which 
supports packaging your Web App into 4 different ASP.NET, Winforms, OSX Cocoa and cross-platform Console App Hosts:

<table class="table">
<tr>
    <th>.NET Framework</th>
    <th>React Desktop Apps Template</th>
</tr>
<tr>
    <td><a href="https://github.com/NetFrameworkTemplates/react-desktop-apps-netfx">react-desktop-apps-netfx</a></td>
    <td align="center">
        <a href="http://react-desktop-apps-netfx.web-templates.io"><img src="https://raw.githubusercontent.com/ServiceStack/Assets/master/csharp-templates/react-desktop-apps-netfx.png" width="500" /></a>
        <p><a href="http://react-desktop-apps-netfx.web-templates.io">react-desktop-apps-netfx.web-templates.io</a></p>
    </td>
</tr>
</table>

## Learn more

To learn more about how Webpack is used in this Template see [Tour of Webpack](/templates/webpack).


# Run ASP.NET Core Apps on the .NET Framework
Source: https://docs.servicestack.net/templates/corefx

![](https://raw.githubusercontent.com/ServiceStack/Assets/master/csharp-templates/web.png)

### Status of ASP.NET Core on .NET Framework

The last important Microsoft announcement concerning the future of ASP.NET Core 2.1 was that it would stop supporting 
[new versions of ASP.NET Core on the .NET Framework](https://github.com/aspnet/AspNetCore/issues/3753).
Whilst we disagreed against this decision which would've put out a large class of the existing ecosystems from participating 
in the new ASP.NET Core development model and many from staged migrations to .NET Core from commencing, we're happy to see 
[ASP.NET Core 2.1 LTS will enjoy the same indefinite level of support](https://github.com/aspnet/AspNetCore/issues/3753#issuecomment-438046364)
as the rest of the .NET Framework - which should come as great news to the 1/3 of our Customers who are still creating new 
[ASP.NET Core on FX Project Templates](https://github.com/NetFrameworkCoreTemplates).

Whilst this announcement sends a clear message that new development on .NET Framework has effectively been put on product life support, 
**ASP.NET Core 2.1 LTS** is still a great rock-solid platform to build on if you're unable to jump directly to **.NET Core** immediately or 
if you want to get off .NET Core's major version release train and build upon a stable LTS platform.

### ASP.NET Core - still our top recommendation for .NET Framework

If you need to stay on the .NET Framework, we'd still recommend using the newer **ASP.NET Core 2.1** over classic **ASP.NET System.Web** projects
as it's cleaner, lighter, more flexible and future proof. Unlike Microsoft web frameworks, ServiceStack is a **single code-base** which 
supports running on [multiple platforms](/why-servicestack#multiple-hosting-options) so your ServiceStack Services can enjoy near perfect 
source-code compatibility when and if you choose to **move to .NET Core** in future.

Whilst Microsoft is stopping new development of ASP.NET Core on .NET Framework, we're not, our supported packages have standardized to
multi-target both **.NET v4.5+** and **.NET Standard 2.0** which is supported natively on **ASP.NET Core 2.1**.

### Future proofed and continually developed

This includes our own innovations that we continue to invest in like [#Script](https://sharpscript.net) (fka ServiceStack Templates) naturally support 
.NET Framework and .NET Core and runs everywhere ServiceStack does including within [classic ASP.NET MVC Controllers](https://sharpscript.net/docs/mvc-netcore)
which wasn't a design goal but was a natural consequence of developing clean libraries without external dependencies or reliance on external tooling.

This is to say that **ASP.NET Core 2.1 LTS** is still a fantastic rock-solid platform to run your .NET Framework workloads when you need to
which will continue to receive enhancements and new features with each ServiceStack release courtesy of being derived from the same 
shared code-base which will enable seamless migrations to .NET Core should you wish to in future.

#### Start from pre-configured Project Templates

Ultimately you'll miss out on niceties like the [Microsoft.AspNetCore.App](https://www.nuget.org/packages/Microsoft.AspNetCore.App)
meta-package, as a result we recommend starting from one of our [ASP.NET Core Framework project Templates](https://github.com/NetFrameworkCoreTemplates) 
which by convention all have the `-corefx` suffix: 

<WebNewCorefxMd></WebNewCorefxMd>

#### Usage

This will let you create an ASP.NET Core App running on the .NET Framework v4.7 using [web new](/web-new) with:

```bash
$ dotnet tool install --global web 

$ x new web-corefx AcmeNetFx
```

Which can then be opened in your preferred VS.NET or Project Rider C# IDE.

### Reference .Core packages

The primary difference between ASP.NET Core Apps on **.NET Core 2.1** vs **.NET Framework** is needing to reference the `.Core` packages to force referencing ServiceStack **.NET Standard 2.0** libraries, which otherwise when installed in a .NET Framework project would install `net45` libraries. The differences between the 2 builds include:

  - `net45` - Contains support for running **ASP.NET** Web or Self-Hosting **HttpListener** App Hosts
  - `netstandard2.0` - Contains support for only running on **ASP.NET Core** App Hosts

In order to run ASP.NET Core Apps on the .NET Framework it needs to only reference `.Core` NuGet packages which contains only the **.NET Standard 2.0** builds. Currently the list of `.Core` packages which contains only **.NET Standard 2.0** builds include:

 - ServiceStack.Text.Core
 - ServiceStack.Interfaces.Core
 - ServiceStack.Client.Core
 - ServiceStack.HttpClient.Core
 - ServiceStack.Core
 - ServiceStack.Common.Core
 - ServiceStack.Mvc.Core
 - ServiceStack.Server.Core
 - ServiceStack.Redis.Core
 - ServiceStack.OrmLite.Core
 - ServiceStack.OrmLite.Sqlite.Core
 - ServiceStack.OrmLite.SqlServer.Core
 - ServiceStack.OrmLite.PostgreSQL.Core
 - ServiceStack.OrmLite.MySql.Core
 - ServiceStack.OrmLite.MySqlConnector.Core
 - ServiceStack.Aws.Core
 - ServiceStack.Azure.Core
 - ServiceStack.RabbitMq.Core
 - ServiceStack.Api.OpenApi.Core
 - ServiceStack.Admin.Core
 - ServiceStack.Stripe.Core
 - ServiceStack.Logging.Log4Net.Core
 - ServiceStack.Logging.NLog.Core
 - ServiceStack.Kestrel.Core

::: warning
Ultimately support for whether a **.NET Standard 2.0** library will run on the .NET Framework depends on whether external dependencies also support this scenario which as it's a more niche use-case, will be a less tested scenario
:::

## Troubleshooting

### Resolving Runtime Assembly Loading Issues

Many of Microsoft's core **.NET Standard 2.0** packages have been reported to have runtime Assembly loading issues 
that throw `FileNotFoundException` "Could not load file or assembly ..." Exceptions in .NET Framework projects, including:

 - `System.Runtime`
 - `System.Runtime.CompilerServices.Unsafe`
 - `System.Runtime.InteropServices.RuntimeInformation`
 - `System.Memory`
 - `System.Buffers`
 - `System.Numerics.Vectors`
 - `netstandard`

Some solutions that have been known to resolve these issues include:

 1. Adding the package, e.g. `System.Runtime.CompilerServices.Unsafe` reference directly on the Host project,
[for netstandard](https://github.com/dotnet/standard/issues/328#issuecomment-299577190) the package is [NETStandard.Library.NETFramework](https://www.nuget.org/packages/NETStandard.Library.NETFramework) or installing .NET Core 2.0 SDK.
 2. Manually Adding Binding Redirect, see:
   - [System.Runtime](https://stackoverflow.com/a/52250140/85785)
   - [System.Runtime.CompilerServices.Unsafe](https://stackoverflow.com/a/55329952/85785)
   - [System.Runtime.InteropServices.RuntimeInformation](https://stackoverflow.com/a/52637120/85785)
   - [System.Numerics.Vectors](https://github.com/dotnet/corefx/issues/30106#issuecomment-395248278)
   - [System.Net.Http](https://stackoverflow.com/a/48867478/85785)
 3. [Install the missing .dll into the GAC](https://stackoverflow.com/a/62770487/85785)
 4. If you had an existing binding redirect, try removing it
 5. Adding `<AutoGenerateBindingRedirects>true</autoquery/autogenerateBindingRedirects>` to your project's .csproj 
 6. Uninstalling and Reinstalling the problem packages from your projects
 7. Clean Solution and remove project artifacts, including Nuget `/packages` and project `/bin` and `/obj` folders
 8. Upgrading to the latest version of the .NET Framework (v4.7.2+)

Many of these issues is the result of [older .NET Frameworks like .NET v4.6.1](https://github.com/dotnet/standard/issues/481)
not properly supporting .NET Standard 2.0 which is mostly resolved by installing .NET Framework v4.7.1+.


# Single Page App Components
Source: https://docs.servicestack.net/templates/spa-components

<div class="not-prose my-8 ml-20 flex justify-center">
<svg style="max-width:200px" version="1.1" viewBox="0 0 261.76 226.69" xmlns="http://www.w3.org/2000/svg"><g transform="matrix(1.3333 0 0 -1.3333 -76.311 313.34)"><g transform="translate(178.06 235.01)"><path d="m0 0-22.669-39.264-22.669 39.264h-75.491l98.16-170.02 98.16 170.02z" fill="#41b883"/></g><g transform="translate(178.06 235.01)"><path d="m0 0-22.669-39.264-22.669 39.264h-36.227l58.896-102.01 58.896 102.01z" fill="#34495e"/></g></g>
</svg>
<svg style="max-width:280px" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" x="0px" y="0px"
	 viewBox="0 0 841.9 595.3" enable-background="new 0 0 841.9 595.3" xml:space="preserve">
<g>
	<path fill="#61DAFB" d="M666.3,296.5c0-32.5-40.7-63.3-103.1-82.4c14.4-63.6,8-114.2-20.2-130.4c-6.5-3.8-14.1-5.6-22.4-5.6v22.3
		c4.6,0,8.3,0.9,11.4,2.6c13.6,7.8,19.5,37.5,14.9,75.7c-1.1,9.4-2.9,19.3-5.1,29.4c-19.6-4.8-41-8.5-63.5-10.9
		c-13.5-18.5-27.5-35.3-41.6-50c32.6-30.3,63.2-46.9,84-46.9l0-22.3c0,0,0,0,0,0c-27.5,0-63.5,19.6-99.9,53.6
		c-36.4-33.8-72.4-53.2-99.9-53.2v22.3c20.7,0,51.4,16.5,84,46.6c-14,14.7-28,31.4-41.3,49.9c-22.6,2.4-44,6.1-63.6,11
		c-2.3-10-4-19.7-5.2-29c-4.7-38.2,1.1-67.9,14.6-75.8c3-1.8,6.9-2.6,11.5-2.6l0-22.3c0,0,0,0,0,0c-8.4,0-16,1.8-22.6,5.6
		c-28.1,16.2-34.4,66.7-19.9,130.1c-62.2,19.2-102.7,49.9-102.7,82.3c0,32.5,40.7,63.3,103.1,82.4c-14.4,63.6-8,114.2,20.2,130.4
		c6.5,3.8,14.1,5.6,22.5,5.6c27.5,0,63.5-19.6,99.9-53.6c36.4,33.8,72.4,53.2,99.9,53.2c8.4,0,16-1.8,22.6-5.6
		c28.1-16.2,34.4-66.7,19.9-130.1C625.8,359.7,666.3,328.9,666.3,296.5z M536.1,229.8c-3.7,12.9-8.3,26.2-13.5,39.5
		c-4.1-8-8.4-16-13.1-24c-4.6-8-9.5-15.8-14.4-23.4C509.3,224,523,226.6,536.1,229.8z M490.3,336.3c-7.8,13.5-15.8,26.3-24.1,38.2
		c-14.9,1.3-30,2-45.2,2c-15.1,0-30.2-0.7-45-1.9c-8.3-11.9-16.4-24.6-24.2-38c-7.6-13.1-14.5-26.4-20.8-39.8
		c6.2-13.4,13.2-26.8,20.7-39.9c7.8-13.5,15.8-26.3,24.1-38.2c14.9-1.3,30-2,45.2-2c15.1,0,30.2,0.7,45,1.9
		c8.3,11.9,16.4,24.6,24.2,38c7.6,13.1,14.5,26.4,20.8,39.8C504.7,309.8,497.8,323.2,490.3,336.3z M522.6,323.3
		c5.4,13.4,10,26.8,13.8,39.8c-13.1,3.2-26.9,5.9-41.2,8c4.9-7.7,9.8-15.6,14.4-23.7C514.2,339.4,518.5,331.3,522.6,323.3z
		 M421.2,430c-9.3-9.6-18.6-20.3-27.8-32c9,0.4,18.2,0.7,27.5,0.7c9.4,0,18.7-0.2,27.8-0.7C439.7,409.7,430.4,420.4,421.2,430z
		 M346.8,371.1c-14.2-2.1-27.9-4.7-41-7.9c3.7-12.9,8.3-26.2,13.5-39.5c4.1,8,8.4,16,13.1,24C337.1,355.7,341.9,363.5,346.8,371.1z
		 M420.7,163c9.3,9.6,18.6,20.3,27.8,32c-9-0.4-18.2-0.7-27.5-0.7c-9.4,0-18.7,0.2-27.8,0.7C402.2,183.3,411.5,172.6,420.7,163z
		 M346.7,221.9c-4.9,7.7-9.8,15.6-14.4,23.7c-4.6,8-8.9,16-13,24c-5.4-13.4-10-26.8-13.8-39.8C318.6,226.7,332.4,224,346.7,221.9z
		 M256.2,347.1c-35.4-15.1-58.3-34.9-58.3-50.6c0-15.7,22.9-35.6,58.3-50.6c8.6-3.7,18-7,27.7-10.1c5.7,19.6,13.2,40,22.5,60.9
		c-9.2,20.8-16.6,41.1-22.2,60.6C274.3,354.2,264.9,350.8,256.2,347.1z M310,490c-13.6-7.8-19.5-37.5-14.9-75.7
		c1.1-9.4,2.9-19.3,5.1-29.4c19.6,4.8,41,8.5,63.5,10.9c13.5,18.5,27.5,35.3,41.6,50c-32.6,30.3-63.2,46.9-84,46.9
		C316.8,492.6,313,491.7,310,490z M547.2,413.8c4.7,38.2-1.1,67.9-14.6,75.8c-3,1.8-6.9,2.6-11.5,2.6c-20.7,0-51.4-16.5-84-46.6
		c14-14.7,28-31.4,41.3-49.9c22.6-2.4,44-6.1,63.6-11C544.3,394.8,546.1,404.5,547.2,413.8z M585.7,347.1c-8.6,3.7-18,7-27.7,10.1
		c-5.7-19.6-13.2-40-22.5-60.9c9.2-20.8,16.6-41.1,22.2-60.6c9.9,3.1,19.3,6.5,28.1,10.2c35.4,15.1,58.3,34.9,58.3,50.6
		C644,312.2,621.1,332.1,585.7,347.1z"/>
	<polygon fill="#61DAFB" points="320.8,78.4 320.8,78.4 320.8,78.4 	"/>
	<circle fill="#61DAFB" cx="420.9" cy="296.5" r="45.7"/>
	<polygon fill="#61DAFB" points="520.5,78.1 520.5,78.1 520.5,78.1 	"/>
</g>
</svg>
<svg style="max-width:200px" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" x="0px" y="0px"
	 viewBox="0 0 250 250" xml:space="preserve">
<g>
	<polygon fill="#DD0031" points="125,30 125,30 125,30 31.9,63.2 46.1,186.3 125,230 125,230 125,230 203.9,186.3 218.1,63.2 	"/>
	<polygon fill="#C3002F" points="125,30 125,52.2 125,52.1 125,153.4 125,153.4 125,230 125,230 203.9,186.3 218.1,63.2 125,30 	"/>
	<path fill="#FFFFFF" d="M125,52.1L66.8,182.6h0h21.7h0l11.7-29.2h49.4l11.7,29.2h0h21.7h0L125,52.1L125,52.1L125,52.1L125,52.1
		L125,52.1z M142,135.4H108l17-40.9L142,135.4z"/>
</g>
</svg>
</div>


## SPA Component Libraries

To lay the foundation for richer and more tightly integrated UI controls, we've created UI and common component libraries for the 
3 most popular JS frameworks:

### [@servicestack/vue](https://github.com/ServiceStack/servicestack-vue)

### [@servicestack/react](https://github.com/ServiceStack/servicestack-react)

### [@servicestack/angular](https://github.com/ServiceStack/servicestack-angular)

All new [Single Page App Project Templates](/templates/single-page-apps) have been pre-configured to use these libraries which will make it 
a lot easier to deliver new UI components and updates to existing SPA Apps with just an npm upgrade.

### UI Component List

Currently the component libraries include common Bootstrap UI Form Controls, Navigation Components and a generic `Forbidden` page 
to handle when users don't have access to a protected route.

Side-by-side comparison displaying the names for the different Component Type in each JS Framework:

| Control        | vue              | react          | angular            |
|----------------|------------------|----------------|--------------------|
| Forbidden      | Forbidden        | Forbidden      | ForbiddenComponent |
| ErrorSummary   | error-summary    | ErrorSummary   | error-summary      |
| Input          | v-input          | Input          | ng-input           |
| Select         | v-select         | Select         |                    |
| CheckBox       | v-checkbox       | CheckBox       | ng-checkbox        |
| Button         | v-button         | Button         | ng-button          |
| SvgImage       | v-svg            | SvgImage       |                    |
| Link           | v-link           | ALink          | ng-link            |
| LinkButton     | link-button      | LinkButton     | link-button        |
| Nav            | v-nav            | Nav            |                    |
| Navbar         | navbar           | Navbar         | navbar             |
| NavLink        | nav-link         | NavLink        | nav-link           |
| NavButtonGroup | nav-button-group | NavButtonGroup | nav-button-group   |
| NavLinkButton  | nav-link-button  | NavLinkButton  | nav-link-button    |



### Bootstrap UI Form Controls

The Bootstrap UI form controls include built-in support for validation where they can render validation errors from ServiceStack's
`ResponseStatus` object, e.g the [SignIn.vue](https://github.com/NetCoreTemplates/vue-spa/blob/master/MyApp/src/components/SignIn.vue) 
page used in all Vue project templates:

```html
<form @submit.prevent="submit" :class="{ error:responseStatus, loading }" >
    <div class="form-group">
        <error-summary except="userName,password" :responseStatus="responseStatus" />
    </div>
    <div class="form-group">
        <v-input id="userName" v-model="userName" placeholder="Username" :responseStatus="responseStatus" 
                 label="Email" help="Email you signed up with" />
    </div>
    <div class="form-group">
        <v-input type="password"  id="password" v-model="password" placeholder="Password" 
                :responseStatus="responseStatus" label="Password" help="6 characters or more" />
    </div>
    <div class="form-group">
        <v-checkbox id="rememberMe" v-model="rememberMe" :responseStatus="responseStatus">
            Remember Me
        </v-checkbox>
    </div>
    <div class="form-group">
        <button type="submit" class="btn btn-lg btn-primary">Login</button>
        <link-button href="/signup" lg outline-secondary class="ml-2">Register New User</link-button>
    </div>
</form>
```

Initially renders the following UI:

![](/img/pages/spa/vue-form-components.png)

All form validation is typically performed the same way, by sending a populated ServiceStack Request DTO and capturing any 
Service Client exceptions in the components `responseStatus` property, e.g:

```typescript
protected async submit() {
    try {
        this.loading = true;
        this.responseStatus = null;
        const response = await client.post(new Authenticate({
            provider: 'credentials',
            userName: this.userName,
            password: this.password,
            rememberMe: this.rememberMe,
        }));
        bus.$emit('signin', response);
        redirect(this.$route.query.redirect as string || Routes.Home);
    } catch (e) {
        this.responseStatus = e.responseStatus || e;
    } finally {
        this.loading = false;
    }
}
```

Where it automatically applies the field validation error next to their respective control:

![](/img/pages/spa/vue-form-components-invalid.png)

Conversely you can unset the `responseStatus` to reset all form validation errors:

```ts
this.responseStatus = null;
```

### Navigation Components

All navigation components are populated the same way for all JavaScript FX's where it embeds the navigation data structure in the page by
serializing the response of the `GetNavItems` Service to JSON that's embedded in the layout page where it's only loaded once 
upon the initial page request (immediately, without an Ajax network request): 

::: v-pre
```hbs
{{#script}}
NAV_ITEMS = {{ 'GetNavItems'  |> execService |> json }};
AUTH      = {{ 'Authenticate' |> execService({ ifErrorReturn: "null" }) |> json }};
{{/script}}
```
:::

The navigation items data structure is used with new Navigation Components for each JavaScript FX to render the menu navigation
which is initially captured in a state object containing the NavItems data structure, the Users Session and the list
of User Attributes generated from the Authenticated Users Session (if any), e.g:

### Vue

In Vue the Nav and User Information is maintained in a global `store` object which uses `UserAttributes.fromSession()` from the 
`@servicestack/client` library to generate the list of User Attributes:

```ts
export const store: State = {
  nav: global.NAV_ITEMS as GetNavItemsResponse,
  userSession: global.AUTH as AuthenticateResponse,
  userAttributes: UserAttributes.fromSession(global.AUTH),
};
```

The built-in list of User Attributes include:

  - `auth` - Authenticated User
  - `role:TheRole` - Authenticated User with `TheRole` role.
  - `perm:ThePermission` - Authenticated User with `ThePermission` permission.

This list can be further extended to include your own custom User Attributes, these are used to control whether to display the navigation item 
based on if the attribute is an exact match for the `Show` and `Hide` properties of the `NavItem`. E.g. Navigation Items populated with:

```json
  "NavItems": [
    { "href":"/login",      "label":"Sign In", "hide":"auth" },
    { "href":"/profile",    "label":"Profile", "show":"auth" },
    { "href":"/admin",      "label":"Admin",   "show":"role:Admin" }
  ],
```

Will hide the **Sign In** and show the **Profile** nav items to Authenticated Users and only show the **Admin** nav item to Admin Users.

The `navbar` component uses these data structures to [render the main menu](https://github.com/NetCoreTemplates/vue-spa/blob/24ce35d67dcec0f4e00f0dd2f40cf2e8f0c58c7c/MyApp/src/App.vue#L9):

```html
<navbar :items="store.nav.results" :attributes="store.userAttributes" />
```

The rendering of the component can be further customized using any of the `NavOptions` properties, in **camelCase**.

Which also applies to the list of [registered OAuth provider buttons](https://github.com/NetCoreTemplates/vue-spa/blob/24ce35d67dcec0f4e00f0dd2f40cf2e8f0c58c7c/MyApp/src/App.vue#L9)
rendered with `<nav-button-group>`:

```html
<nav-button-group :items="store.nav.navItemsMap.auth" :attributes="store.userAttributes" 
                  :baseHref="store.nav.baseUrl" block lg />
```

In addition to `NavOptions` properties, new Bootstrap UI Controls (in each JavaScript FX) can also use these common bootstrap attributes
to stylize their components:

```ts
export declare class BootstrapBase extends Vue {
    primary?: boolean;
    outlinePrimary?: boolean;
    secondary?: boolean;
    outlineSecondary?: boolean;
    success?: boolean;
    outlineSuccess?: boolean;
    info?: boolean;
    outlineInfo?: boolean;
    warning?: boolean;
    outlineWarning?: boolean;
    danger?: boolean;
    outlineDanger?: boolean;
    light?: boolean;
    outlineLight?: boolean;
    dark?: boolean;
    outlineDark?: boolean;
    lg?: boolean;
    md?: boolean;
    sm?: boolean;
    xs?: boolean;
    block?: boolean;
    vertical?: boolean;
    horizontal?: boolean;
}
```

> camelCase properties like `outlinePrimary` are exposed as **kebab-case** in components, e.g. `outline-primary`

### React

These same components are 
[available in React](https://github.com/NetCoreTemplates/react-spa/blob/7bee202a4ceff4b5a191df178633c45f7f736073/MyApp/src/App.tsx#L46) 
from the new `@servicestack/react` library, except the JSX Components use PascalCase, e.g:

```html
<Navbar items={state.nav.results} attributes={state.userAttributes} />
```

Likewise for [NavButtonGroup](https://github.com/NetCoreTemplates/react-spa/blob/7bee202a4ceff4b5a191df178633c45f7f736073/MyApp/src/components/SignIn.tsx#L93):

```html
<NavButtonGroup items={state.nav.navItemsMap.auth} attributes={state.userAttributes} 
                baseHref={state.nav.baseUrl} block lg />
```

### Angular

Likewise for Angular from the new `@servicestack/angular` package where the main menu is rendered using the 
[navbar component](https://github.com/NetCoreTemplates/angular-spa/blob/278a965d3b8d922f6ea55408269308ff90913263/MyApp/src/app/app.component.html#L9):

```html
<navbar [items]="nav.results" [attributes]="userAttributes"></navbar>
```

And the OAuth Button list is rendered using the [nav-button-group component](https://github.com/NetCoreTemplates/angular-spa/blob/278a965d3b8d922f6ea55408269308ff90913263/MyApp/src/app/signin/index.ts#L49) in kebab-case:

```html
 <nav-button-group [items]="nav.navItemsMap.auth" [attributes]="userAttributes" 
                   [baseHref]="nav.baseUrl" block lg></nav-button-group>
```

### Mobile and Desktop Apps

Whilst there are no native components developed for different Mobile and Desktop UI's, the same navigation information can be accessed
by calling the `GetNavItems` Service, e.g:

```csharp
var response = await client.GetAsync(new GetNavItems());
```


# Tour of Webpack
Source: https://docs.servicestack.net/templates/webpack

[![](/img/pages/ssvs/webpack-overview.png)](https://webpack.js.org)

Webpack powers many npm-based Single Page App templates to enable a flexible and feature-rich development model whose defaults in **webpack.config.js** will be able to support a large number of Web Apps without modification, leaving you free to focus on developing your App.

Webpack works natively with npm packages and is used to handle **all client assets** which can leverage its
[vast ecosystem](https://webpack.github.io/docs/list-of-loaders.html) of 
[loaders](https://webpack.js.org/concepts/loaders/) and 
[plugins](https://webpack.js.org/concepts/plugins/) to handle every kind of web asset, performing the necessary transformations to transpile it into the native formats browsers understand, loading it in browsers and generating source maps so their original source files can be debugged. The Webpack configuration is customized per build type where the optimal configuration is used in development for faster builds and easier debuggability whilst production builds are optimized for performance, size and cacheability.

Although as Webpack is the central hub powering each template you'll still want to become familiar with its [four high-level concepts](https://webpack.js.org/concepts/) to understand how it's new approach to Single Page App development works and how it can handle all your App's dependencies and resources.
 
We'll quickly touch on each of Webpack's concepts by seeing how the React App's [webpack.config.js](https://github.com/ServiceStack/Templates/blob/master/src/SinglePageApps/ReactApp/ReactApp/webpack.config.js) is configured to handle its TypeScript sources, sass/css files and their references.
 
### [Entry points](https://webpack.js.org/concepts/entry-points/)
 
Webpack builds a graph of your App's dependencies which it traverses starting from its entry points, this is the input into Webpack where its given the App's entry point. 

#### [webpack.config.js](https://github.com/NetFrameworkTemplates/react-desktop-apps-netfx/blob/master/MyApp/webpack.config.js)

```js
entry: isTest ? NONE : {
    app: [
        './src/main.ts'
    ]
},
```
 
#### [webpack.config.vendor.js](https://github.com/NetFrameworkTemplates/react-desktop-apps-netfx/blob/master/MyApp/webpack.config.vendor.js)

A separate **vendor** Webpack configuration is maintained for 3rd party Vendor dependencies independent from your App's code-base so they only need to be compiled once when adding a new dependency instead of each time your App changes. To include another vendor library in the vendor build, add the module name or the resource your App uses in the `VENDOR` collection, e.g:

```js
const VENDOR = [
    'bootstrap/dist/css/bootstrap.css',
    'font-awesome/css/font-awesome.css',
    'es6-shim',
    '@servicestack/client',
    'vue',
    'vue-router'
];

entry: { vendor: VENDOR },
```

### [Output](https://webpack.js.org/concepts/output/)
 
On the opposite end of Webpack's build are its outputs where we tell it where to bundle our App:
 
```js
output: {
    path: root('wwwroot/dist'),
    publicPath: '/dist/',
    filename: isProd ? '[name].[chunkhash].bundle.js' : '[name].bundle.js',
    chunkFilename: isProd ? '[name].[chunkhash].js' : '[name].js',
},
```

Here we can see that our Webpack config supports multiple [isProd and isDev](https://github.com/NetCoreTemplates/vue-spa/blob/9f4c81c9f6dc5e1e812238357853eb0ea08bac51/MyApp/webpack.config.js#L5-L6) configurations, `isDev` is used for development builds where Webpack bundles our website in the `/dist` folder whilst `isProd` is used for production builds which is instead bundled in the `/wwwroot/dist` folder with each `.js` bundle including a **[chunkhash]** cache-breaker in its filename. 
 
> The `root()` and `when()` functions used are basic [helpers used to simplify webpack configuration](https://github.com/NetCoreTemplates/vue-spa/blob/9f4c81c9f6dc5e1e812238357853eb0ea08bac51/MyApp/webpack.config.js#L158-L164)
 
### Vendor Output

The Vendor Webpack configuration utilizes [Webpack's DllPlugin](https://webpack.js.org/plugins/dll-plugin/) to generate a `vendor.dll.css` and a `vendor.dll.js` containing the Vendor's compiled `.css` and `.js` bundles:

```js
const extractCSS = new ExtractTextPlugin('vendor.dll.css');

output: {
    path: root('wwwroot/dist'),
    publicPath: 'dist/',
    filename: '[name].dll.js',
    library: '[name]_[hash]',
},
plugins: [
    extractCSS,
    new webpack.DllPlugin({
        path: path.join(__dirname, 'wwwroot', 'dist', '[name]-manifest.json'),
        name: '[name]_[hash]'
    })
]
```

It also generates `vendor-manifest.json` which is referenced in the App's [webpack.config.js](https://github.com/NetCoreTemplates/vue-spa/blob/9f4c81c9f6dc5e1e812238357853eb0ea08bac51/MyApp/webpack.config.js#L134-L136) to tell it which dependencies are included in the vendor bundles so they don't need to be compiled with the App:

```js
plugins: [
    ...when(!isTest, [
        new webpack.DllReferencePlugin({
            context: __dirname,
            manifest: require('./wwwroot/dist/vendor-manifest.json')
        }),
    ]),
]
```

Utilizing Webpack .dll's plugin for your vendor dependencies allows for faster compilation times as they don't need to be recompiled when your App changes.

### [Loaders](https://webpack.js.org/concepts/loaders/)
 
Loaders are the flexible engine that sets Webpack apart where it's able to leverage its [vast ecosystem](https://webpack.github.io/docs/list-of-loaders.html) where there's a loader for every kind of web asset typically used when developing Web Apps. 
 
Loaders are configured in the `rules` section and invoked using node's `require()` statement or ES6/TypeScript's `import` statement. Rules use the `test` regex to specify which files they should apply to whilst the `loader` property tells Webpack which loader to load them with. Each loader is self-contained in a separate npm package that needs to be made available to your project by adding them to your [package.json devDependencies](https://github.com/NetCoreTemplates/vue-spa/blob/9f4c81c9f6dc5e1e812238357853eb0ea08bac51/MyApp/package.json#L31). 
 
Lets checkout Vue's loader configuration for a typical example:
 
```js
const postcssLoader = {
    loader: 'postcss-loader',
    options: { plugins: [require('precss'), require('autoprefixer')] }
};
 
module: {
    rules: [
        {
            test: /\.vue$/,
            loader: 'vue-loader',
            options: {
                loaders: {
                    scss: 'vue-style-loader!css-loader!sass-loader',
                    sass: 'vue-style-loader!css-loader!sass-loader?indentedSyntax'
                }
            }
        },
        {
            test: /\.tsx?$/,
            loader: 'ts-loader',
            options: {
                appendTsSuffixTo: [/\.vue$/],
                transpileOnly: isTest
            },
            exclude: [isTest ? /\.(e2e)\.ts$/ : /\.(spec|e2e)\.ts$/, /node_modules/]
        },
        {
            test: /\.html$/,
            loader: 'html-loader'
        },
        {
            enforce: "pre",
            test: /\.js$/, 
            loader: "source-map-loader"
        },
        {
            test: /\.(jpe?g|gif|png|ico|svg|wav|mp3)$/i,
            loader: 'file-loader' + (isProd 
                ? '?hash=sha512&digest=hex&name=img/[name].[hash].[ext]' 
                : '?name=img/[name].[ext]')
        },
        {
            test: /\.(eot|ttf|woff|woff2)(\?v=\d+\.\d+\.\d+)?$/,
            loader: isProd 
                ? 'url-loader?limit=10000&name=img/[name].[hash].[ext]' 
                : 'file-loader?name=img/[name].[ext]'
        },
        ...when(isDev || isTest, [
            {
                test: /\.css$/,
                use: [ 'style-loader', 'css-loader', postcssLoader ]
            },
            {
                test: /\.(sass|scss)$/,
                use: [ 'style-loader', 'css-loader', postcssLoader, 'sass-loader' ] 
            },            
        ]),
        ...when(isProd, [
            {
                test: /\.css$/,
                loader: ExtractTextPlugin.extract({
                    fallback: 'style-loader',
                    use: ['css-loader?minimize', postcssLoader],
                }),
            },
            {
                test: /\.(sass|scss)$/,
                loader: ExtractTextPlugin.extract({
                    fallback: 'style-loader',
                    use: ['css-loader?minimize', postcssLoader, 'sass-loader'],
                }),
            }
        ])
    ]
},
```
 
This configuration instructs Webpack to load any `.ts` or `.tsx` files using the [TypeScript loader for webpack](https://www.npmjs.com/package/ts-loader) which is then responsible for compiling the source files with TypeScript's compiler. 
 
Loaders are also chainable as seen in the `.css` and `.scss` rules which starts from right-to-left where the output of the rightmost loader is passed into the next loader on its left and so on. 

```js
{
    test: /\.css$/,
    use: [ 'style-loader', 'css-loader', postcssLoader ]
},
```
 
Here the `.css` contents are first processed with [postcssLoader](https://github.com/postcss/postcss-loader) which uses [precss](https://github.com/jonathantneal/precss) to let you use basic sass-like features in vanilla `.css` files and [autoprefixer](https://github.com/postcss/autoprefixer) which lets you write clean standard css rules like:
 
```css
a {
    display: flex;
}
```
 
Which autoprefixer will expand to include vendor prefixes, maximizing support for older browser versions:
 
```css
a {
    display: -webkit-box;
    display: -webkit-flex;
    display: -ms-flexbox;
    display: flex
}
```
 
The output of `postcssLoader` then gets passed into [css-loader](https://github.com/webpack-contrib/css-loader) which processes any css `@import()` and `@url()` rules and loads them with Webpack's `require()` to ensure its references are also processed by Webpack.
 
The output of `css-loader` then gets passed into [style-loader](https://github.com/webpack-contrib/style-loader) who injects the resulting css fragments within `<style></style>` tags in the browser's DOM which is how Web App styles in development builds are still visible despite their being no `.css` files written. [Sass](http://sass-lang.com/) `.scss` files are handled similarly to `.css` files except they're initially loaded with [sass-loader](https://github.com/webpack-contrib/sass-loader) which converts them into `.css`. Both these rules together let you use your preferred choice of `.scss` or `.css` files to style your Web App.
 
There's a separate configuration needed for Production builds which is configured to minify the css and write their contents out into separate `.css` bundles as defined in the plugins section below:
 
### [Plugins](https://webpack.js.org/concepts/plugins/)
 
Loaders only loads and transforms files on a **per-file** basis, anything more advanced requires using plugins. In this template plugins are used to:
 
 1. Set type of Webpack build so other loaders/plugins can optimize accordingly
 2. Ignores watching the `/wwwroot` folder for any changes during watched builds
 3. References the **vendor** `.js` and `.css` bundles in the App's Webpack build
 4. Generate the WebApps `index.html`, based on [index.template.ejs](https://github.com/NetFrameworkTemplates/react-desktop-apps-netfx/blob/master/MyApp/index.template.ejs) and compiled with [lodash template](https://lodash.com/docs/4.17.4#template), which also takes care of injecting any `.css` and `.js` output bundle references
 5. Injects the vendor  `.js` and `.css` bundles in the generated `wwwroot/index.html`

```js
plugins: [
    new webpack.DefinePlugin({ '_process.env.NODE_ENV': isDev ? '"development"' : '"production"' }),
    new webpack.WatchIgnorePlugin([root("wwwroot")]),
    ...when(!isTest, [
        new webpack.DllReferencePlugin({
            context: __dirname,
            manifest: require('./wwwroot/dist/vendor-manifest.json')
        }),
        new HtmlWebpackPlugin({
            template: 'index.template.ejs',
            filename: '../index.html',
            inject: true
        }),
        new AddAssetHtmlPlugin({ filepath: root('wwwroot/dist/*.dll.js') }),
        new AddAssetHtmlPlugin({ filepath: root('wwwroot/dist/*.dll.css'), typeOfAsset: 'css' })
    ]),
    ...when(isProd, [
        new webpack.LoaderOptionsPlugin({ minimize: true }),
        new ExtractTextPlugin({ filename: '[name].[chunkhash].css', allChunks: true }),
        new webpack.optimize.UglifyJsPlugin({ sourceMap: true, compress: { warnings: false } })
    ]),
]
```

### /wwwroot WebRoot Path for .NET Framework Templates

To simplify migration efforts of ServiceStack projects between .NET Core and .NET Framework, all SPA and Website Templates are configured to use .NET Core's convention of `/wwwroot` for its public WebRoot Path. The 2 adjustments needed to support this was configuring ServiceStack to use the `/wwwroot` path in AppHost:

```csharp
SetConfig(new HostConfig {
    WebHostPhysicalPath = MapProjectPath("~/wwwroot"),
});
```

### Deployments

When your App is ready to deploy, run the `publish` npm (or Gulp) script to package your App for deployment:

```bash
npm run publish
```

Which creates a production build of your App where the `.css` files are written using [ExtractTextPlugin](https://github.com/webpack-contrib/extract-text-webpack-plugin) and the resulting `.js` files minified with UglifyJS. The full production build is generated in in `/wwwroot/dist` folder where it's ready for an XCOPY, rsync or MSDeploy deployment.

In the .NET Framework templates you can deploy to any [MS WebDeploy](https://www.iis.net/downloads/microsoft/web-deploy) enabled Server by clicking **Publish...** in the ASP.NET's project Context Menu item which makes use of the existing [/PublishProfiles/PublishToIIS.pubxml](https://github.com/NetFrameworkTemplates/vue-spa-netfx/blob/master/MyApp/Properties/PublishProfiles/PublishToIIS.pubxml) which [includes an instruction](https://github.com/NetFrameworkTemplates/vue-spa-netfx/blob/2e8c208982561695275b451a9ece35522d9739d9/MyApp/Properties/PublishProfiles/PublishToIIS.pubxml#L23-L36) to include the `/wwwroot` folder in deployments.

In .NET 6.0 projects the `publish` npm script runs `dotnet publish -c Release` to Publish a Release build of your App in the `/bin/netcoreapp3.1/publish` folder which can then copied to remote server or an included in a Docker container to deploy your App.
 
### Loading Dependencies
 
Now that we've covered how Webpack is configured, the next step is showing how to make use of it, by loading your App's resources using node's `require()` or TypeScript's `import` statement. 

This can be seen in the App's [main.ts](https://github.com/NetCoreTemplates/vue-spa/blob/master/MyApp/src/main.ts) starting point where it imports **bootstrap.css** and **font-awesome.css** directly from the installed **bootstrap** and **font-awesome** npm packages as well as a local [./app.scss](https://github.com/NetCoreTemplates/vue-spa/blob/master/MyApp/src/app.scss) SASS file which lives side-by-side next to TypeScript source files:
 
```ts
import 'bootstrap/dist/css/bootstrap.css';
import "font-awesome/css/font-awesome.css";
import './app.scss';
import 'es6-shim';

import Vue from 'vue';
import Router from 'vue-router';
import App from './App.vue';
import Home from './home/Home.vue';
import View1 from './view1/View1.vue';
import View2 from './view2/View2.vue';
```
 
Importing **bootstrap** and **font-awesome** also imports their references, including any images, fonts, svg and other .css files. These are all transparently added to the webpack build and bundled with the rest of your app. 
 
In production builds the `file-loader` copies their references to the output folder, embedding its `sha512` hash in each file name. `url-loader` works similarly but also has the option of embedding file contents below the configured **10000** byte limit inline inside a [Data URI](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/Data_URIs) to reduce network requests in production builds.

```js
{
    test: /\.(jpe?g|gif|png|ico|svg|wav|mp3)$/i,
    loader: 'file-loader' + (isProd 
        ? '?hash=sha512&digest=hex&name=img/[name].[hash].[ext]' 
        : '?name=img/[name].[ext]')
},
{
    test: /\.(eot|ttf|woff|woff2)(\?v=\d+\.\d+\.\d+)?$/,
    loader: isProd 
        ? 'url-loader?limit=10000&name=img/[name].[hash].[ext]' 
        : 'file-loader?name=img/[name].[ext]'
},
```

`require()` can also be used to load resources in other files which is how images can be imported in the [index.template.ejs](https://github.com/NetCoreTemplates/vue-spa/blob/master/MyApp/index.template.ejs) home page template:
 
```html
<img src="<%=require('./src/assets/img/logo.png')%>" />
```
 
Or inside [App components](https://github.com/NetCoreTemplates/angular-lite-spa/blob/4d3ad89c57a7243c6c00758a4de779ba5222de8d/MyApp/src/app.component.ts#L32), both of which returns the image url after it has been processed by Webpack's loaders, e.g:
 
```csharp
constructor() {
    this.logoUrl = require("./assets/img/logo.png");
}
```
 
In production builds this returns a relative url to the output image, e.g: `img/logo.36166adfacf0c8cc11d493f2161164fd.png`.
 
### Webpack builds
 
By importing all your WebApp resources into Webpack it's able to maintain a knowledgeable graph of all your Web Apps dependencies where it lets you define how they're handled at a macro level making it easy to incorporate design-time features like TypeScript and Sass whilst also taking care of generating optimal builds for development, testing and production.
 
#### Development builds
 
You'll use development builds when developing your app locally which you can run with either the `webpack-build` Gulp task in VS.NET's Task Runner Explorer GUI or by running the `build` npm script on the command-line:
 
```bash
$ npm run build
```
 
This will generate your App in the `/wwwroot/dist` folder similar to:
 
 ```
/wwwroot
    /dist
        /img
            logo.png
            ...
        app.bundle.js
        vendor.dll.css
        vendor.dll.js
        vendor-manifest.json
index.html
```

The lack of `.css` files or source-maps are due to being embedded in the `.js` bundles and injected in the browser's DOM within `<style></style>` tags. 
 
After the Webpack development build has completed you can just run or refresh your ASP.NET Web App to view the latest changes.
 
#### Production builds
 
When your App is ready to deploy you can run a production build using the `webpack-build-prod` Gulp task or the `build-prod` npm script:
 
```bash
$ npm run build-prod
```
 
This will bundle and generate your WebApp in the **/wwwroot/dist** folder with css and source maps extracted and written into separate files, css and js minified and all assets emitted with cache-breaking hashes, similar to:
 
 ```
/wwwroot
    /dist
        /img
            logo.36166adfacf0c8cc11d493f2161164fd.png
        674f50d287a8c48dc19ba404d20fe713.eot
        912ec66d7572ff821749319396470bde.svg
        b06871f281fee6b241d60582ae9369b9.ttf
        app.3728b4547755ace1f489.bundle.js
        app.3728b4547755ace1f489.bundle.js.map
        app.3728b4547755ace1f489.css
        app.3728b4547755ace1f489.css.map
        vendor.dll.css
        vendor.dll.css.map
        vendor.dll.js
        vendor.dll.js.map
        vendor-manifest.json
    index.html
```

## Development workflow
 
Executing a development build of Webpack is all that's required to be able to see our changes but it can take a while to run a full dev build which negatively impacts our fast iterative dev workflow. It's instead recommended to leave webpack running in the background and have it watch for changes so it only needs to rebuild assets that have changed, which it's able to do very quickly. 
 
![](/img/pages/ssvs/gulp-tasks.png)

### Gulp Tasks
 
 - **dev** - Run Webpack watch to automatically build, watch and process changed files
 - **dtos** - Run **typescript-ref** npm script to import latest TypeScript Server DTOs
 - **webpack-build** - Run a Webpack development build to bundle and output your app to `/dist`
 - **webpack-build-prod** - Run a Webpack production build to bundle and output your app to `/wwwroot/dist`
 - **webpack-build-vendor** - Run a Webpack production build to bundle the Vendor libraries to `/wwwroot/dist`
 - **package** - Perform all tasks to build the client so your App is ready for deployment
 - **tests-run** - Run all TypeScript/JS unit and integration tests
 - **tests-watch** - Rerun all TypeScript/JS tests as source code changes are made
 - **tests-coverage** - View test coverage of your existing TypeScript/JS tests

Whilst we recommend running the `dev` Gulp or npm script during development to run a live watched development, you can instead run the `npm run dev-server` npm script to run a development build of your app through Webpack's dev-server which has it's own built-in hot reloading for when your Client Apps source code changes.

### Webpack watch
 
Our recommendation during development is to run the `dev` Gulp task and leave it running in the background, or if preferred, run the **dev** npm script on the command-line with:
 
```bash
$ npm run dev
```
 
Webpack **dev**  initially generates a full development build of your Web App then stays running in the background to process files as they're changed. This enables the normal dev workflow of running your ASP.NET Web App from VS.NET, saving changes locally which are then reloaded using ServiceStack's built-in hot reloading. Alternatively hitting **F5** will refresh the page and view the latest changes.
 
Each change updates the output dev resources so even if you stop the **dev** task your Web App remains in a working state that's viewable when running the ASP.NET Web App.
 
### Live reload with Webpack Dev Server
 
The alternative dev workflow is to run the `dev-server` npm script to run the [Webpack dev server](https://webpack.js.org/configuration/dev-server/#devserver):
 
```bash
$ npm run dev-server
```
 
This launches the Webpack dev server listening at `http://localhost:3000/` and configured to proxy all non-Webpack HTTP requests to the ASP.NET Web App where it handles all Server API requests. The benefit of viewing your App through the Webpack dev server is its built-in Live Reload feature where it will automatically reload the page as resources are updated. We've found the Webpack dev server ideal when developing UI's where your Web App is running side-by-side VS.NET, where every change saved triggers the dev server to reload the current page so changes are visible immediately. 
 
The disadvantage of the dev server is that all transformations are kept in memory so when the dev server is stopped, the Web Apps resources are lost, so it requires a `webpack-build` in order to generate a current build. There's also a slight lag in API requests resulting from each server request being handled by both Webpack's Dev Server and ASP.NET's IIS Express.


# Install ServiceStackVS
Source: https://docs.servicestack.net/templates/install-servicestackvs

First we want to install [ServiceStackVS Visual Studio extension](http://visualstudiogallery.msdn.microsoft.com/5bd40817-0986-444d-a77d-482e43a48da7). The easiest way to do this is to look for it from within Visual Studio by going to Tools->Extensions and Updates and searching the Visual Studio Gallery as seen below.

![](/img/pages/ssvs/vs-extensions-manage.png)

![](/img/pages/ssvs/vs-extensions-ssvs.png)

## VS.NET Gallery

Optionally it can be downloaded and installed from the [VS.NET Gallery](http://visualstudiogallery.msdn.microsoft.com/5bd40817-0986-444d-a77d-482e43a48da7)

[![VS.NET Gallery Download](https://raw.githubusercontent.com/ServiceStack/Assets/master/img/servicestackvs/vsgallery-download.png)](http://visualstudiogallery.msdn.microsoft.com/5bd40817-0986-444d-a77d-482e43a48da7)

## Visual Studio 2019-2022

The latest **ServiceStackVS** from v3+ includes support for Visual Studio 2019 and 2022:

![](/img/pages/ssvs/vs2019-install-vue.gif)

## Visual Studio 2013-2017

If you're still using VS.NET 2017, 2015 or 2013 you can use the earlier VS.NET ServiceStackVS extension:

- [ServiceStackVS for 2013-2015](https://github.com/ServiceStack/ServiceStackVS/raw/master/dist/2018/ServiceStackVS.vsix)
- [ServiceStackVS 2.0 for 2015-2019](https://github.com/ServiceStack/ServiceStackVS/raw/master/dist/2021/ServiceStackVS.vsix)

::: info
A limited selection of .NET Framework project templates can also be created inside VS.NET using the previous version of
[ServiceStackVS VS.NET Extension](https://github.com/ServiceStack/ServiceStackVS/raw/master/dist/2021/ServiceStackVS.vsix), however these templates are no longer updated. From ServiceStack VS v3+, impacting Visual Studio 2019-2022, templates are no longer available in the extension. To get started with our templates it is best to use our [Getting Started page on our website](https://servicestack.net/start) or the ServiceStack [dotnet `x` tool to create new projects](/templates/#x-new).
:::


# Cross platform dotnet scripts
Source: https://docs.servicestack.net/templates/dotnet-scripts

Often most of our [Project Templates](/dotnet-new) need to include scripts to perform different tasks utilized in each project type, e.g. for generating DTOs, running a dev server, publishing release builds, etc. 

To surface these common tasks to the developer we initially used Gulp and Grunt JS Tasks so they would show up in 
[VS .NET's Task Runner Explorer UI](https://marketplace.visualstudio.com/items?itemName=MadsKristensen.TaskRunnerExplorer) however this has 
become dated over time with both Grunt & Gulp.js seeing their usage decline in favor of more advanced build systems like 
[Webpack](https://webpack.js.org) and [rollup.js](https://rollupjs.org) and at the other end targeting to a single IDE like VS.NET no longer makes sense in a post .NET 6 world which needs to support for multiple platforms and IDEs.

## No formal task solution in dotnet projects

Unfortunately .NET doesn't have a formal way to define common tasks for a project as custom XML MS Build tasks are to clunky and hidden to be useful and littering your project with multiple `.bat` and `.sh` scripts for each task is tacky in a modern development workflow.

## Using npm scripts

As this use-case is [well covered in npm](https://css-tricks.com/why-npm-scripts/) using [npm scripts](https://docs.npmjs.com/cli/v7/using-npm/scripts), the natural choice for our [Single Page App Project Templates](/templates/single-page-apps) (which require npm) is to use npm scripts in [package.json](https://github.com/NetCoreTemplates/vue-spa/blob/master/MyApp/package.json):

![](/img/pages/templates/packagejson-scripts.png)

Thanks to Node.js's popularity this convention available in all node installations is both ubiquitous & UX friendly as every developer knows where to look to find tasks available for each project, how each script is implemented, sorted in the order in which they're generally run and all executed the same way with `npm run`, e.g:

```bash
$ npm run dtos
```

As this default convention is so prevalent it has the advantage that modern IDEs like [Rider](https://www.jetbrains.com/rider/) includes UI support where each task can be directly in the UI.

## What about .NET Apps?

Without a better alternative available to .NET projects we've also resorted to using npm scripts for our project templates that don't use npm like our [vuedesktop.com](https://www.vuedesktop.com) project template which only uses [package.json](https://github.com/NetCoreTemplates/vue-desktop/blob/master/package.json) to maintain scripts of its built-in functionality:

![](/img/pages/templates/packagejson-scripts-vuedesktop.png)

Where they can be run from Rider's IDE or using npm's `run`.

## Using dotnet tools to run package.json scripts

Whilst we can assume **node** to be a ubiquitous dependency installed on most Developer workstations, it may not be available in all environments like CI build agents, Docker containers, new VM workspaces, etc. 

So if we're going to standardize on **package.json** scripts for encapsulating a project template's functionality we thought it also prudent to offer a .NET only solution to support environments where an npm dependency is not desirable, so we've added support for executing npm package.json scripts in our [x](/dotnet-tool) and [app](/netcore-windows-desktop) dotnet tools using `x script`, e.g:

```bash
$ x scripts dtos
```

That's also available from the more wrist-friendly alias `x s`, e.g:

```bash
$ x s dtos
$ app s dtos
```

Which can be used interchangeably with `npm run` to execute command scripts on Windows and `bash` scripts on macOS and Linux or WSL.

## Cross platform scripts

Whilst we now have a pure .NET alternative for running **package.json** scripts should we need it, we still have the issue of maintaining scripts to support multiple platforms. Most of the time this isn't an issue when calling cross-platform tools like `x` or `tsc` which supports the same command syntax on all platforms, but it starts to become an issue if also needing to perform some file operations.

An example of this is the script to generate JS DTOs in our [pure JS dep-free Project templates](/create-your-first-webservice#dependency-free-jsonserviceclient--typed-dtos-in-web-pages) which uses TypeScript to transpile the DTOs then needs to move the generated `dtos.js` to `wwwroot`. If only needing to support Windows the script would simply be:

```json
"scripts": {
    "dtos": "x ts && tsc -m umd dtos.ts && move dtos.js wwwroot/dtos.js"
}
```

But we'd need to have a different script that uses `mv` to support macOS & Linux, we could maintain a separate script per platform, e.g:

```json
"scripts": {
    "dtos:win":  "x ts && tsc -m umd dtos.ts && move dtos.js wwwroot/dtos.js",
    "dtos:unix": "x ts && tsc -m umd dtos.ts && mv dtos.js wwwroot/dtos.js"
}
```

But then anything calling it would also need to be platform specific including docs needing to having to differentiate between which platform-specific scripts to run.

One solution is to evaluate a node expression that performs the required file operations, e.g:

```json
"scripts": {
    "dtos": "x ts && tsc -m umd dtos.ts && node -e \"require('fs').renameSync('dtos.js','wwwroot/dtos.js')\""
}
```

In a similar vein we can also evaluate a [#Script Expression](https://sharpscript.net) to perform the cross-platform operations, e.g:

```json
"scripts": {
    "dtos": "x ts && tsc -m umd dtos.ts && x -e \"mv('dtos.js','wwwroot/dtos.js')\""
}
```

Which our latest templates have adopted, that can be run with either `npm run`, `x scripts` or its `x s` alias:

```bash
$ npm run dtos
$ x scripts dtos
$ x s dtos
```

## Shell Script Methods

`#Script` lets you evaluate [1000+ .NET #Script Methods](https://sharpscript.net/docs/scripts-reference) using [JavaScript syntax](https://sharpscript.net/docs/syntax) including a number of common Windows and Bash shell commands:

| #Script        | Windows             | Unix            |
|----------------|---------------------|-----------------|
| mv(from,to)    | MOVE /Y from to     | mv -f from to   |
| cp(from,to)    | COPY /Y from to     | cp -f from to   |
| xcopy(from,to) | XCOPY /E /H from to | cp -R from to   |
| rm(from,to)    | DEL /Y from to      | rm -f from to   |
| rmdir(target)  | RMDIR /Q /S target  | rm -rf target   |
| mkdir(target)  | MKDIR target        | mkdir -p target |
| cat(target)    | type target         | cat target      |
| touch(target)  | CALL >> target      | touch target    |

Using Unix `/` Path separators are replaced to use `\` in Windows commands.

### File and Directory APIs

Alternatively you can also call .NET's [File](https://docs.microsoft.com/en-us/dotnet/api/system.io.file) and [Directory](https://docs.microsoft.com/en-us/dotnet/api/system.io.directory) static methods, e.g:

```json
"scripts": {
    "dtos": "x ts && tsc -m umd dtos.ts && x -e \"File.Move('dtos.js','wwwroot/dtos.js')\""
}
```

| #Script                              |
|--------------------------------------|
| File.Copy(from,to)                   |
| File.Create(path)                    |
| File.Decrypt(path)                   |
| File.Delete(path)                    |
| File.Encrypt(path)                   |
| File.Exists(path)                    |
| File.Move(from,to)                   |
| File.Replace(from,to,backup)         |
| File.ReadAllBytes(path)              |
| File.ReadAllLines(path)              |
| File.ReadAllText(path)               |
| File.WriteAllBytes(path,bytes)       |
| File.WriteAllLines(path,lines)       |
| File.WriteAllText(path,text)         |
| File.AppendAllLines(path,lines)      |
| File.AppendAllText(path,text)        |
| Directory.CreateDirectory(path)      |
| Directory.Delete(path)               |
| Directory.Exists(path)               |
| Directory.GetDirectories(path)       |
| Directory.GetFiles(path)             |
| Directory.GetLogicalDrives()         |
| Directory.GetFileSystemEntries(path) |
| Directory.GetParent(path)            |
| Directory.GetCurrentDirectory()      |
| Directory.GetDirectoryRoot(path)     |
| Directory.Move(from,to)              |
| Directory.Copy(from,to)              |


# Installation
Source: https://docs.servicestack.net/vue/install

## Manual Installation

**@servicestack/vue** can be added to existing Vue SPA Apps by installing via npm:

:::sh
npm install @servicestack/vue
:::

Where it will also install its **vue** and **@servicestack/client** dependencies.

## Installation-less option

Alternatively you can take advantage of modern browsers [JS Modules](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules) support to
use these libraries without installation by registering an [importmap](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script/type/importmap) to define where it should load the ESM builds of these libraries from, e.g:

```html
<script type="importmap">
{
    "imports": {
        "vue":                  "https://unpkg.com/vue@3/dist/vue.esm-browser.prod.js",
        "@servicestack/client": "https://unpkg.com/@servicestack/client@2/dist/servicestack-client.min.mjs",
        "@servicestack/vue":    "https://unpkg.com/@servicestack/vue@3/dist/servicestack-vue.min.mjs"
    }
}
</script>
```

For intranet Web Apps that need to work without internet access, save and reference local copies of these libraries, e.g:

```html
<script type="importmap">
{
    "imports": {
        "vue":                  "/lib/mjs/vue.mjs",
        "@servicestack/client": "/lib/mjs/servicestack-client.mjs",
        "@servicestack/vue":    "/lib/mjs/servicestack-vue.mjs"
    }
}
</script>
```

## @Html.ImportMap

Razor Pages or MVC Apps can use the `Html.ImportMaps()` to use local debug builds during development and optimal CDN hosted minified production builds in production:

```csharp
@Html.ImportMap(new()
{
    ["vue"]                  = ("/lib/mjs/vue.mjs",                 "https://unpkg.com/vue@3/dist/vue.esm-browser.prod.js"),
    ["@servicestack/client"] = ("/lib/mjs/servicestack-client.mjs", "https://unpkg.com/@servicestack/client@2/dist/servicestack-client.min.mjs"),
    ["@servicestack/vue"]    = ("/lib/mjs/servicestack-vue.mjs",    "https://unpkg.com/@servicestack/vue@3/dist/servicestack-vue.min.mjs")
})
```

> It's recommended to use exact versions to eliminate redirect latencies and to match the local version your App was developed against

### Polyfill for Safari

Unfortunately Safari is the last modern browser to [support import maps](https://caniuse.com/import-maps) which is only now in
Technical Preview. Luckily this feature can be polyfilled with the pre-configured [ES Module Shims](https://github.com/guybedford/es-module-shims):

```html
@if (Context.Request.Headers.UserAgent.Any(x => x.Contains("Safari") && !x.Contains("Chrome")))
{
    <script async src="https://ga.jspm.io/npm:es-module-shims@1.6.3/dist/es-module-shims.js"></script>
}
```

## Registration

Then register the `@servicestack/vue` component library with your Vue app with:

```js
import { JsonServiceClient } from "@servicestack/client"
import ServiceStackVue from "@servicestack/vue"

const client = new JsonServiceClient()

const app = createApp(component, props)
app.provide('client', client)
app.use(ServiceStackVue)

//...
app.mount('#app')
```

The **client** instance is used by API-enabled components to call your APIs using the [/api predefined route](/routing#json-api-pre-defined-route). ServiceStack Apps not running on .NET 6+ or have the **/api** route disabled should use
`JsonServiceClient` instead:

```js
const client = new JsonServiceClient()
```

## Not using Vue Router

Non SPA Vue Apps that don't use [Vue Router](https://router.vuejs.org) should register a replacement `<router-link>` component
that uses the browser's native navigation in [navigational components](/vue/navigation):

```js
app.component('RouterLink', ServiceStackVue.component('RouterLink'))
```


# AutoQueryGrid Component
Source: https://docs.servicestack.net/vue/autoquerygrid

<div class="flex justify-center">
    <lite-youtube class="w-full mx-4 my-4" width="560" height="315" videoid="znCoC-Ct0Ps" style="background-image: url('https://img.youtube.com/vi/znCoC-Ct0Ps/maxresdefault.jpg')"></lite-youtube>
</div>

<api-reference component="AutoQueryGrid<Model>"></api-reference>
## Default CRUD

By default you can create an AutoQueryGrid that allows authorized users the ability to Create, Read, Update & Delete records 
with just the DataModel, e.g:

```html
<AutoQueryGrid type="Booking" />
```
<div class="not-prose prose-table">
<auto-query-grid type="Booking"></auto-query-grid>
</div>

This will utilize your App's existing [AutoQuery APIs](/autoquery/rdbms) for the specified DataModel to enable its CRUD functionality.

<api-reference component="AutoQueryGrid<Model>"></api-reference>
## Read Only

You can use `apis` to limit which AutoQuery APIs AutoQueryGrid should use, so if only the AutoQuery DTO is provided, the AutoQueryGrid will only be browsable in **read-only** mode:

```html
<AutoQueryGrid type="Booking" apis="QueryBookings"  />
```
<div class="not-prose prose-table">
<auto-query-grid type="Booking" apis="QueryBookings"></auto-query-grid>
</div>

<h2 class="pt-8 mb-4 text-2xl font-semibold text-gray-900 dark:text-gray-100">
  Table Styles
</h2>

The same [DataGrid Table Styles](/vue/datagrid#table-styles) can also be used to style AutoQueryGrid, e.g:

```html
<AutoQueryGrid type="Booking" tableStyle="verticalLines,uppercaseHeadings" />
```
<div class="not-prose prose-table">
<auto-query-grid type="Booking" tableStyle="verticalLines,uppercaseHeadings"></auto-query-grid>
</div>

**Custom Styles**

The AutoQueryGrid's appearance is further customizable with the property classes & functions below:

```ts
defineProps<{
  toolbarButtonClass: string
  tableStyle: "simple" | "fullWidth" | "stripedRows" | "whiteBackground" | "uppercaseHeadings" | "verticalLines"
  gridClass: string
  grid2Class: string
  grid3Class: string
  grid4Class: string
  tableClass: string
  theadClass: string
  tbodyClass: string
  theadRowClass: string
  theadCellClass: string

  rowClass:(model:any,i:number) => string
  rowStyle:(model:any,i:number) => StyleValue
}>()
```

<h2 class="pt-8 mb-4 text-2xl font-semibold text-gray-900 dark:text-gray-100">
  Custom AutoQueryGrid
</h2>

Different AutoQueryGrid features can be hidden with `hide` and functionality disabled with `deny`, e.g:

```html
<AutoQueryGrid type="Booking" hide="pagingNav,copyApiUrl,downloadCsv" deny="filtering" />
```

<div class="not-prose prose-table">
<auto-query-grid type="Booking" hide="pagingNav,copyApiUrl,downloadCsv" deny="filtering"></auto-query-grid>
</div>

Features that can be hidden and disabled include:

```ts
defineProps<{
    deny: "filtering" | "queryString" | "queryFilters"
    hide: "toolbar"   | "preferences" | "pagingNav" | "pagingInfo" | "downloadCsv" | "refresh" 
       | "copyApiUrl" | "filtersView" | "newItem"   | "resetPreferences" 
}>()
```

<h2 class="pt-8 mb-4 text-2xl font-semibold text-gray-900 dark:text-gray-100">
  Global AutoQueryGrid Configuration
</h2>

These features can also be disabled at a global level, applying to all `<AutoQueryGrid>` components with [setConfig](/vue/use-config), e.g:

```js
const { setAutoQueryGridDefaults } = useConfig()

setAutoQueryGridDefaults({
  hide: ['pagingNav','copyApiUrl','downloadCsv']
})
```

<h2 class="pt-8 mb-4 text-2xl font-semibold text-gray-900 dark:text-gray-100">
  Limit Columns
</h2>

By default AutoQueryGrid displays all public properties returned in its AutoQuery API which can be further limited with `selected-columns`:

```html
<AutoQueryGrid type="Booking" selectedColumns="id,name,roomType,roomNumber,cost" />
```
<div class="not-prose prose-table">
<auto-query-grid type="Booking" selectedColumns="id,name,roomType,roomNumber,cost"></auto-query-grid>
</div>

<h2 class="pt-8 mb-4 text-2xl font-semibold text-gray-900 dark:text-gray-100">
  Simple Responsive Columns
</h2>

Using `visible-from` is a simple way to enable a responsive DataGrid by specifying at which [Tailwind breakpoints](https://tailwindcss.com/docs/responsive-design)
columns should be visible from and `header-titles` to use friendlier aliases for different columns, e.g:

```html
<AutoQueryGrid type="Booking" 
  selectedColumns="id,name,roomType,roomNumber,cost,bookingStartDate,bookingEndDate" 
  :headerTitles="{ roomNumber:'Room', bookingStartDate:'Start', bookingEndDate:'End' }"
  :visibleFrom="{ bookingStartDate:'lg', bookingEndDate:'xl' }" />
```
<div class="not-prose prose-table">
<auto-query-grid type="Booking" 
  selectedColumns="id,name,roomType,roomNumber,cost,bookingStartDate,bookingEndDate" 
  :headerTitles="{ roomNumber:'Room', bookingStartDate:'Start', bookingEndDate:'End' }"
  :visibleFrom="{ bookingStartDate:'lg', bookingEndDate:'xl' }"></auto-query-grid>
</div>

<h2 class="pt-8 mb-4 text-2xl font-semibold text-gray-900 dark:text-gray-100">
  Custom Responsive Columns
</h2>

Which columns are displayed and how they're formatted are further customizable with `<template #column>` slots:

```html
<AutoQueryGrid type="Booking" :visibleFrom="{ name:'xl', bookingStartDate:'sm', bookingEndDate:'xl', createdBy:'2xl' }">
    <template #id="{ id }">
        <span class="text-gray-900" v-html="id"></span>
    </template>
    
    <template #name="{ name }">{{name}}</template>
    
    <template #roomNumber-header>
        <span class="hidden lg:inline">Room </span>No
    </template>

    <template #cost="{ cost }">
        <span v-html="currency(cost)"></span>
    </template>
    
    <template #bookingStartDate-header>
        Start<span class="hidden lg:inline"> Date</span>
    </template>
    
    <template #bookingEndDate-header>
        End<span class="hidden lg:inline"> Date</span>
    </template>

    <template #createdBy-header>
        Employee
    </template>
    <template #createdBy="{ createdBy }" v-html="createdBy"></template>
</AutoQueryGrid>
```

<responsive class="not-prose mb-4"></responsive>

<h2 class="pt-8 mb-4 text-2xl font-semibold text-gray-900 dark:text-gray-100">
  Custom Functionality
</h2>

The column template slots can be leveraged to implement custom functionality, e.g. instead of navigating to separate pages to manage related data
we can use a custom column to manage Booking Coupons from within the same grid, e.g:

```html
<AutoQueryGrid type="Booking" selectedColumns="id,name,cost,bookingStartDate,bookingEndDate,discount">
    <template #discount="{ discount }">
        <TextLink v-if="discount" class="flex items-end" @click.stop="showCoupon(discount.id)" :title="discount.id">
            <Icon class="w-5 h-5 mr-1" type="Coupon" />
            <PreviewFormat :value="discount.description" />
        </TextLink>
    </template>
</AutoQueryGrid>
<AutoEditForm v-if="coupon" type="UpdateCoupon" v-model="coupon" @done="close" @save="close" />

<script setup lang="ts">
import { ref } from "vue"
import { useClient } from "@servicestack/vue"
import { QueryCoupons } from "dtos"

const client = useClient()
const coupon = ref()

async function showCoupon(id:string) {
    const api = await client.api(new QueryCoupons({ id }))
    if (api.succeeded) {
        coupon.value = api.response!.results[0]
    }
}

const close = () => coupon.value = null
</script>
```

<custom-booking class="not-prose"></custom-booking>

<h2 class="pt-8 mb-4 text-2xl font-semibold text-gray-900 dark:text-gray-100">
  Data Reference Labels
</h2>

[AutoQuery](/autoquery/rdbms) is able to infer relationships from the [POCO References](/ormlite/reference-support) of your Data Models where if your DataModel includes `[Reference]` attributes so that its related Data is returned in your AutoQuery APIs, AutoQueryGrid will be able to make use of it to render the Contacts & Job Names and Icons instead of just the plain Foreign Key Ids.

An example of this in the [JobApplications](https://blazor-gallery.servicestack.net/locode/QueryJobApplications) DataModel DTO:

```csharp
[Icon(Svg = Icons.Application)]
public class JobApplication : AuditBase
{
    [AutoIncrement]
    public int Id { get; set; }

    [References(typeof(Job))]
    public int JobId { get; set; }

    [References(typeof(Contact))]
    public int ContactId { get; set; }

    [Reference]
    [Format(FormatMethods.Hidden)]
    public Job Position { get; set; }

    [Reference]
    [Format(FormatMethods.Hidden)]
    public Contact Applicant { get; set; }

    [Reference]
    public List<JobApplicationComment> Comments { get; set; }

    public DateTime AppliedDate { get; set; }

    public JobApplicationStatus ApplicationStatus { get; set; }
    //...
}
```

Which AutoQueryGrid uses to automatically display the Job and Contact name instead of their ids:

```html
<AutoQueryGrid type="JobApplication" :prefs="{take:5}" />
```
<div class="not-prose prose-table">
<auto-query-grid type="JobApplication" :prefs="{take:5}"></auto-query-grid>
</div>

With the original ids are discoverable by hovering over the Job & Contact labels. 

## Reference Fields

By default AutoQuery will infer using the first string column of the related table for its label, this information can also be explicitly defined
with the `[Ref]` attribute, e.g:

```csharp
public class JobApplication : AuditBase
{
    [AutoIncrement]
    public int Id { get; set; }

    [References(typeof(Job))]
    [Ref(Model=nameof(Job), RefId=nameof(Job.Id), RefLabel=nameof(Job.Title))]
    public int JobId { get; set; }

    [References(typeof(Contact))]
    [Ref(Model=nameof(Contact), RefId=nameof(Contact.Id), RefLabel=nameof(Contact.DisplayName))]
    public int ContactId { get; set; }
    //...
}
```

Alternatively you can use `[Ref(None=true)]` to disable any implicit inferences and render the FK property Ids as-is.

When displaying referential data you can tell AutoQueryGrid to hide rendering the complex data references as well columns 
using `[Format(FormatMethods.Hidden)]`. 

## AutoQueryGrid Template Slots

AutoQueryGrid supports a number of [Vue slots](https://vuejs.org/guide/components/slots.html) to customize its built-in UIs, 
including `formheader` and `formfooter` slots to insert custom content before and after the Auto Create & Edit components forms:

```html
<template #formheader="{ form, type, apis, model, id }">
<template #formfooter="{ form, type, apis, model, id }">
```

This feature is used to implement [Locode's Audit History UI](/locode/auditing) for displaying the Audit History of each record in the bottom of the 
Edit Form for Authorized Users, implemented with:

```html
<AutoQueryGrid :key="store.opDataModel" ref="grid" :type="store.opDataModel">
    <template #formfooter="{ form, type, apis, model, id }">
        <AuditEvents v-if="form === 'edit' && canAccessCrudEvents" class="mt-4" :key="id" :type="type" :id="id" />
    </template>
</AutoQueryGrid>
```

Which loads the [AuditEvents.mjs](https://github.com/ServiceStack/ServiceStack/blob/main/ServiceStack/src/ServiceStack/modules/locode/components/AuditEvents.mjs)
component at the bottom of **Edit** forms, allowing Admin Users to inspect the Audit History of each record:

[![](/img/pages/vue/audit-history-job.png)](/locode/auditing)

Alternatively you can replace the entire Create and Edit Forms used with the `createform` and `editforms` slots:

```html
<template #createform="{ form, apis, type }">
<template #editform="{ form, apis, type }">
```

Additional toolbar buttons can be added with the `toolbarbuttons` slot, e.g:

```html
<template #toolbarbuttons="{ toolbarButtonClass }">
  <div class="pl-2 mt-1">
      <button type="button" @click="customAction" :class="toolbarButtonClass">
        <span class="whitespace-nowrap">My Action</span>
      </button>
  </div>
</template>
```

Alternatively you can replace the entire toolbar with your own with:

```html
<template #toolbar>
```

All other template slots are passed down to the embedded [DataGrid](/vue/datagrid) component where they can be used to customize column headers and cells.

## AutoQueryGrid Properties

Additional customizations available using AutoQueryGrid properties include:

```ts
defineProps<{
    filterDefinitions?: AutoQueryConvention[]
    id?: string
    apis?: string|string[]
    type?: string|InstanceType<any>|Function
    prefs?: ApiPrefs

    deny?: string|GridAllowOptions|GridAllowOptions[]
    hide?: string|GridShowOptions|GridShowOptions[]
    
    selectedColumns?:string[]|string
    toolbarButtonClass?: string
    tableStyle?: TableStyleOptions
    gridClass?: string
    grid2Class?: string
    grid3Class?: string
    grid4Class?: string
    tableClass?: string
    theadClass?: string
    tbodyClass?: string
    theadRowClass?: string
    theadCellClass?: string

    headerTitle?:(name:string) => string
    headerTitles?: {[name:string]:string}
    visibleFrom?: {[name:string]:Breakpoint}
    rowClass?:(model:any,i:number) => string
    rowStyle?:(model:any,i:number) => StyleValue | undefined

    apiPrefs?: ApiPrefs
    canFilter?:(column:string) => boolean
    disableKeyBindings?:(column:string) => boolean
    configureField?: (field:InputProp) => void
    skip?: number
    create?: boolean
    edit?: string|number
}>()

type ApiPrefs = {
    take?: number
    selectedColumns?: string[]    
}

type FormStyle  = "slideOver" | "card"
type TableStyle = "simple" | "fullWidth" | "stripedRows" | "whiteBackground" | "uppercaseHeadings"
  | "verticalLines"

type Breakpoint = "xs" | "sm" | "md" | "lg" | "xl" | "2xl"

type GridAllowOptions = 
  "filtering"   | "queryString" | "queryFilters"

type GridShowOptions = 
  "toolbar"     | "preferences" | "pagingNav"        | "pagingInfo"  | "downloadCsv" | 
  "refresh"     | "copyApiUrl"  | "resetPreferences" | "filtersView" | "newItem"
```

## AutoQueryGrid Events

Whilst the `headerSelected` and `rowSelected` events can be used to invoke custom functionality when column headers and rows are selected:

```ts
defineEmits<{
    (e: "headerSelected", name:string, ev:Event): void
    (e: "rowSelected", item:any, ev:Event): void
}>()
```

## Powers Locode

AutoQueryGrid is already used extensively and is the key component that enables [Locode's](/locode/) Instant Auto UI to manage your App's 
AutoQuery CRUD APIs.

[![](/img/pages/vue/blazor-gallery-contact.png)](/locode/)


# DataGrid Component
Source: https://docs.servicestack.net/vue/datagrid

<api-reference component="DataGrid<Model>"></api-reference>
## Default

In its most simple usage the DataGrid component can be used to render typed collections:

```html
<DataGrid :items="tracks" />

<script>
const tracks = [
    track("Everythings Ruined", "Faith No More", "Angel Dust", 1992),
    track("Lightning Crashes", "Live", "Throwing Copper", 1994),
    track("Heart-Shaped Box", "Nirvana", "In Utero", 1993),
    track("Alive", "Pearl Jam", "Ten", 1991),
]
</script>
```

Which by default will display all object properties:

<div class="not-prose">
<data-grid :items="tracks" class="mb-4"></data-grid>
</div>

Use **selected-columns** to control which columns to display and **header-titles** to use different column names:

```html
<DataGrid :items="tracks" :selected-columns="['year','album','name','artist']" 
          :header-titles="{ name:'Track' }" />
```
<div class="not-prose">
<data-grid :items="tracks" :selected-columns="['year','album','name','artist']" :header-titles="{ name:'Track' }" class="mb-4"></data-grid>
</div>

Which for a wrist-friendly alternative also supports a string of comma delimited column names, e.g:

```html
<DataGrid :items="tracks" selected-columns="year,album,name,artist" />
```

## Simple Customizations

Which columns are shown and how they're rendered is customizable with custom `<template #column>` definitions:

```html
<DataGrid :items="forecasts" class="max-w-screen-md" :table-style="['stripedRows','uppercaseHeadings']"
          :header-titles="{ temperatureC:'TEMP. (C)', temperatureF:'TEMP. (F)' }">
    <template #date-header>
        <span class="text-indigo-600">Date</span>
    </template>
    <template #date="{ date }">
        {{ new Intl.DateTimeFormat().format(new Date(date)) }}
    </template>
    <template #temperatureC="{ temperatureC }">
        {{ temperatureC }}&deg;
    </template>
    <template #temperatureF="{ temperatureF }">
        {{ temperatureF }}&deg;
    </template>
    <template #summary="{ summary }">{{ summary }}</template>
</DataGrid>
```

<custom class="not-prose mb-4"></custom>

Column names can be changed with a **header-titles** alias mapping, or dynamically with a **header-title** mapping function.

Alternatively for more advanced customizations, custom `<template #column-header>` definitions can be used 
to control how column headers are rendered.

If any custom column or header definitions are provided, only those columns will be displayed. 
Alternatively specify an explicit array of column names in **selected-columns**
to control the number and order or columns displayed.

## Responsive

A more advanced example showing how to implement a responsive datagrid defining what columns and Headers
are visible at different screen sizes using **visible-from** to specify which columns to show 
from different Tailwind responsive breakpoints and `<template #column-header>` definitions to 
collapse column names at small screen sizes:

```html
<template>
<DataGrid :items="bookings" 
      :visible-from="{ name:'xl', bookingStartDate:'sm', bookingEndDate:'xl' }"
      @header-selected="headerSelected"
      @row-selected="rowSelected" :is-selected="row => selected == row.id">
    <template #id="{ id }">
        <span class="text-gray-900" v-html="id"></span>
    </template>
    
    <template #name="{ name }">{{name}}</template>
    
    <template #roomNumber-header>
        <span class="hidden lg:inline">Room </span>No
    </template>

    <template #cost="{ cost }" v-html="currency(cost)"></template>
    
    <template #bookingStartDate-header>
        Start<span class="hidden lg:inline"> Date</span>
    </template>
    
    <template #bookingEndDate-header>
        End<span class="hidden lg:inline"> Date</span>
    </template>

    <template #createdBy-header>
        Employee
    </template>
    <template #createdBy="{ createdBy }" v-html="createdBy"></template>
</DataGrid>
</template>

<script setup lang="ts">
import { ref } from 'vue'
import { useFormatters } from '@servicestack/vue'
import { bookings } from '../data'
import { Booking } from '../dtos'

const { currency } = useFormatters()
const selected = ref()

function headerSelected(column:string) {
    console.log('headerSelected',column)
}
function rowSelected(row:Booking) {
    selected.value = selected.value === row.id ? null : row.id
    console.log('rowSelected', row)
}
</script>
```

<responsive class="not-prose mb-4"></responsive>

Behavior of the DataGrid can be customized with the `@header-selected` event to handle when column headers are selected to 
apply custom filtering to the **items** data source whilst the `@row-selected` event can be used to apply custom behavior 
when a row is selected.

## Using Formatters

Your App and custom templates can also utilize @servicestack/vue's [built-in formatting functions](/vue/use-formatters) from:

```js
import { useFormatters } from '@servicestack/vue'

const {
    Formats,             // Available format methods to use in <PreviewFormat />
    formatValue,         // Format any value or object graph
    currency,            // Format number as Currency
    bytes,               // Format number in human readable disk size
    link,                // Format URL as <a> link
    linkTel,             // Format Phone Number as <a> tel: link
    linkMailTo,          // Format email as <a> mailto: link
    icon,                // Format Image URL as an Icon
    iconRounded,         // Format Image URL as a full rounded Icon
    attachment,          // Format File attachment URL as an Attachment
    hidden,              // Format as empty string
    time,                // Format duration in time format
    relativeTime,        // Format Date as Relative Time from now
    relativeTimeFromMs,  // Format time in ms as Relative Time from now
    formatDate,          // Format as Date
    formatNumber,        // Format as Number
} = useFormatters()
```

Many of these formatting functions return rich HTML markup which will need to be rendered using Vue's **v-html** directive:

```html
<span v-html="formatValue(value)"></span>
```

The [PreviewFormat](/vue/formats) component also offers a variety of flexible formatting options.

## Table Styles

The appearance of DataGrids can use **tableStyles** to change to different
[Tailwind Table Styles](https://tailwindui.com/components/application-ui/lists/tables), e.g:

### Default (Striped Rows)

```html
<DataGrid :items="tracks" />
```

<div class="not-prose">
<data-grid :items="tracks"></data-grid>
</div>

### Simple

```html
<DataGrid :items="tracks" table-style="simple" />
```

<div class="not-prose">
<data-grid :items="tracks" table-style="simple"></data-grid>
</div>

### Uppercase Headings

```html
<DataGrid :items="tracks" table-style="uppercaseHeadings" />
```

<div class="not-prose">
<data-grid :items="tracks" table-style="uppercaseHeadings"></data-grid>
</div>

### Vertical Lines

```html
<DataGrid :items="tracks" table-style="verticalLines" />
```

<div class="not-prose">
<data-grid :items="tracks" table-style="verticalLines"></data-grid>
</div>

### White Background

```html
<DataGrid :items="tracks" table-style="whiteBackground" />
```

<div class="not-prose">
<data-grid :items="tracks" table-style="whiteBackground"></data-grid>
</div>

### Full Width

```html
<DataGrid :items="tracks" table-style="fullWidth" />
```

<div class="not-prose">
<data-grid :items="tracks" table-style="fullWidth"></data-grid>
</div>

### Full Width, Uppercase with Vertical Lines

```html
<DataGrid :items="tracks" :table-style="['uppercaseHeadings', 'fullWidth', 'verticalLines']" />
```

<div class="not-prose">
<data-grid :items="tracks" :table-style="['uppercaseHeadings', 'fullWidth', 'verticalLines']"></data-grid>
</div>

## Using App Metadata

By default DataGrid will render values using its default configured formatters, so results with strings, numbers and defaults
will display a stock standard resultset:

```html
<DataGrid :items="bookings" />
```
<div class="not-prose prose-table">
<data-grid :items="bookings" class="mb-4"></data-grid>
</div>

Another option for formatting this dataset is to use the rich [format functions](/locode/formatters) in ServiceStack
to annotate the DTOs with how each field should be formatted, e.g:

```csharp
public class Booking
{
    [AutoIncrement]
    public int Id { get; set; }
    public string Name { get; set; }
    public RoomType RoomType { get; set; }
    public int RoomNumber { get; set; }

    [IntlDateTime(DateStyle.Long)]
    public DateTime BookingStartDate { get; set; }

    [IntlRelativeTime]
    public DateTime? BookingEndDate { get; set; }

    [IntlNumber(Currency = NumberCurrency.USD)]
    public decimal Cost { get; set; }
}
```

Which can be enabled when using [useMetadata](/vue/use-metadata) by specifying the `MetadataType` for the DataGrid's results in **type**:

```html
<DataGrid :items="bookings" type="Booking" />
```

<div class="not-prose prose-table">
<data-grid :items="bookings" type="Booking" class="mb-4"></data-grid>
</div>

Declaratively annotating your DTOs with preferred formatting hints makes this rich metadata information available to clients where
it's used to enhance ServiceStack's built-in UI's and Components like:

 - [API Explorer](/api-explorer)
 - [Locode](/locode/)
 - [Blazor Tailwind Components](/templates/blazor-components)


# Auto Form Components
Source: https://docs.servicestack.net/vue/autoform

<api-reference Component="AutoForm"></api-reference>
## AutoForm

The `AutoForm` component is a generic form component that can be used to create and wire a traditional Form for any Request DTO definition
where successful responses can be handled the `@success` event, e.g:

```html
<AutoForm type="QueryBookings" @success="onSuccess" />
<div v-if="results">
    <h3 class="py-4 text-2xl">Results</h3>
    <HtmlFormat :value="results" />
</div>

<script setup>
const results = ref([])
const onSuccess = response => results.value = response.results
</script>
```

<div class="py-8 not-prose">
    <auto-form class="mx-auto max-w-3xl" type="QueryBookings" @success="onSuccess"></auto-form>
    <div v-if="results">
        <h3 class="py-4 text-2xl">Results</h3>
        <html-format :value="results"></html-format>
    </div>
</div>

These Auto Form components are customizable with the [declarative C# UI Attributes](/locode/declarative#ui-metadata-attributes) where you can 
override the form's **heading** with `[Description]` and include a **subHeading** with `[Notes]` which supports rich HTML markup.

**AutoForm Properties**

Alternatively they can be specified in the components properties:

```ts
defineProps<{
    type: string|InstanceType<any>|Function
    modelValue?: ApiRequest|any
    heading?: string
    subHeading?: string
    showLoading?: boolean
    jsconfig?: string         //= eccn,edv
    configureField?: (field:InputProp) => void

    /* Default Styles */
    formClass?: string        //= shadow sm:rounded-md
    innerFormClass?: string
    bodyClass?: string
    headerClass?: string      //= p-6
    buttonsClass?: string     //= mt-4 px-4 py-3 bg-gray-50 dark:bg-gray-900 sm:px-6 flex justify-between
    headingClass?: string     //= text-lg font-medium leading-6 text-gray-900 dark:text-gray-100
    subHeadingClass?: string
    submitLabel?: string      //= Submit
}>()
```

Both `@success` and `@error` events are fired after each API call, although built-in validation binding means it's typically unnecessary to manually 
handle error responses.

```ts
defineEmits<{
    (e:'success', response:any): void
    (e:'error', error:ResponseStatus): void
    (e:'update:modelValue', model:any): void
}>()
```

**Model Binding**

Forms can be bound to a Request DTO model where it can be used to pre-populate the Forms default values and Request DTO whereby specifying a **type** 
is no longer necessary:

```ts
<AutoForm v-model="request" />

<script setup>
const request = ref(new QueryBookings({ skip:1, take:2, orderBy:'Name' }))
</script>
```

<div class="not-prose">
    <auto-form class="mx-auto max-w-3xl not-prose" v-model="request" type="QueryBookings"></auto-form>
</div>

<api-reference Component="AutoCreateForm"></api-reference>
## Create Form

`AutoCreateForm` can be used to create an automated form based on a [AutoQuery CRUD](/autoquery/crud) Create Request DTO definition which can be rendered in a traditional inline Form with **card** formStyle option, e.g:

```html
<AutoCreateForm type="CreateBooking" formStyle="card" />
```

<div class="not-prose py-8">
    <auto-create-form class="mx-auto max-w-3xl" type="CreateBooking" form-style="card"></auto-create-form>
</div>

By default Auto Forms are rendered in a `SlideOver` dialog:

```html
<AutoCreateForm type="CreateBooking" />
```

<iframe src="/pages/vue/autoform/new.html" class="border-none h-[45em] w-[1330px] -ml-40 mb-4 relative z-20"></iframe>

These Auto Forms are powered by the rich [App Metadata](/vue/use-metadata) surrounding your APIs,
which contain all the necessary metadata to invoke the API and bind any contextual validation errors adjacent to the invalid field inputs.

<api-reference id="edit-form" component="AutoEditForm"></api-reference>
## Edit Form

`AutoEditForm` can be used to render an automated form based on Update and Delete
[AutoQuery CRUD](/autoquery/crud) APIs which also makes use of **heading** and **sub-heading** customization options:

```html
<AutoEditForm v-model="booking" type="UpdateBooking" deleteType="DeleteBooking" 
    heading="Change an existing Room Booking" sub-heading="Manage reservations for MyApp hotels." />
```

<iframe src="/pages/vue/autoform/edit.html" class="border-none h-[46em] w-[1330px] -ml-40 mb-4 relative z-20"></iframe>

The same form rendered in a traditional inline form with a **card** formStyle with some more advanced
customization examples using rich markup in custom `<template #heading>` and `<template #sub-heading>` slots:

```html
<AutoEditForm v-model="booking" formStyle="card" type="UpdateBooking" deleteType="DeleteBooking">
  <template #heading>
    <h3 class="text-xl font-semibold text-green-600">Change an existing Room Booking</h3>
  </template>
  <template #sub-heading>
    <p>
      Here are some 
      <TextLink href="https://youtu.be/rSFiikDjGos">good tips on making room reservations 
        <Icon class='inline-block' icon="lucide:external-link" />
      </TextLink>
    </p>
  </template>
</AutoEditForm>
```

<div class="not-prose">
    <auto-edit-form class="mx-auto max-w-3xl mb-4" v-model="booking" form-style="card" type="UpdateBooking" deleteType="DeleteBooking">
        <template #heading>
            <h3 class="text-xl font-semibold text-green-600">Change an existing Room Booking</h3>
        </template>
        <template #sub-heading>
            <p>
                Here are some <text-link href="https://youtu.be/rSFiikDjGos">good tips on making room reservations 
                    <svg class="inline-block" xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24"><path fill="none" stroke="currentColor" stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M18 13v6a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2V8a2 2 0 0 1 2-2h6m4-3h6v6m-11 5L21 3"/></svg>
                </text-link>
            </p>
        </template>
    </auto-edit-form>
</div>

The forms behavior and appearance is further customizable with the
[API annotation](/locode/declarative#annotate-apis), declarative [validation](/locode/declarative#type-validation-attributes)
and the custom [Field and Input](/locode/declarative#custom-fields-and-inputs) attributes, e.g:

```csharp
[Description("Update an existing Booking")]
[Notes("Find out how to create a <a href='https://youtu.be/rSFiikDjGos'>C# Bookings App from Scratch</a>")]
[Route("/booking/{Id}", "PATCH")]
[ValidateHasRole("Employee")]
[AutoApply(Behavior.AuditModify)]
public class UpdateBooking : IPatchDb<Booking>, IReturn<IdResponse>
{
    public int Id { get; set; }
    public string? Name { get; set; }
    public RoomType? RoomType { get; set; }
    [ValidateGreaterThan(0)]
    public int? RoomNumber { get; set; }
    [ValidateGreaterThan(0)]
    public decimal? Cost { get; set; }
    public DateTime? BookingStartDate { get; set; }
    public DateTime? BookingEndDate { get; set; }
    [Input(Type = "textarea")]
    public string? Notes { get; set; }
    public string? CouponId { get; set; }
    public bool? Cancelled { get; set; }
}
```

Where they can be used to customize Auto Form's appearance from annotations on C# Server DTOs:

```html
<AutoEditForm v-model="booking" formStyle="card" type="UpdateBooking" deleteType="DeleteBooking" />
```

<div class="not-prose">
<auto-edit-form class="mx-auto max-w-3xl" v-model="booking" form-style="card" type="UpdateBooking" deleteType="DeleteBooking"></auto-edit-form>
</div>

<api-reference component="AutoFormFields"></api-reference>
## Form Fields

For more advanced customization of a Forms appearance and behavior, `AutoFormFields` can be used to just render the Form's fields (with validation binding) inside a custom Form which can submit the data-bound populated Request DTO to invoke the API, e.g:

```html
<template>
<form v-if="request" @submit.prevent="submit">
    <div class="shadow sm:overflow-hidden sm:rounded-md">
        <div class="space-y-6 py-6 px-4 sm:p-6 bg-white dark:bg-black">
            <div>
                <h3 class="text-lg font-medium leading-6 text-gray-900 dark:text-gray-100">
                    Change an existing Room Booking
                </h3>
                <p class="notes mt-1 text-sm text-gray-500 dark:text-gray-400">
                    Find out how to quickly create a 
                    <a class='svg-external' target='_blank' href='https://youtu.be/rSFiikDjGos'>
                        C# Bookings App from Scratch
                    </a>
                </p>
            </div>

            <AutoFormFields v-model="request" :api="api" />

        </div>
        <div class="bg-gray-50 dark:bg-gray-800 px-4 py-3 text-right sm:px-12">
            <PrimaryButton>Save</PrimaryButton>
        </div>
    </div>
</form>
</template>

<script setup lang="ts">
import { onMounted, ref } from 'vue'
import { ApiResponse } from '@servicestack/client'
import { useClient, useMetadata } from '@servicestack/vue'
import { QueryBookings, UpdateBooking } from '../dtos'

const { toFormValues } = useMetadata()
const client = useClient()

let api = ref<ApiResponse>()
let request = ref<UpdateBooking>()

async function submit(e:Event) {
    api.value = await client.api(request.value!)
}

onMounted(async () => {
    let api = await client.api(new QueryBookings({ id: 1 }))
    if (api.succeeded) {
        request.value = new UpdateBooking(toFormValues(api.response!.results[0]))
    }
})
</script>
```

<div class="not-prose">
    <fields class="my-4 mx-auto max-w-screen-md"></fields>
</div>

`toFormValues` is used when updating the data bound `request` DTO to convert API response values into the required format that HTML Inputs expect.


# Custom Auto Forms
Source: https://docs.servicestack.net/vue/custom-autoforms

## Custom AutoForm UIs

[CoffeeShop's Admin UI](https://servicestack.net/posts/building-typechat-coffeeshop-modelling) is a good example of the rapid development model 
of AutoQuery and Vue's [AutoQueryGrid](/vue/autoquerygrid) and 
[Auto Form](/vue/autoform) Components was nearly able to develop the entire CRUD management UI using just AutoQuery's Typed DTOs.

The one Form that it wasn't able to generate the entire UI for is its **Many-to-Many** `CategoryOption` relationship
which requires a custom AutoForm component to be able to specify which Options a category of CoffeeShop Products can have.

<div class="not-prose">
    <div class="mb-16 flex justify-center">
        <iframe style="width:896px;height:504px;" src="https://www.youtube.com/embed/MjNqPAXLH5w?si=HDFs2FnYhtuZSDWL&amp;start=404" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
    </div>
</div>


### Implementing Many to Many CategoryOption Admin UI

The easier way to implement this functionality would be to have the UI call an API each time an `Option` was added or removed
to a `Category`. The problem with this approach is that it doesn't match the existing behavior where if a User **cancels**
a form they'd expect for none of their changes to be applied.

To implement the desired functionality we'll instead create a custom `UpdateCategory` implementation that also
handles any changes to `CategoryOption` using new `AddOptionIds` and `RemoveOptionIds` properties that we'll want 
rendered as **hidden** inputs in our HTML Form with:

```csharp
public class UpdateCategory : IPatchDb<Category>, IReturn<Category>
{
    public int Id { get; set; }
    public string? Name { get; set; }
    public string? Description { get; set; }
    [Input(Type = "tag"), FieldCss(Field = "col-span-12")]
    public List<string>? Sizes { get; set; }
    [Input(Type = "tag"), FieldCss(Field = "col-span-12")]
    public List<string>? Temperatures { get; set; }
    public string? DefaultSize { get; set; }
    public string? DefaultTemperature { get; set; }
    [Input(Type = "file"), UploadTo("products")]
    public string? ImageUrl { get; set; }

    [Input(Type = "hidden")]
    public List<int>? AddOptionIds { get; set; }
 
    [Input(Type = "hidden")]
    public List<int>? RemoveOptionIds { get; set; }
}
```

## Custom AutoQuery Implementation

The [Custom AutoQuery Implementation](/autoquery/rdbms#custom-autoquery-implementations)
in [CoffeeShopServices.cs](https://github.com/NetCoreApps/TypeChatExamples/blob/main/TypeChatExamples.ServiceInterface/CoffeeShopServices.cs) 
contains the custom implementation which continues to utilize AutoQuery's **Partial Update** functionality if there's any changes to update, 
as well as removing or adding any Options the user makes to the `Category`: 

```csharp
public class CoffeeShopServices(IAutoQueryDb autoQuery) : Service
{
    public async Task<object> Any(UpdateCategory request)
    {
        // Perform all RDBMS Updates within the same Transaction
        using var trans = Db.OpenTransaction();

        Category? response = null;
        var ignore = new[]{nameof(request.Id),nameof(request.AddOptionIds),nameof(request.RemoveOptionIds)};
        // Only call AutoQuery Update if there's something to update
        if (request.ToObjectDictionary().HasNonDefaultValues(ignoreKeys:ignore))
        {
            response = (Category) await autoQuery.PartialUpdateAsync<Category>(request, Request, Db);
        }
        if (request.RemoveOptionIds?.Count > 0)
        {
            await Db.DeleteAsync<CategoryOption>(x => 
                x.CategoryId == request.Id && request.RemoveOptionIds.Contains(x.OptionId));
        }
        if (request.AddOptionIds?.Count > 0)
        {
            await Db.InsertAllAsync(request.AddOptionIds.Map(id => 
                new CategoryOption { CategoryId = request.Id, OptionId = id }));
        }
        trans.Commit();

        response ??= request.ConvertTo<Category>();
        return response;
    }
}
```

## Custom AutoForm Component

It now needs to implement a Custom UI that Adds/Removes Options from a Category which is done in a custom `CategoryOptions`
Vue Component that displays all the Category Options with a button to remove existing ones and a Select Input to 
add non existing options.

The purpose of the component is to populate the `addOptionIds` field with Option Ids that should be added and `removeOptionIds`
with Ids to be removed, which updates the Request DTO of the parent Form Model with the `update:modelValue` event:

```js
const CategoryOptions = {
    template:`
         <div>
            <ul v-for="optionType in currentOptionTypes">
                <li class="py-1 flex justify-between">
                    <span>
                        {{optionType}}
                    </span>
                    <span>
                        <svg class="w-6 h-6 text-red-600 hover:text-red-800 cursor-pointer" @click="removeOption(optionType)" xmlns='http://www.w3.org/2000/svg' width='1024' height='1024' viewBox='0 0 1024 1024'>
                            <title>Remove Option</title>
                            <path fill='currentColor' d='M512 64a448 448 0 1 1 0 896a448 448 0 0 1 0-896zM288 512a38.4 38.4 0 0 0 38.4 38.4h371.2a38.4 38.4 0 0 0 0-76.8H326.4A38.4 38.4 0 0 0 288 512z'/>
                        </svg>
                    </span>
                </li> 
            </ul>
            <div class="flex justify-between items-center">
                <select-input class="flex-grow" @change="addOption" :values="['',...options.filter(x => !currentOptionTypes.includes(x.type)).map(x => x.type)]"></select-input>
                <svg class="ml-2 w-6 h-6 text-green-600" xmlns='http://www.w3.org/2000/svg' width='24' height='24' viewBox='0 0 24 24'>
                    <title>Add Option</title>
                    <path fill='currentColor' d='M11 17h2v-4h4v-2h-4V7h-2v4H7v2h4v4Zm1 5q-2.075 0-3.9-.788t-3.175-2.137q-1.35-1.35-2.137-3.175T2 12q0-2.075.788-3.9t2.137-3.175q1.35-1.35 3.175-2.137T12 2q2.075 0 3.9.788t3.175 2.137q1.35 1.35 2.138 3.175T22 12q0 2.075-.788 3.9t-2.137 3.175q-1.35 1.35-3.175 2.138T12 22Z'/>
                </svg>            
            </div>
         </div>
    `,
    props:['type','id','modelValue'],
    emits:['update:modelValue'],
    setup(props, { emit }) {
        const client = useClient()
        const options = ref([])
        const model = props.modelValue

        model.addOptionIds ??= []
        model.removeOptionIds ??= []
        const origOptionIds = model.categoryOptions?.map(x => x.optionId) || []

        const currentOptionIds = computed(() => [...origOptionIds, ...model.addOptionIds]
            .filter(x => !model.removeOptionIds.includes(x)))
        const currentOptionTypes = computed(() =>
            currentOptionIds.value.map(id => options.value.find(x => x.id === id)?.type).filter(x => !!x))

        function addOption(e) {
            const optionType = e.target.value
            if (!optionType) return
            const option = options.value.find(x => x.type === optionType)
            if (model.removeOptionIds.includes(option.id))
                model.removeOptionIds = model.removeOptionIds.filter(id => id !== option.id)
            else if (!model.addOptionIds.includes(option.id))
                model.addOptionIds.push(option.id)
            emit('update:modelValue', model)
        }
        function removeOption(optionType) {
            const option = options.value.find(x => x.type === optionType)
            if (model.addOptionIds.includes(option.id))
                model.addOptionIds = model.addOptionIds.filter(id => id !== option.id)
            else if (!model.removeOptionIds.includes(option.id))
                model.removeOptionIds.push(option.id)
        }

        onMounted(async () => {
            const api = await client.api(new QueryOptions({ orderBy:'id' }))
            options.value = api.response.results || []
            emit('update:modelValue', model)
        })

        return { options, addOption, removeOption, currentOptionTypes }
    }
}
```

Which is then attached to the AutoQueryGrid Form Components using its `<template #formfooter>` to include it in the
bottom of the Create and Edit Form Components:

```js
const sections = {
    Categories: {
        type: 'Category',
        component: {
            components: { CategoryOptions },
            template:`
            <AutoQueryGrid :type="type" selectedColumns="imageUrl,id,name,defaultSize,products"
                    :headerTitles="{ imageUrl: ' ' }" :canFilter="x => x != 'ImageUrl'">
                <template #imageUrl="{ imageUrl }">
                    <Icon :src="imageUrl" class="w-8 h-8 rounded-full" />
                </template>
                <template #id="{ id }">{{id}}</template>
                <template #name="{ name }">{{name}}</template>
                <template #description="{ description }">{{description}}</template>
                <template #defaultSize="{ defaultSize }">{{defaultSize}}</template>
                <template #products="{ products }">{{ products.map(x => x.name).join(', ') }}</template>
                <template #formfooter="{ form, type, apis, model, id, updateModel }">
                    <div class="w-1/2 mt-4 px-4 sm:px-6">
                        <h3 class="text-lg font-semibold">Options</h3>
                        <CategoryOptions v-if="form === 'edit'" :key="id" :type="type" :id="id" v-model="model" @update:modelValue="updateModel(model)" />
                    </div>
                </template>                
            </AutoQueryGrid>`,
        },
    },
    //...
}
```

With those finishing touches CoffeeShop's back-end Admin UI is now complete which now allows shop owners to manage their entire database:

:::{.shadow .rounded-sm}
[![](/img/pages/autoquery/portal-update-category.png)](/img/pages/autoquery/portal-update-category.png)
:::


# Form Inputs Components
Source: https://docs.servicestack.net/vue/form-inputs

<api-reference component="TextInput"></api-reference>
## Bookings Form

The `TextInput`, `SelectInput`, `CheckboxInput` and `TextAreaInput` contains the most popular
Input controls used by C# POCOs which can be bound directly to Request DTOs and includes support for
[declarative](/declarative-validation) and [Fluent Validation](/validation) binding.

```html
<form @submit.prevent="submit">
    <div class="shadow sm:overflow-hidden sm:rounded-md">
        <div class="space-y-6 py-6 px-4 sm:p-6 bg-white dark:bg-black">
            <div>
                <h3 class="text-lg font-medium leading-6 text-gray-900 dark:text-gray-100">
                    Update an existing Booking
                </h3>
            </div>
            <fieldset>
                <ErrorSummary :except="visibleFields" class="mb-4" />
                <div class="grid grid-cols-6 gap-6">
                    <div class="col-span-6 sm:col-span-3">
                        <TextInput id="name" v-model="request.name" required placeholder="Name for this booking" />
                    </div>
                    <div class="col-span-6 sm:col-span-3">
                        <SelectInput id="roomType" v-model="request.roomType" :options="enumOptions('RoomType')" />
                    </div>
                    <div class="col-span-6 sm:col-span-3">
                        <TextInput type="number" id="roomNumber" v-model="request.roomNumber" min="0" required />
                    </div>
                    <div class="col-span-6 sm:col-span-3">
                        <TextInput type="number" id="cost" v-model="request.cost" min="0" required />
                    </div>
                    <div class="col-span-6 sm:col-span-3">
                        <TextInput type="date" id="bookingStartDate" v-model="request.bookingStartDate" required />
                    </div>
                    <div class="col-span-6 sm:col-span-3">
                        <TextInput type="date" id="bookingEndDate" v-model="request.bookingEndDate" />
                    </div>
                    <div class="col-span-6">
                        <TextareaInput id="notes" v-model="request.notes" placeholder="Notes about this booking" class="h-24" />
                    </div>
                </div>
            </fieldset>
        </div>
        <div class="mt-4 bg-gray-50 dark:bg-gray-800 px-4 py-3 text-right sm:px-12">
            <div class="flex justify-between space-x-3">
                <div>
                    <ConfirmDelete v-if="canDelete" @delete="onDelete">Delete</ConfirmDelete>
                </div>
                <div>
                    <PrimaryButton @click="submit">Update Booking</PrimaryButton>
                </div>
            </div>
        </div>
    </div>
</form>
```

<bookings-form :id="1" class="not-prose mb-4"></bookings-form>

Which can be wired up to handle querying, updating and deleting including limiting functionality to authorized users with:

```html
<script setup lang="ts">
import { computed, ref, watchEffect } from 'vue'
import { useMetadata, useAuth, useClient } from '@servicestack/vue'
import { DeleteBooking, QueryBookings, UpdateBooking } from '../dtos'

const props = defineProps<{
    id: number
}>()
const emit = defineEmits<{
    (e: 'done'): void
}>()

const { enumOptions, toFormValues } = useMetadata()

const visibleFields = "name,roomType,roomNumber,bookingStartDate,bookingEndDate,cost,notes"

const { hasRole, user, isAuthenticated } = useAuth()
const canDelete = computed(() => hasRole('Manager'))
const client = useClient()
const request = ref(new UpdateBooking())

watchEffect(async () => {
    const api = await client.api(new QueryBookings({ id: props.id }))
    if (api.succeeded) {
        request.value = new UpdateBooking(toFormValues(api.response?.results[0]))
    }
})

async function submit(e:Event) {
    const api = await client.api(request.value)
    if (api.succeeded) close()
}
async function onDelete() {
    const api = await client.apiVoid(new DeleteBooking({ id: props.id }))
    if (api.succeeded) close()
}

const close = () => emit('done')
</script>
```

This also shows how we can utilize `enumOptions` from our [App Metadata](/vue/use-metadata) to populate select drop downs from C# enums.


# FileInput Component
Source: https://docs.servicestack.net/vue/fileinput

The `<FileInput>` component beautifies the browsers default HTML file Input, supporting both Single file: 

```html
<FileInput id="profileUrl" label="Single File Upload" v-model="contact.profileUrl" />
```
<div class="not-prose">
<file-input id="profileUrl" label="Single File Upload" v-model="contact.profileUrl" class="max-w-lg mb-4"></file-input>
</div>

and Multiple File Uploads:

```html
<FileInput id="profileUrls" label="Multiple File Uploads" multiple :files="contact.files" />
```
<div class="not-prose">
<file-input id="profileUrls" label="Multiple File Uploads" multiple :files="files" class="max-w-lg not-prose mb-4"></file-input>
</div>

Use **files** when your binding to a `UploadedFile` complex type or **values** when binding to a `string[]` of file paths.
When binding to relative paths, absolute URLs are resolved using [assetsPathResolver](/vue/use-config).

## Invoking APIs containing uploaded files

When uploading files, you'll need to submit API requests using the `apiForm` or `apiFormVoid` methods to send
a populated `FormData` instead of a Request DTO, e.g:

```html
<form @submit.prevent="submit">
    <FileInput id="profileUrls" label="Multiple File Uploads" multiple :files="files" />
    <PrimaryButton>Save</PrimaryButton>
</form>

<script setup lang="ts">
import { useClient } from "@servicestack/vue"
import { CreateContact } from "/mjs/dtos.mjs"

const client = useClient()
async function submit(e:Event) {
    const form = e.target as HTMLFormElement
    const api = await client.apiForm(new CreateContact(), new FormData(form))
    if (api.succeeded) {
        //...
    }
}
</script>
```

## Integrates with Managed File Uploads

Using [Managed File Uploads](/locode/files-overview) is a productive solution for easily managing file uploads where you can declaratively specify
which location uploaded files should be written to, e.g:

```csharp
public class UpdateContact : IPatchDb<Contact>, IReturn<Contact>
{
    public int Id { get; set; }
    [ValidateNotEmpty]
    public string? FirstName { get; set; }
    [ValidateNotEmpty]
    public string? LastName { get; set; }
    [Input(Type = "file"), UploadTo("profiles")]
    public string? ProfileUrl { get; set; }
    public int? SalaryExpectation { get; set; }
    [ValidateNotEmpty]
    public string? JobType { get; set; }
    public int? AvailabilityWeeks { get; set; }
    public EmploymentType? PreferredWorkType { get; set; }
    public string? PreferredLocation { get; set; }
    [ValidateNotEmpty]
    public string? Email { get; set; }
    public string? Phone { get; set; }
    [Input(Type = "tag"), FieldCss(Field = "col-span-12")]
    public List<string>? Skills { get; set; }
    [Input(Type = "textarea")]
    [FieldCss(Field = "col-span-12 text-center", Input = "h-48", Label= "text-xl text-indigo-700")]
    public string? About { get; set; }
}
```

This metadata information is also available to [AutoForm components](/vue/autoform) which supports invoking APIs with uploaded files:

```html
<AutoEditForm type="UpdateContact" v-model="contact" formStyle="card" />
```
<div class="not-prose">
<auto-edit-form id="updatecontact" data-id="UpdateContact" type="UpdateContact" v-model="contact" form-style="card" class="not-prose max-w-3xl"></auto-edit-form>
</div>


# TagInput Component
Source: https://docs.servicestack.net/vue/taginput

The `TagInput` component provides a user friendly control for managing a free-form `List<string>` tags or symbols
which is also supported in declarative Auto Forms using the `[Input(Type="tag")]` attribute as seen in the 
**UpdateContact** example using the [AutoForm components](/vue/autoform):

```html
<AutoEditForm type="UpdateContact" v-model="contact" formStyle="card" />
```
<auto-edit-form id="updatecontact" data-id="UpdateContact" type="UpdateContact" v-model="contact" form-style="card" class="not-prose max-w-3xl mb-4"></auto-edit-form>

Generated from the **UpdateContact** C# Request DTO:

```csharp
public class UpdateContact : IPatchDb<Contact>, IReturn<Contact>
{
    public int Id { get; set; }
    [ValidateNotEmpty]
    public string? FirstName { get; set; }
    [ValidateNotEmpty]
    public string? LastName { get; set; }
    [Input(Type = "file"), UploadTo("profiles")]
    public string? ProfileUrl { get; set; }
    public int? SalaryExpectation { get; set; }
    [ValidateNotEmpty]
    public string? JobType { get; set; }
    public int? AvailabilityWeeks { get; set; }
    public EmploymentType? PreferredWorkType { get; set; }
    public string? PreferredLocation { get; set; }
    [ValidateNotEmpty]
    public string? Email { get; set; }
    public string? Phone { get; set; }
    [Input(Type = "tag"), FieldCss(Field = "col-span-12")]
    public List<string>? Skills { get; set; }
    [Input(Type = "textarea")]
    [FieldCss(Field = "col-span-12 text-center", Input = "h-48", Label= "text-xl text-indigo-700")]
    public string? About { get; set; }
}
```

Alternatively `<TagInput>` can be used in Custom Forms directly by binding to a `List<string>` or `string[]` model:

<api-reference component="TagInput"></api-reference>
## Custom Form

```html
<form @submit.prevent="submit">
    <div class="shadow sm:rounded-md bg-white dark:bg-black">
        <div class="relative px-4 py-5 sm:p-6">
            <fieldset>
                <legend class="text-base font-medium text-gray-900 dark:text-gray-100 text-center mb-4">
                    TagInput Examples
                </legend>
                <ErrorSummary :except="visibleFields" />
                <div class="grid grid-cols-12 gap-6">
                    <div class="col-span-6">
                        <TextInput v-model="request.firstName" />
                    </div>
                    <div class="col-span-6">
                        <TextInput v-model="request.lastName" />
                    </div>
                    <div class="col-span-12">
                        <TagInput v-model="request.skills" label="Technology Skills" 
                            :allowableValues="['c#','servicestack','vue','.net','typescript']" />
                    </div>
                </div>
            </fieldset>
        </div>
        <div class="mt-4 px-4 py-3 bg-gray-50 dark:bg-gray-900 sm:px-6 flex flex-wrap justify-between">
            <div></div>
            <div class="flex justify-end">
                <SecondaryButton class="mr-4">Cancel</SecondaryButton>
                <PrimaryButton type="submit">Submit</PrimaryButton>
            </div>
        </div>
    </div>
</form>
```

<form data-id="TagInputExamples" class="max-w-screen-md not-prose" @submit.prevent="submit">
    <div class="shadow sm:rounded-md bg-white dark:bg-black">
        <div class="relative px-4 py-5 sm:p-6">
            <fieldset>
                <legend class="text-base font-medium text-gray-900 dark:text-gray-100 text-center mb-4">
                    TagInput Examples
                </legend>
                <error-summary :except="visibleFields"></error-summary>
                <div class="grid grid-cols-12 gap-6">
                    <div class="col-span-6">
                        <text-input v-model="request.firstName"></text-input>
                    </div>
                    <div class="col-span-6">
                        <text-input v-model="request.lastName"></text-input>
                    </div>
                    <div class="col-span-12">
                        <tag-input v-model="request.skills" label="Technology Skills"
                            :allowable-values="['c#','servicestack','vue','.net','typescript']"></tag-input>
                    </div>
                </div>
            </fieldset>
        </div>
        <div class="mt-4 px-4 py-3 bg-gray-50 dark:bg-gray-900 sm:px-6 flex flex-wrap justify-between">
            <div></div>
            <div class="flex justify-end">
                <secondary-button class="mr-4">Cancel</secondary-button>
                <primary-button type="submit">Submit</primary-button>
            </div>
        </div>
    </div>
</form>


<api-reference component="TagInput"></api-reference>
## Allowable Values

The list of allowable values can also be populated on C# Request DTO from a JavaScript expression:

```csharp
public class MyRequest
{
    [Input(Type = "tag", Options="{ allowableValues: ['c#','servicestack','vue'] }")]
    public List<string>? Skills { get; set; }
}
```

Or from a [#Script Expression](https://sharpscript.net) in `EvalEvalAllowableValues` where it can be populated from a static list, e.g:

```csharp
public class MyRequest
{
    [Input(Type = "tag", EvalEvalAllowableValues="['c#','servicestack','vue']")]
    public List<string>? Skills { get; set; }
}
```

Or sourced from a C# Expression, e.g:

```csharp
public class MyRequest
{
    [Input(Type = "tag", EvalEvalAllowableValues="AppData.Tags")]
    public List<string>? Skills { get; set; }
}
```

Where it can be populated from a dynamic data source like from an RDBMS populated in your AppHost on Startup, e.g:

```csharp
ScriptContext.Args[nameof(AppData)] = new AppData {
    Tags = db.Select<Tag>().Select(x => x.Name).ToList()
};
```


# Combobox Component
Source: https://docs.servicestack.net/vue/combobox

The `Combobox` component provides an Autocomplete Input optimized for searching a List of string values, Key Value Pairs or Object Dictionary, e.g:

```html
<div class="grid grid-cols-12 gap-6">
  <Combobox id="Strings" class="col-span-4" v-model="strings" :values="['Alpha','Bravo','Charlie']" />
  <Combobox id="Object"  class="col-span-4" v-model="objects" :options="{ A:'Alpha', B:'Bravo', C:'Charlie' }" />
  <Combobox id="Pairs"   class="col-span-4" v-model="pairs"   label="Multiple from Pairs" multiple
    :entries="[{key:'A',value:'Alpha'}, {key:'B',value:'Bravo'}, {key:'C',value:'Charlie'}]" />
</div>
```

<div class="not-prose grid grid-cols-12 gap-6">
  <combobox id="Strings" class="col-span-4" v-model="strings" :values="['Alpha','Bravo','Charlie']"></combobox>
  <combobox id="Object"  class="col-span-4" v-model="objects" :options="{ A:'Alpha', B:'Bravo', C:'Charlie' }"></combobox>
  <combobox id="Pairs"   class="col-span-4" v-model="pairs"   label="Multiple from Pairs" multiple
    :entries="[{key:'A',value:'Alpha'}, {key:'B',value:'Bravo'}, {key:'C',value:'Charlie'}]"></combobox>
</div>

Which supports populating both a single string value or multiple strings in an Array with **multiple** property.

<api-reference component="Combobox"></api-reference>
## Auto Forms

Combobox components can also be used in [Auto Form Components](/vue/autoform) on `string` or string collection properties
with the `[Input(Type="combobox")]` [declarative UI Attribute](/locode/declarative#ui-metadata-attributes) on C# Request DTOs, e.g:

```csharp
public class ComboBoxExamples : IReturn<ComboBoxExamples>, IPost
{
    [Input(Type="combobox", Options = "{ allowableValues:['Alpha','Bravo','Charlie'] }")]
    public string? SingleClientValues { get; set; }

    [Input(Type="combobox", Options = "{ allowableValues:['Alpha','Bravo','Charlie'] }", Multiple = true)]
    public List<string>? MultipleClientValues { get; set; }

    [Input(Type="combobox", EvalAllowableValues = "['Alpha','Bravo','Charlie']")]
    public string? SingleServerValues { get; set; }

    [Input(Type="combobox", EvalAllowableValues = "AppData.AlphaValues", Multiple = true)]
    public List<string>? MultipleServerValues { get; set; }

    [Input(Type="combobox", EvalAllowableEntries = "{ A:'Alpha', B:'Bravo', C:'Charlie' }")]
    public string? SingleServerEntries { get; set; }

    [Input(Type="combobox", EvalAllowableEntries = "AppData.AlphaDictionary", Multiple = true)]
    public List<string>? MultipleServerEntries { get; set; }
}
```

Which can then be rendered with:

```html
<AutoForm type="ComboBoxExamples" />
```
<auto-form type="ComboBoxExamples" class="not-prose mb-4"></auto-form>

**Combobox Options**

Each property shows a different way of populating the Combobox's optional values, they can be populated from a JavaScript
Object literal using `Options` or on the server with a [#Script Expression](https://sharpscript.net) where they can be 
populated from a static list or from a C# class as seen in the examples referencing `AppData` properties:

```csharp
public class AppData
{
    public List<string> AlphaValues { get; set; }
    public Dictionary<string, string> AlphaDictionary { get; set; }
    public List<KeyValuePair<string, string>> AlphaKeyValuePairs { get; set; }
}
```

Which are populated on in the AppHost on Startup with:

```csharp
ScriptContext.Args[nameof(AppData)] = new AppData
{
    AlphaValues = new() {
        "Alpha", "Bravo", "Charlie"
    },
    AlphaDictionary = new()
    {
        ["A"] = "Alpha",
        ["B"] = "Bravo",
        ["C"] = "Charlie",
    },
    AlphaKeyValuePairs = new()
    {
        new("A","Alpha"),
        new("B","Bravo"),
        new("C","Charlie"),
    },
};
```

Which can alternatively be populated from a dynamic source like an RDBMS table.

As C# Dictionaries have an undetermined sort order, you can use a `List<KeyValuePair<string, string>>` instead when you need to
display an ordered list of Key/Value pairs.


# Autocomplete Component
Source: https://docs.servicestack.net/vue/autocomplete

The `Autocomplete` component provides a user friendly Input for being able to search and quickly select items
with support for partial items view and infinite scrolling.

```html
<form class="col-span-12">
    <div class="mb-3">
        <Autocomplete id="simple" :options="allContacts" v-model="simple" label="Single Contact"
            :match="(x: any, value: string) => x!.displayName.toLowerCase().includes(value.toLowerCase())"
            placeholder="Select Contact">
            <template #item="{ displayName }">
                <span class="block truncate">{{ displayName }}</span>
            </template>
        </Autocomplete>
        <div class="mt-2 flex justify-end">
            <p>
                <b class="text-gray-500">Single:</b>
                <div v-if="simple" class="flex">
                    <img :src="simple.profileUrl" class="w-8 h-8 rounded-full mr-2">
                    <b class="text-lg">{{ simple.displayName }}</b>
                </div>
            </p>
        </div>
    </div>

    <div class="mb-3">
        <Autocomplete id="contact" :options="allContacts" v-model="contact" label="Single Contact with Icon"
            :match="(x: any, value: string) => x!.displayName.toLowerCase().includes(value.toLowerCase())"
            placeholder="Select Contact">
            <template #item="{ displayName, profileUrl }">
                <div class="flex items-center">
                    <Icon class="h-6 w-6 flex-shrink-0 rounded-full" :src="profileUrl" loading="lazy" />
                    <span class="ml-3 truncate">{{ displayName }}</span>
                </div>
            </template>
        </Autocomplete>
        <div class="mt-2 flex justify-end">
            <p>
                <b class="text-gray-500">Single with Icon:</b>
                <div v-if="contact" class="flex">
                    <img :src="contact.profileUrl" class="w-8 h-8 rounded-full mr-2">
                    <b class="text-lg">{{ contact.displayName }}</b>
                </div>
            </p>
        </div>
    </div>

    <div class="mb-3">
        <Autocomplete id="contacts" :options="allContacts" v-model="contacts" multiple
            label="Multiple Contacts with Icon"
            :match="(x: any, value: string) => x!.displayName.toLowerCase().includes(value.toLowerCase())"
            placeholder="Select Contact">
            <template #item="{ displayName, profileUrl }">
                <div class="flex items-center">
                    <Icon class="h-6 w-6 flex-shrink-0 rounded-full" :src="profileUrl" loading="lazy" />
                    <span class="ml-3 truncate">{{ displayName }}</span>
                </div>
            </template>
        </Autocomplete>
        <div class="mt-2">
            <div class="text-right"><b class="text-gray-500">Multiple with Icon:</b></div>
            <p>
            <div v-if="contacts.length" class="flex flex-wrap">
                <div v-for="contact in contacts" class="flex ml-4 mb-2">
                    <img :src="contact.profileUrl" class="w-6 h-6 rounded-full mr-2">
                    <span>{{ contact.displayName }}</span>
                </div>
            </div>
            </p>
        </div>
    </div>
</form>
```

## Custom Form

<div class="not-prose">
<autocomplete-examples class="max-w-prose"></autocomplete-examples>
</div>


# Markdown Input Component
Source: https://docs.servicestack.net/vue/markdown

## Markdown Editor Input

The `<MarkdownInput>` component is a developer-friendly Markdown Editor that provides a rich Markdown Textarea Input to capture 
rich formatted text in Markdown with icons for markdown's popular formatting options and convenience keyboard bindings for a pleasant 
intuitive authoring experience. 

It's optimized [GitHub Flavored Markdown](https://guides.github.com/features/mastering-markdown/) where it supports popular short-cuts for 
editing and documenting code like tab block un/indenting, single-line and code and comments blocks.

It behaves like all other Input components which you can embed in custom UIs as a standard Vue Component:

```ts
<MarkdownInput id="body" v-model="request.body" />
```

#### MarkdownInput Properties

It offers a number of properties to customize its appearance and behavior:

```ts
defineProps<{
    status?: ResponseStatus|null
    id: string
    inputClass?: string
    label?: string
    labelClass?: string
    help?: string
    placeholder?: string
    modelValue?: string

    counter?: boolean
    rows?: number
    errorMessages?: string[]
    lang?: string
    autoFocus?: boolean
    disabled?: boolean
    helpUrl?: string
    hide?: string|MarkdownInputOptions|MarkdownInputOptions[]
}>()

type MarkdownInputOptions = "bold" | "italics" | "link" | "image" | "blockquote" | "code" 
  | "heading" | "orderedList" | "unorderedList" | "strikethrough" | "undo" | "redo" | "help"
```

Just like other Input components it can be annotated on Request DTO string properties to change which Input component it should use in 
[AutoForm components](/vue/autoform), where it can be further customized with tailwind classes on its
containing Field and Textarea Input elements, e.g:

```csharp
public class MarkdownEmail
{
    [Input(Type="MarkdownInput", Label=""), FieldCss(Field="col-span-12", Input="h-56")]
    public string? Body { get; set; }
}
```

Where it's used to generate all of [CreatorKit's Markdown Email Forms](https://servicestack.net/creatorkit/portal-messages), e.g:

<figure class="mt-4">
    <a class="my-8 max-w-4xl mx-auto block" href="https://servicestack.net/creatorkit/portal-messages#sending-html-markdown-emails">
        <img class="rounded shadow hover:shadow-lg" src="/img/pages/vue/markdown-email-form.png" alt=""></a>
</figure>

## Keyboard Shortcuts

For added productivity the Editor supports many of the popular Keyboard shortcuts in found in common IDEs:

![](/img/pages/vue/markdown-shortcuts.png)


# Custom Input Components
Source: https://docs.servicestack.net/vue/custom-inputs

## Custom Declarative Input Components

In addition to all the [Input Components](/vue/form-inputs) in the Vue Component Library, AutoForm components bound to your declarative Request DTOs 
can also reference your own Vue Input components.

This allows us to continue to benefiting rapid development workflow enabled by the [AutoForm components](/vue/autoform) whilst also being able
to deliver the most optimal UX when we need to. 

CreatorKit's [Email Templates](https://servicestack.net/creatorkit/portal-messages) are a good example of this, which instead of utilizing the standard
[LookupInput](/vue/autoform#edit-form) (inferred from [Reference Fields](/vue/autoquerygrid#reference-fields))
to open a modal to select a contact from a Contacts DataGrid it uses a custom `EmailInput` Component to provide an optimal, user-friendly UX that
we've come to expect from popular Email clients like gmail to provide a non-modal autocomplete dropdown that automatically searches our contact list 
as we type.

### Registering Custom Components

To make use of a custom Input component we need to register it with the Vue Component Library in [app.mjs](https://github.com/NetCoreApps/CreatorKit/blob/main/CreatorKit/wwwroot/mjs/app.mjs), e.g:

```ts
import ServiceStackVue, { useAuth } from "@servicestack/vue"
//...

ServiceStackVue.component('EmailInput', EmailInput)
ServiceStackVue.component('MarkdownEmailInput', MarkdownEmailInput)
```

### EmailInput

This registers the custom `EmailInput` and `MarkdownEmailInput` components defined in [Inputs.mjs](https://github.com/NetCoreApps/CreatorKit/blob/main/CreatorKit/wwwroot/mjs/components/Inputs.mjs)

Where we can see that `<EmailInput>` is a customized `<TextInput>` with an added `SelectEmail` component that's used to display the Autocomplete
email dropdown:

```ts
export const EmailInput = {
    components: { SelectEmail },
    template: `<TextInput v-bind="$attrs" @update:modelValue="$emit('update:modelValue',$event)">
      <template #footer="{ id, inputElement, modelValue }">
        <SelectEmail v-if="inputElement" :inputElement="inputElement" :modelValue="modelValue" />
      </template>
    </TextInput>`,
    emits:['update:modelValue'],
}
```

### MarkdownEmailInput 

Whilst `<MarkdownEmailInput>` is a customized `<MarkdownInput>` that's been extended with an additional 
[Insert Template Variables button](https://servicestack.net/creatorkit/portal-messages#template-variables) that enables quick access for users to discover and insert user-defined [Template Variables](https://servicestack.net/creatorkit/customize#template-variables):

```ts
export const MarkdownEmailInput = {
    components: { InsertVariableButton },
    template: `<MarkdownInput v-bind="$attrs" @update:modelValue="$emit('update:modelValue',$event)">
      <template #toolbarbuttons="{ instance, textarea }">
        <InsertVariableButton :instance="instance" :textarea="textarea" />
      </template>
    </MarkdownInput>`,
    emits:['update:modelValue'],
}
```

Once registered they can be declaratively used like any other Input Component using the `[Input(Type)]` attribute:

```csharp
[Description("Markdown Email")]
public class MarkdownEmail : CreateEmailBase, IPost, IReturn<MailMessage>
{
    [ValidateNotEmpty]
    [FieldCss(Field = "col-span-12")]
    public string Subject { get; set; }

    [ValidateNotEmpty]
    [Input(Type="MarkdownEmailInput", Label=""), FieldCss(Field="col-span-12", Input="h-56")]
    public string? Body { get; set; }
    
    public bool? Draft { get; set; }
}

public abstract class CreateEmailBase
{
    [ValidateNotEmpty]
    [Input(Type="EmailInput")]
    public string Email { get; set; }

    [ValidateNotEmpty]
    [FieldCss(Field = "col-span-6 lg:col-span-3")]
    public string FirstName { get; set; }
    
    [ValidateNotEmpty]
    [FieldCss(Field = "col-span-6 lg:col-span-3")]
    public string LastName { get; set; }
}
```

Where they're effortlessly used together to deliver a great, optimal UX in all of CreatorKit's Markdown Email Forms:

<figure class="mt-4">
    <a class="my-8 max-w-4xl mx-auto block" href="https://servicestack.net/creatorkit/portal-messages#sending-html-markdown-emails">
        <img class="rounded shadow hover:shadow-lg" src="/img/pages/release-notes/v6.9/markdown-email-custom-inputs.png" alt=""></a>
</figure>

### Extending Auto Forms

The Email Forms also includes a **Live Preview** component so you can view a HTML Preview of what the Email looks like as-you-type which was 
created using a customized `<AutoCreateForm>` component that's enhanced to include an `<EmailPreview>` component by using a custom
`<template #footer>`:

```html
<AutoCreateForm v-if="selectedOp" :type="selectedOp?.name" @save="save" @done="done">
    <template #footer="{ model }">
        <EmailPreview :type="selectedOp?.name" :modelValue="model" />
    </template>
</AutoCreateForm>
```

### AutoForm Components Everywhere

These features have given AutoForm components all the flexibility needed to be able to deliver a great, optimal experience without sacrificing the high-productivity of ServiceStack's validation-bound Auto UIs and API Form components, as a result CreatorKit was able to continue to
use AutoForm components for all 17 of its API Forms.


# Modal Components
Source: https://docs.servicestack.net/vue/modals

<api-reference component="ModalDialog"></api-reference>
## ModalDialog

Use `<ModalDialog>` component to show any content inside a Modal Dialog:

```html
<SecondaryButton @click="showDialog=true">Show Modal</SecondaryButton>
<ModalDialog v-if="showDialog" @done="showDialog=false">
  <h3 class="p-8 text-3xl">Hello @servicestack/vue!</h3>
</ModalDialog>
```

<div class="not-prose">
    <secondary-button @click="showDialog=true">Show Modal</secondary-button>
    <modal-dialog v-if="showDialog" @done="showDialog=false"><h3 class="p-8 text-3xl">Hello @servicestack/vue!</h3></modal-dialog>
</div>

<api-reference component="SlideOver"></api-reference>
## SlideOver

Use `<SlideOver>` to show contents inside an animated slide over:

```html
<SecondaryButton @click="showSlide=true" class="mt-4">Show Slide</SecondaryButton>
<SlideOver v-if="showSlide" title="The Title" @done="showSlide=false" content-class="relative flex-1">
  <template #subtitle>
    a <b>subtitle</b>
  </template>
  <Alert type="error">Authentication Required</Alert>
  <div class="md:p-4">
    <SecondaryButton>Sign In</SecondaryButton>
  </div>
</SlideOver>
```

<div class="not-prose">
    <secondary-button @click="showSlide=true" class="mt-4">Show Slide</secondary-button>
    <slide-over v-if="showSlide" title="The Title" @done="showSlide=false" content-class="relative flex-1">
        <template #subtitle>
            a <b>subtitle</b>
        </template>
        <alert type="error">Authentication Required</alert>
        <div class="md:p-4">
            <secondary-button>Sign In</secondary-button>
        </div>
    </slide-over>
</div>


As seen in this example we can use **content-class** to customize the inner body contents and the `<template #subtitle>` slot
to include an optional rich HTML subtitle, with all other inner contents is displayed in the SlideOver's body.

<api-reference component="SignIn"></api-reference>
## SignIn

The `<SignIn>` Component can be used to create an instant Sign Up form based on the [registered Auth Providers](/auth/) that handles
Signing In authenticated users into Vue Apps with the [useAuth()](/vue/use-auth) APIs:


```html
<SignIn v-if="!user" />
<h3 v-else class="text-2xl my-4">Hello, {{ user.displayName }}</h3>

<script setup>
import { useAuth } from "@servicestack/vue"
const { user } = useAuth()
</script>
```

<div class="not-prose">
    <sign-in v-if="!user" :tabs="false"></sign-in>
    <h3 v-else class="text-2xl my-4">Hello, {{ user.displayName }}</h3>
</div>

**SignIn Properties**

```ts
defineProps<{
    provider?: string  // which Auth Provider to default to
    title?: string     //= Sign In - Heading
    tabs?: boolean     //= true - Show different Auth Provider tabs
    oauth?: boolean    //= true - Show OAuth Provider buttons
}>()
```

**Events**

Use `@login` to run custom logic after successful authentication:

```ts
defineEmits<{
    (e:'login', auth:AuthenticateResponse): void
}>()
```


# Navigation Components
Source: https://docs.servicestack.net/vue/navigation

<api-reference component="Tabs"></api-reference>
## Tabs

The `<Tabs>` component lets you switch between different Vue components from a object component dictionary where the **Key** is used for the Tab's label and URL param and the **Value** component for the tab body. 

```html
<script setup>
import A from "./A.vue"
import B from "./B.vue"
import C from "./C.vue"
const tabs = { A, B, C }
</script>
```

The Tab's Label can alternatively be overridden with a custom **label** function, e.g:

```html
<Tabs :tabs="tabs" :label="tab => `${tab} Tab Label`" />
```
<tabs :tabs="tabs" :label="tab => `${tab} Tab Label`" class="not-prose mb-8"></tabs>

**Tabs properties**

```ts
defineProps<{
    tabs: {[name:string]:Component }
    id?: string                      //= tabs
    param?: string                   //= tab - URL param to use
    label?: (tab:string) => string   // - Custom function to resolve Tab Label
    selected?: string                // - The selected tab
    tabClass?: string                // - Additional classes for Tab Label
    bodyClass?: string               // - Classes for Tab Body
    url?:boolean                     //= true - Whether to maintain active tab in history.pushState()
}>()
```

<api-reference component="Breadcrumbs"></api-reference>
## Breadcrumbs

Breadcrumb example:

```html
<Breadcrumbs home-href="/vue/">
  <Breadcrumb href="/vue/gallery">gallery</Breadcrumb>
  <Breadcrumb>Navigation Examples</Breadcrumb>
</Breadcrumbs>
```

<Breadcrumbs class="not-prose my-8" home-href="/vue/">
  <Breadcrumb href="/vue#gallery">gallery</Breadcrumb>
  <Breadcrumb>Navigation Examples</Breadcrumb>
</Breadcrumbs>

<api-reference component="NavList"></api-reference>
## NavList

Use `NavList` for rendering a vertical navigation list with Icons:

```html
<NavList title="Explore Vue Tailwind Components">
    <NavListItem title="DataGrid" href="/vue/gallery/datagrid" :iconSvg="Icons.DataGrid">
        DataGrid Component Examples for rendering tabular data
    </NavListItem>
    <NavListItem title="AutoQuery Grid" href="/vue/gallery/autoquerygrid" :iconSvg="Icons.AutoQueryGrid">
        Instant customizable UIs for calling AutoQuery CRUD APIs
    </NavListItem>
</NavList>
```

<div class="my-8 not-prose">
    <nav-list-examples class="max-w-3xl mx-auto"></nav-list-examples>
</div>

<api-reference component="PrimaryButton"></api-reference>
## Link Buttons

Using `href` with Button components will style hyper links to behave like buttons:

```html
<PrimaryButton href="https://blazor-vue.web-templates.io/" class="mr-2">
    Blazor Vue Template
</PrimaryButton>

<SecondaryButton href="/vue/">
    Vue Component Docs
</SecondaryButton>
```

<div class="my-8 not-prose">
    <primary-button href="https://blazor-vue.web-templates.io/" class="mr-2">Blazor Vue Template</primary-button>
    <secondary-button href="/vue/">Vue Component Docs</secondary-button>
</div>

<api-reference component="PrimaryButton"></api-reference>
## PrimaryButton

That can use **color** to render it in different colors:

```html
<PrimaryButton>Default</PrimaryButton>
<PrimaryButton color="blue">Blue</PrimaryButton>
<PrimaryButton color="purple">Purple</PrimaryButton>
<PrimaryButton color="red">Red</PrimaryButton>
<PrimaryButton color="green">Green</PrimaryButton>
<PrimaryButton color="sky">Sky</PrimaryButton>
<PrimaryButton color="cyan">Cyan</PrimaryButton>
<PrimaryButton color="indigo">Indigo</PrimaryButton>
```

<div class="my-8 not-prose space-x-2">
    <primary-button>Default</primary-button>
    <primary-button color="blue">Blue</primary-button>
    <primary-button color="purple">Purple</primary-button>
    <primary-button color="red">Red</primary-button>
    <primary-button color="green">Green</primary-button>
    <primary-button color="sky">Sky</primary-button>
    <primary-button color="cyan">Cyan</primary-button>
    <primary-button color="indigo">Indigo</primary-button>
</div>

<api-reference component="TextLink"></api-reference>
## TextLink

Tailwind `<a>` hyper links, e.g:

```html
<TextLink href="/vue/" class="text-xl">
    docs.servicestack.net/vue
</TextLink>
```

<div class="not-prose">
<text-link href="/vue/" class="text-xl">docs.servicestack.net/vue</text-link>
</div>

That can also use **color** to render it in different colors:

```html
<TextLink @click="say('Hi!')" title="Greetings">Default <b>Link</b></TextLink>
<TextLink color="purple" href="https://google.com" target="_blank" title="Google Link">Purple <b>Link</b></TextLink>
<TextLink color="red"    href="https://google.com" target="_blank" title="Google Link">Red <b>Link</b></TextLink>
<TextLink color="green"  href="https://google.com" target="_blank" title="Google Link">Green <b>Link</b></TextLink>
<TextLink color="sky"    href="https://google.com" target="_blank" title="Google Link">Sky <b>Link</b></TextLink>
<TextLink color="cyan"   href="https://google.com" target="_blank" title="Google Link">Cyan <b>Link</b></TextLink>
<TextLink color="indigo" href="https://google.com" target="_blank" title="Google Link">Indigo <b>Link</b></TextLink>
```

<div class="not-prose flex space-x-4">
  <text-link @click="say('Hi!')" title="Greetings">Default <b>Link</b></text-link>
  <text-link color="purple" href="https://google.com" target="_blank" title="Google Link">Purple <b>Link</b></text-link>
  <text-link color="red"    href="https://google.com" target="_blank" title="Google Link">Red <b>Link</b></text-link>
  <text-link color="green"  href="https://google.com" target="_blank" title="Google Link">Green <b>Link</b></text-link>
  <text-link color="sky"    href="https://google.com" target="_blank" title="Google Link">Sky <b>Link</b></text-link>
  <text-link color="cyan"   href="https://google.com" target="_blank" title="Google Link">Cyan <b>Link</b></text-link>
  <text-link color="indigo" href="https://google.com" target="_blank" title="Google Link">Indigo <b>Link</b></text-link>
</div>


# Alert Components
Source: https://docs.servicestack.net/vue/alerts

<api-reference component="Alert"></api-reference>
## Alert

<p class="mb-4 text-lg">
    Show basic alert message:
</p>

```html
<Alert>Default <b>Message</b></Alert>
<Alert type="info">Information <b>Message</b></Alert>
<Alert type="success">Success <b>Message</b></Alert>
<Alert type="warn">Warning <b>Message</b></Alert>
<Alert type="error">Error <b>Message</b></Alert>
```

<div class="not-prose mb-4">
<alert>Default <b>Message</b></alert>
<alert type="info">Information <b>Message</b></alert>
<alert type="success">Success <b>Message</b></alert>
<alert type="warn">Warning <b>Message</b></alert>
<alert type="error">Error <b>Message</b></alert>
</div>

Show alert message from dynamic HTML string:

```html
<Alert v-html="message" />

<script>
const message = "Requires <b>Employee</b> Role"
</script>
```

<div class="not-prose">
<alert v-html="message"></alert>
</div>

<api-reference component="AlertSuccess"></api-reference>
## Alert Success

Show success alert message:

```html
<AlertSuccess>Order was received</AlertSuccess>
```

<div class="not-prose">
<alert-success class="not-prose">Order was received</alert-success>
</div>

<api-reference component="ErrorSummary"></api-reference>
## Error Summary

Show failed Summary API Error Message:

```html
<ErrorSummary :status="{ message:'Requires Employee Role' }" />
```

<div class="not-prose">
<error-summary :status="{ message:'Requires Employee Role' }" class="not-prose"></error-summary>
</div>


# Format Examples
Source: https://docs.servicestack.net/vue/formats

<api-reference component="PreviewFormat"></api-reference>
## PreviewFormat

Useful for rendering Table Cell data into different customizable formats, e.g:

### Currency

```html
<PreviewFormat :value="50" :format="Formats.currency" />
```
<div class="not-prose">
<preview-format :value="50" :format="Formats.currency"></preview-format>
</div>

### Bytes

```html
<PreviewFormat :value="10000000" :format="Formats.bytes" />
```
<div class="not-prose">
<preview-format :value="10000000" :format="Formats.bytes"></preview-format>
</div>

### Icon

```html
<PreviewFormat value="/pages/vue/1.jpg" :format="Formats.icon" />
```
<div class="not-prose">
<preview-format value="/pages/vue/1.jpg" :format="Formats.icon"></preview-format>
</div>

### Icon Rounded

```html
<PreviewFormat value="/pages/vue/1.jpg" :format="Formats.iconRounded" />
```
<div class="not-prose">
<preview-format value="/pages/vue/1.jpg" :format="Formats.iconRounded"></preview-format>
</div>

### Icon with custom class

```html
<PreviewFormat value="/pages/vue/1.jpg" :format="Formats.icon" class="w-40 h-40 rounded-full" />
```
<div class="not-prose">
<preview-format value="/pages/vue/1.jpg" :format="Formats.icon" class="not-prose w-40 h-40 rounded-full"></preview-format>
</div>

### Attachment (Image)

```html
<PreviewFormat value="/pages/vue/1.jpg" :format="Formats.attachment" />
```
<div class="not-prose">
<preview-format value="/pages/vue/1.jpg" :format="Formats.attachment"></preview-format>
</div>

### Attachment (Document)

```html
<PreviewFormat value="/content/hosting.md" :format="Formats.attachment" />
```
<div class="not-prose">
<preview-format value="/content/hosting.md" :format="Formats.attachment"></preview-format>
</div>

### Attachment (Document) with classes

```html
<PreviewFormat value="/content/hosting.md" :format="Formats.attachment" 
    class="text-xl text-indigo-700 font-semibold" icon-class="w-8 h-8" />
```
<div class="not-prose">
<preview-format value="/content/hosting.md" :format="Formats.attachment" class="text-xl text-indigo-700 font-semibold" icon-class="w-8 h-8"></preview-format>
</div>

### Link

```html
<PreviewFormat value="https://servicestack.net/blazor" :format="Formats.link" />
```
<div class="not-prose">
<preview-format value="https://servicestack.net/blazor" :format="Formats.link"></preview-format>
</div>

### Link with class

```html
<PreviewFormat value="https://servicestack.net/blazor" :format="Formats.link" class="text-xl" />
```
<div class="not-prose">
<preview-format value="https://servicestack.net/blazor" :format="Formats.link" class="text-xl text-blue-600"></preview-format>
</div>

### Link Email

```html
<PreviewFormat value="user@email.com" :format="Formats.linkMailTo" />
```
<div class="not-prose">
<preview-format value="user@email.com" :format="Formats.linkMailTo"></preview-format>
</div>

### Link Phone

```html
<PreviewFormat value="555 123 4567" :format="Formats.linkTel" />
```
<div class="not-prose">
<preview-format value="555 123 4567" :format="Formats.linkTel"></preview-format>
</div>

## Using Formatters

Your App and custom templates can also utilize @servicestack/vue's [built-in formatting functions](/vue/use-formatters) from:

```js
import { useFormatters } from '@servicestack/vue'

const {
    Formats,             // Available format methods to use in <PreviewFormat />
    formatValue,         // Format any value or object graph
    currency,            // Format number as Currency
    bytes,               // Format number in human readable disk size
    link,                // Format URL as <a> link
    linkTel,             // Format Phone Number as <a> tel: link
    linkMailTo,          // Format email as <a> mailto: link
    icon,                // Format Image URL as an Icon
    iconRounded,         // Format Image URL as a full rounded Icon
    attachment,          // Format File attachment URL as an Attachment
    hidden,              // Format as empty string
    time,                // Format duration in time format
    relativeTime,        // Format Date as Relative Time from now
    relativeTimeFromMs,  // Format time in ms as Relative Time from now
    formatDate,          // Format as Date
    formatNumber,        // Format as Number
} = useFormatters()
```

Many of these formatting functions return rich HTML markup which will need to be rendered using Vue's **v-html** directive:

```html
<span v-html="formatValue(value)"></span>
```

<api-reference component="HtmlFormat"></api-reference>
## HtmlFormat

`HtmlFormat` can be used to render any Serializable object into a human-friendly HTML Format:

### Single Model

```html
<HtmlFormat :value="tracks[0]" />
```
<div class="not-prose max-w-screen-sm">
    <html-format :value="tracks[0]"></html-format>
</div>

### Item Collections

```html
<HtmlFormat :value="tracks" />
```
<div class="not-prose max-w-screen-sm">
    <html-format :value="tracks"></html-format>
</div>

### Nested Complex Types

```html
<HtmlFormat :value="players" />
```
<div class="not-prose prose-table">
<html-format :value="players"></html-format>
</div>

### Nested Complex Types with custom classes

When needed most default classes can be overridden with a custom **classes** function that can inspect the
type, tag, depth, and row index to return a custom class. The TypeScript function shows an example of checking
these different parameters to render a custom HTML resultset:

```html
<HtmlFormat :value="players" :classes="classes" />

<script lang="ts">
function classes(type:'array'|'object', tag:'div'|'table'|'thead'|'th'|'tr'|'td',depth:number,cls:string,index?:number)
{
    if (type === 'array') {
        if (tag === 'th') return cls.replace('text-sm text-gray-500 font-medium',' ') + (depth === 0 
            ? 'text-xs uppercase font-semibold text-indigo-700'
            : 'text-xs font-medium text-gray-500')
        if (tag === 'tr') return depth > 0 || index! % 2 == 0 ? 'bg-white' : 'bg-yellow-50'
        if (tag === 'td' && depth > 0) return 'px-4 py-3 whitespace-nowrap text-xs'
    }
    return cls
}
</script>
```
<div class="not-prose prose-table">
<html-format :value="players" :classes="classes"></html-format>
</div>


# App Metadata
Source: https://docs.servicestack.net/vue/use-metadata

The rich server metadata about your APIs that's used to generate your App's DTOs in 
[Multiple Programming Languages](/add-servicestack-reference), power ServiceStack's 
[built-in Auto UIs](/locode/declarative) also power the Metadata driven components in the **@servicestack/vue** component library 
where it can be loaded in your `_Layout.cshtml` using an optimal configuration like:

```html
var dev = HostContext.AppHost.IsDevelopmentEnvironment();
@if (dev) {
    <script>window.Server = @await Html.ApiAsJsonAsync(new MetadataApp())</script>
}

<script type="module">
import { useMetadata } from "@@servicestack/vue"

const { loadMetadata } = useMetadata()
loadMetadata({
    olderThan: window.Server ? null : location.search.includes('clear=metadata') ? 0 : 60 * 60 * 1000 //1hr 
})
</script>
```

Where during development it always embeds the AppMetadata in each page but as this metadata can become quite large for systems with a lot of APIs, the above optimization clears and reloads the AppMetadata after **1 hr** or if the page was explicitly loaded with `?clear=metadata`, 
otherwise it will use a local copy cached in `localStorage` at `/metadata/app.json`, which Apps needing more 
fine-grained cache invalidation strategies can manage themselves.

Once loaded the AppMetadata features can be access with the helper functions in [useMetadata](/vue/use-metadata).

```js
import { useMetadata } from "@servicestack/vue"

const { 
    loadMetadata,      // Load {AppMetadata} if needed 
    setMetadata,       // Explicitly set AppMetadata and save to localStorage
    clearMetadata,     // Delete AppMetadata and remove from localStorage
    metadataApi,       // Reactive accessor to Ref<MetadataTypes>
    typeOf,            // Resolve {MetadataType} for DTO name
    typeOfRef,         // Resolve {MetadataType} by {MetadataTypeName}
    apiOf,             // Resolve Request DTO {MetadataOperationType} by name
    property,          // Resolve {MetadataPropertyType} by Type and Property name
    enumOptions,       // Resolve Enum entries for Enum Type by name
    propertyOptions,   // Resolve allowable entries for property by {MetadataPropertyType}
    createFormLayout,  // Create Form Layout's {InputInfo[]} from {MetadataType}
    typeProperties,    // Return all properties (inc. inherited) for {MetadataType}
    supportsProp,      // Check if a supported HTML Input exists for {MetadataPropertyType}
    Crud,              // Query metadata information about AutoQuery CRUD Types
    getPrimaryKey,     // Resolve PrimaryKey {MetadataPropertyType} for {MetadataType}
    getId,             // Resolve Primary Key value from {MetadataType} and row instance
    createDto,         // Create a Request DTO instance for Request DTO name
    toFormValues,      // Convert Request DTO values to supported HTML Input values
    formValues,        // Convert HTML Input values to supported DTO values
} = useMetadata()
```

For example you can use this to view all C# property names and Type info for the `Contact` C# DTO with:

```html
<HtmlFormat :value="typeOf('Contact').properties.map(({ name, type, namespace }) => ({ name, type, namespace }))" />
```
<div class="not-prose">
<html-format :value="typeOf('Contact').properties.map(({ name, type, namespace }) => ({ name, type, namespace }))"></html-format>
</div>

## Enum Values and Property Options

More usefully this can avoid code maintenance and duplication efforts from maintaining enum values on both server and client forms. 

An example of this is in the [Contacts.mjs](https://github.com/NetCoreTemplates/razor/blob/net6/MyApp/wwwroot/Pages/Contacts.mjs) 
component which uses the server metadata to populate the **Title** and **Favorite Genre** select options from the `Title` and `FilmGenre` enums:

```html
<div class="grid grid-cols-6 gap-6">
  <div class="col-span-6 sm:col-span-3">
    <SelectInput id="title" v-model="request.title" :options="enumOptions('Title')" />
  </div>
  <div class="col-span-6 sm:col-span-3">
    <TextInput id="name" v-model="request.name" required placeholder="Contact Name" />
  </div>
  <div class="col-span-6 sm:col-span-3">
    <SelectInput id="color" v-model="request.color" :options="colorOptions" />
  </div>
  <div class="col-span-6 sm:col-span-3">
    <SelectInput id="favoriteGenre" v-model="request.favoriteGenre" :options="enumOptions('FilmGenre')" />
  </div>
  <div class="col-span-6 sm:col-span-3">
    <TextInput type="number" id="age" v-model="request.age" />
  </div>
</div>
```

Whilst the `colorOptions` gets its values from the available options on the `CreateContact.Color` property:    

```js
const Edit = {
    //...
    setup(props) {
        const { property, propertyOptions, enumOptions } = useMetadata()
        const colorOptions = propertyOptions(property('CreateContact','Color'))
        return { enumOptions, colorOptions }
        //..
    }
}
```

Which instead of an enum, references the C# Dictionary in:

```csharp
public class CreateContact : IPost, IReturn<CreateContactResponse>
{
    [Input(Type="select", EvalAllowableEntries = "AppData.Colors")]
    public string? Color { get; set; }
    //...
}
```

To return a C# Dictionary of custom colors defined in:

```csharp
public class ConfigureUi : IHostingStartup
{
    public void Configure(IWebHostBuilder builder) => builder
        .ConfigureAppHost(appHost => {
            //Enable referencing AppData.* in #Script expressions
            appHost.ScriptContext.Args[nameof(AppData)] = AppData.Instance;
        });
}

public class AppData
{
    public static readonly AppData Instance = new();
    public Dictionary<string, string> Colors { get; } = new() {
        ["#F0FDF4"] = "Green",
        ["#EFF6FF"] = "Blue",
        ["#FEF2F2"] = "Red",
        ["#ECFEFF"] = "Cyan",
        ["#FDF4FF"] = "Fuchsia",
    };
}
```

## AutoForm Components

See [Auto Form Components](/vue/autoform) docs for examples of easy to use, high productivity `AppMetadata` powered components.

## TypeScript Definition

TypeScript definition of the API surface area and type information for correct usage of `useMetadata()`

```ts
import type { 
    AppMetadata, MetadataType, MetadataPropertyType, MetadataOperationType, InputInfo, KeyValuePair 
} from "./types"


/** Load {AppMetadata} if needed 
 * @param olderThan   - Reload metadata if age exceeds ms
 * @param resolvePath - Override `/metadata/app.json` path use to fetch metadata
 * @param resolve     - Use a custom fetch to resolve AppMetadata
*/
function loadMetadata(args: {
    olderThan?: number;
    resolvePath?: string;
    resolve?: () => Promise<Response>;
}): Promise<AppMetadata>;

/** Check if AppMetadata is valid */
function isValid(metadata: AppMetadata | null | undefined): boolean | undefined;

/** Delete AppMetadata and remove from localStorage */
function setMetadata(metadata: AppMetadata | null | undefined): boolean;

/** Delete AppMetadata and remove from localStorage */
function clearMetadata(): void;


/** Query metadata information about AutoQuery CRUD Types */
const Crud: {
    Create: string;
    Update: string;
    Patch: string;
    Delete: string;
    AnyRead: string[];
    AnyWrite: string[];
    isQuery: (op: MetadataOperationType) => any;
    isCrud: (op: MetadataOperationType) => boolean | undefined;
    isCreate: (op: MetadataOperationType) => boolean | undefined;
    isUpdate: (op: MetadataOperationType) => boolean | undefined;
    isPatch: (op: MetadataOperationType) => boolean | undefined;
    isDelete: (op: MetadataOperationType) => boolean | undefined;
    model: (type?: MetadataType | null) => string | null | undefined;
};

/** Resolve HTML Input type to use for {MetadataPropertyType}  */
function propInputType(prop: MetadataPropertyType): string;

/** Resolve HTML Input type to use for C# Type name */
function inputType(type: string): string;

/** Check if C# Type name is numeric */
function isNumericType(type?: string | null): boolean;

/** Check if C# Type is an Array or List */
function isArrayType(type: string): boolean;

/** Check if a supported HTML Input exists for {MetadataPropertyType} */
function supportsProp(prop?: MetadataPropertyType): boolean;

/** Create a Request DTO instance for Request DTO name */
function createDto(name: string, obj?: any): any;

/** Convert Request DTO values to supported HTML Input values */
function toFormValues(dto: any, metaType?: MetadataType | null): any;

/** Convert HTML Input values to supported DTO values */
function formValues(form: HTMLFormElement, props?: MetadataPropertyType[]): {
    [k: string]: any;
};

/**
 * Resolve {MetadataType} for DTO name
 * @param name        - Find MetadataType by name
 * @param [namespace] - Find MetadataType by name and namespace 
 */
function typeOf(name?: string | null, namespace?: string | null): MetadataType | null;

/** Resolve Request DTO {MetadataOperationType} by name */
function apiOf(name: string): MetadataOperationType | null;

/** Resolve {MetadataType} by {MetadataTypeName} */
function typeOfRef(ref?: {
    name: string;
    namespace?: string;
}): MetadataType | null;

function property(typeName: string, name: string): MetadataPropertyType | null;

/** Resolve Enum entries for Enum Type by name */
function enumOptions(name: string): { [name: string]: string; } | null;

function enumOptionsByType(type?: MetadataType | null): { [name: string]: string; } | null;

/** Resolve Enum entries for Enum Type by MetadataType */
function propertyOptions(prop: MetadataPropertyType): { [name: string]: string; } | null;

/** Convert string dictionary to [{ key:string, value:string }] */
function asKvps(options?: { [k: string]: string; } | null): KeyValuePair<string, string>[] | undefined;

/** Create InputInfo from MetadataPropertyType and custom InputInfo */
function createInput(prop: MetadataPropertyType, input?: InputInfo): InputInfo;

/** Create Form Layout's {InputInfo[]} from {MetadataType} */
function createFormLayout(metaType?: MetadataType | null): InputInfo[];

/** Return all properties (inc. inherited) for {MetadataType} */
function typeProperties(type?: MetadataType | null): MetadataPropertyType[];

/** Check if MetadataOperationType implements interface by name */
function hasInterface(op: MetadataOperationType, cls: string): boolean;

/** Resolve PrimaryKey {MetadataPropertyType} for {MetadataType} */
function getPrimaryKey(type?: MetadataType | null): MetadataPropertyType | null;

/** Resolve Primary Key value from {MetadataType} and row instance  */
function getId(type: MetadataType, row: any): any;
```


# JSON API Client Features
Source: https://docs.servicestack.net/vue/use-client

[useClient()](https://github.com/ServiceStack/servicestack-vue/blob/main/src/api.ts) provides managed APIs around the `JsonServiceClient` 
instance registered in Vue App's with:

```js
app.provide('client', client)
```

Which maintains contextual information around your API calls like **loading** and **error** states, used by `@servicestack/vue` components to 
enable its auto validation binding. Other functionality in this provider include:

```js
let { 
    api,            // Send a typed API request and return results in an ApiResult<TResponse>
    apiVoid,        // Send a typed API request and return empty response in a void ApiResult
    apiForm,        // Send a FormData API request and return results in an ApiResult<TResponse>
    apiFormVoid,    // Send a FormData API request and return empty response in a void ApiResult
    loading,        // Maintain loading state whilst API Request is in transit
    error,          // Maintain API Error response in reactive Ref<ResponseStatus>
    setError,       // Set API error state with summary or field validation error
    addFieldError,  // Add field error to API error state
    unRefs          // Returns a dto with all Refs unwrapped
} = useClient()
```

Typically you would need to unwrap `ref` values when calling APIs, i.e:

```js
let client = new JsonServiceClient()
let api = await client.api(new Hello({ name:name.value }))
```

### api

This is unnecessary in useClient `api*` methods which automatically unwraps ref values, allowing for the more pleasant API call:

```js
let api = await client.api(new Hello({ name }))
```

### unRefs

But as DTOs are typed, passing reference values will report a type annotation warning in IDEs with type-checking enabled, 
which can be avoided by explicitly unwrapping DTO ref values with `unRefs`:

```js
let api = await client.api(new Hello(unRefs({ name })))
```

### setError

`setError` can be used to populate client-side validation errors which the 
[SignUp.mjs](https://github.com/NetCoreTemplates/vue-mjs/blob/main/MyApp/wwwroot/Pages/SignUp.mjs)
component uses to report an invalid submissions when passwords don't match:

```js
const { api, setError } = useClient()
async function onSubmit() {
    if (password.value !== confirmPassword.value) {
        setError({ fieldName:'confirmPassword', message:'Passwords do not match' })
        return
    }
    //...
}
```

## Form Validation

All `@servicestack/vue` Input Components support contextual validation binding that's typically populated from API
[Error Response DTOs](/error-handling) but can also be populated from client-side validation
as done above.

### Explicit Error Handling

This populated `ResponseStatus` DTO can either be manually passed into each component's **status** property as done in [/Todos](https://vue-mjs.web-templates.io/TodoMvc):

```html
<template id="TodoMvc-template">
    <div class="mb-3">
        <text-input :status="store.error" id="text" label="" placeholder="What needs to be done?"
                    v-model="store.newTodo" v-on:keyup.enter.stop="store.addTodo()"></text-input>
    </div>
    <!-- ... -->
</template>
```

Where if you try adding an empty Todo the `CreateTodo` API will fail and populate its `store.error` reactive property with the 
APIs Error Response DTO which the `<TextInput />` component checks for to display any field validation errors matching the
field in `id` adjacent to the HTML Input:

```js
let store = {
    /** @type {Todo[]} */
    todos: [],
    newTodo:'',
    error:null,
    async refreshTodos(errorStatus) {
        this.error = errorStatus
        let api = await client.api(new QueryTodos())
        if (api.succeeded)
            this.todos = api.response.results
    },
    async addTodo() {
        this.todos.push(new Todo({ text:this.newTodo }))
        let api = await client.api(new CreateTodo({ text:this.newTodo }))
        if (api.succeeded)
            this.newTodo = ''
        return this.refreshTodos(api.error)
    },
    //...
}
```

### Implicit Error Handling

More often you'll want to take advantage of the implicit validation support in `useClient()` which makes its state available to child
components, alleviating the need to explicitly pass it in each component as seen in razor tailwind's 
[Contacts.mjs](https://github.com/NetCoreTemplates/razor/blob/net6/MyApp/wwwroot/Pages/Contacts.mjs) `Edit` component for its 
[/Contacts](https://vue-mjs.web-templates.io/Contacts) page which doesn't do any manual error handling:

```js
const Edit = {
    template:/*html*/`<SlideOver @done="close" title="Edit Contact">
    <form @submit.prevent="submit">
      <input type="submit" class="hidden">
      <fieldset>
        <ErrorSummary except="title,name,color,filmGenres,age,agree" class="mb-4" />
        <div class="grid grid-cols-6 gap-6">
          <div class="col-span-6 sm:col-span-3">
            <SelectInput id="title" v-model="request.title" :options="enumOptions('Title')" />
          </div>
          <div class="col-span-6 sm:col-span-3">
            <TextInput id="name" v-model="request.name" required placeholder="Contact Name" />
          </div>
          <div class="col-span-6 sm:col-span-3">
            <SelectInput id="color" v-model="request.color" :options="colorOptions" />
          </div>
          <div class="col-span-6 sm:col-span-3">
            <SelectInput id="favoriteGenre" v-model="request.favoriteGenre" :options="enumOptions('FilmGenre')" />
          </div>
          <div class="col-span-6 sm:col-span-3">
            <TextInput type="number" id="age" v-model="request.age" />
          </div>
        </div>
      </fieldset>
    </form>
    <template #footer>
      <div class="flex justify-between space-x-3">
        <div><ConfirmDelete @delete="onDelete">Delete</ConfirmDelete></div>
        <div><PrimaryButton @click="submit">Update Contact</PrimaryButton></div>
      </div>
    </template>
  </SlideOver>`,
    props:['contact'],
    emits:['done'],
    setup(props, { emit }) {
        const client = useClient()
        const request = ref(new UpdateContact(props.contact))
        const colorOptions = propertyOptions(getProperty('UpdateContact','Color'))

        async function submit() {
            const api = await client.api(request.value)
            if (api.succeeded) close()
        }
        
        async function onDelete () {
            const api = await client.apiVoid(new DeleteContact({ id:props.id }))
            if (api.succeeded) close()
        }

        const close = () => emit('done')
        
        return { request, enumOptions, colorOptions, submit, onDelete, close }
    }
}
```

This effectively makes form validation binding a transparent detail where all `@servicestack/vue` 
Input Components are able to automatically apply contextual validation errors next to the fields they apply to: 

<div class="my-8">
  <img class="mx-auto max-w-2xl" src="/img/pages/scripts/edit-contact-validation.png">
</div>

## Example using apiForm

An alternative method of invoking APIs is to submit a HTML Form Post which can be achieved with Ajax by sending a populated `FormData` 
with `client.apiForm()` as done in vue-mjs's 
[SignUp.mjs](https://github.com/NetCoreTemplates/vue-mjs/blob/main/MyApp/wwwroot/Pages/SignUp.mjs) for its 
[/signup](https://vue-mjs.web-templates.io/signup) page:

```js
import { ref } from "vue"
import { leftPart, rightPart, toPascalCase } from "@servicestack/client"
import { useClient } from "@servicestack/vue"
import { Register } from "../mjs/dtos.mjs"

export default {
    template:/*html*/`    
    <form @submit.prevent="submit">
      <div class="shadow overflow-hidden sm:rounded-md">
        <ErrorSummary except="displayName,userName,password,confirmPassword,autoLogin" />
        <div class="px-4 py-5 bg-white dark:bg-black space-y-6 sm:p-6">
          <div class="flex flex-col gap-y-4">
            <TextInput id="displayName" help="Your first and last name" v-model="request.displayName" />
            <TextInput id="userName" label="Email" placeholder="Email" help="" v-model="request.userName" />
            <TextInput id="password" type="password" help="6 characters max" v-model="request.password "/>
            <TextInput id="confirmPassword" type="password" v-model="request.confirmPassword" />
            <CheckboxInput id="autoLogin" v-model="request.autoLogin" />
          </div>
        </div>
        <div class="pt-5 px-4 py-3 bg-gray-50 dark:bg-gray-900 text-right sm:px-6">
          <div class="flex justify-end">
            <FormLoading v-if="loading" class="flex-1" />
            <PrimaryButton :disabled="loading" class="ml-3">Sign Up</PrimaryButton>
          </div>
        </div>
      </div>
    </form>`,
    props: { returnUrl:String },
    setup(props) {
        const client = useClient()
        const { setError, loading } = client
        const request = ref(new Register({ autoLogin:true }))

        /** @param email {string} */
        function setUser(email) {
            let first = leftPart(email, '@')
            let last = rightPart(leftPart(email, '.'), '@')
            const dto = request.value
            dto.displayName = toPascalCase(first) + ' ' + toPascalCase(last)
            dto.userName = email
            dto.confirmPassword = dto.password = 'p@55wOrd'
        }
        
        /** @param {Event} e */
        async function submit(e) {
            if (request.value.password !== request.value.confirmPassword) {
                setError({ fieldName: 'confirmPassword', message: 'Passwords do not match' })
                return
            }
            
            // Example using client.apiForm()
            const api = await client.apiForm(new Register(), new FormData(e.target))
            if (api.succeeded) {
                location.href = props.returnUrl || '/signin'
            }
        }
        
        return { loading, request, setUser, submit }
    }
}
```

Which method to use is largely a matter of preference except if your form needs to upload a file in which case using `apiForm` is required.

## AutoForm Components

We can elevate our productivity even further with [Auto Form Components](/vue/autoform) that can automatically generate an
instant API-enabled form with validation binding by just specifying the Request DTO to create the form for, e.g:

```html
<AutoCreateForm type="CreateBooking" formStyle="card" />
```

<div class="mb-4 not-prose">
<auto-create-form type="CreateBooking" form-style="card"></auto-create-form>
</div>

The AutoForm components are powered by your [App Metadata](/vue/use-metadata) which allows creating 
highly customized UIs from [declarative C# attributes](/locode/declarative) whose customizations are
reused across all ServiceStack Auto UIs.

## Stale-While-Revalidate APIs

A popular performance enhancing technique you can use to improve perceived performance between pages are to use State-While-Revalidate (SWR) APIs
which can deliver just as good UX as complex SPAs with stateless full page reloads of pre-rendered HTML pages if we use SWR to fetch all 
the API data needed to render the page on first load:

[![](/img/pages/release-notes/v6.9/diffusion-swr.gif)](https://diffusion.works)

This is easily achieved in reactive Vue.js UIs by invoking API requests with the new `swr()` client API where if 
the same API request had been run before it will execute the callback immediately with its "stale" cached results
in `localStorage` first, before invoking the callback again after receiving the API response with the latest data:

```ts
import { useClient } from "@servicestack/vue"
const client = useClient()

const results = ref([])
const topAlbums = ref([])
//...

onMounted(async () => {
    await Promise.all([
        client.swr(request.value, api => {
            results.value = api.response?.results || []
            //...
        }),
        client.swr(new AnonData(), async api => {
            topAlbums.value = api.response?.topAlbums || []
            //...
        }),
    ])
})
```

This results in UIs being immediately rendered on load and if the API response has changed, the updated reactive collections will re-render 
the UI with the updated data.

### swrEffect

The built-in `swrEffect()` API uses Vue's `watchEffect` to detect property changes to trigger invoking the API request and returning API responses 
in an idiomatic `ApiResult<T>` with a similarly pleasant declarative API without the unnecessary boilerplate:

```ts
const client = useClient()
//...

const api = client.swrEffect(() => new Hello({ name: props.name }))
```

It also includes a built-in [debounce feature](https://www.freecodecamp.org/news/javascript-debounce-example/) where you can collapse multiple event triggers within a specified duration (like input events when a user is typing), e.g. we can initiate an API request when a user has paused briefly after 50ms with:

```ts
const api = client.swrEffect(() => new Hello({ name: props.name }), { delayMs:50 })
```


## TypeScript Definition

TypeScript definition of the API surface area and type information for correct usage of `useClient()`

```ts
/** Maintain loading state whilst API Request is in transit */
const loading: Ref<boolean>

/** Maintain API Error in reactive Ref<ResponseStatus> */
const error: Ref<ResponseStatus>

/** Set error state with summary or field validation error */
function setError({ message, errorCode, fieldName, errors }: IResponseStatus);

/** Add field error to API error state */
function addFieldError({ fieldName, message, errorCode }: IResponseError);

/** Send a typed API request and return results in an ApiResult<TResponse> */
async function api<TResponse>(request:IReturn<TResponse> | ApiRequest, args?:any, method?:string);

/** Send a typed API request and return empty response in a void ApiResult */
async function apiVoid(request:IReturnVoid | ApiRequest, args?:any, method?:string);

/** Send a FormData API request and return results in an ApiResult<TResponse> */
async function apiForm<TResponse>(request:IReturn<TResponse> | ApiRequest, body:FormData, args?:any, method?:string);

/** Send a FormData API request and return empty response in a void ApiResult */
async function apiFormVoid(request: IReturnVoid | ApiRequest, body: FormData, args?: any, method?: string);
```


# Auth Features
Source: https://docs.servicestack.net/vue/use-auth

Vue.js Apps can access Authenticated Users using [useAuth()](/vue/use-auth)
which can also be populated without the overhead of an Ajax request by embedding the response of the built-in
[Authenticate API](https://blazor-vue.web-templates.io/ui/Authenticate?tab=details) inside `_Layout.cshtml` with:

```html
<script type="module">
import { useAuth } from "@@servicestack/vue"
const { signIn } = useAuth()
signIn(@await Html.ApiAsJsonAsync(new Authenticate()))
</script>
```

Where it enables access to the below [useAuth()](/vue/use-auth) utils for inspecting the 
current authenticated user:  

```js
const { 
    signIn,           // Sign In the currently Authenticated User
    signOut,          // Sign Out currently Authenticated User
    user,             // Access Authenticated User info in a reactive Ref<AuthenticateResponse>
    isAuthenticated,  // Check if the current user is Authenticated in a reactive Ref<boolean>
    hasRole,          // Check if the Authenticated User has a specific role
    hasPermission,    // Check if the Authenticated User has a specific permission
    isAdmin           // Check if the Authenticated User has the Admin role
} = useAuth()
```

An example where this is used is in 
[Bookings.mjs](https://github.com/NetCoreTemplates/blazor-vue/blob/main/MyApp/wwwroot/pages/Bookings.mjs)
to control whether the `<AutoEditForm>` component should enable its delete functionality:

```js
export default {
    template/*html*/:`
    <AutoEditForm type="UpdateBooking" :deleteType="canDelete ? 'DeleteBooking' : null" />
    `,
    setup(props) {
        const { hasRole } = useAuth()
        const canDelete = computed(() => hasRole('Manager'))
        return { canDelete }
    }
}
```

## TypeScript Definition

TypeScript definition of the API surface area and type information for correct usage of `useAuth()`

```ts
/** Access the currently Authenticated User info in a reactive Ref<AuthenticateResponse> */
const user: Ref<AuthenticateResponse>

/** Check if the current user is Authenticated in a reactive Ref<boolean> */
const isAuthenticated: Ref<boolean>

/** Sign In the currently Authenticated User */
function signIn(user:AuthenticateResponse): void;

/** Sign Out currently Authenticated User */
function signOut(): void;

/** Check if the Authenticated User has a specific role */
function hasRole(role:string): boolean;

/** Check if the Authenticated User has a specific permission */
function hasPermission(permission:string): boolean;

/** Check if the Authenticated User has the Admin role */
function isAdmin(): boolean;
```


# Formatting Functions and Methods
Source: https://docs.servicestack.net/vue/use-formatters

### Using Formatters

Your App and components can also utilize the built-in formatting functions in `useFormatters()`:

```js
import { useFormatters } from '@servicestack/vue'

const {
    Formats,              // Available format methods to use in <PreviewFormat />
    formatValue,          // Format any value or object graph
    currency,             // Format number as Currency
    bytes,                // Format number in human readable disk size
    link,                 // Format URL as <a> link
    linkTel,              // Format Phone Number as <a> tel: link
    linkMailTo,           // Format email as <a> mailto: link
    icon,                 // Format Image URL as an Icon
    iconRounded,          // Format Image URL as a full rounded Icon
    attachment,           // Format File attachment URL as an Attachment
    hidden,               // Format as empty string
    time,                 // Format duration in time format
    relativeTime,         // Format Date as Relative Time from now
    relativeTimeFromMs,   // Format time in ms as Relative Time from now
    relativeTimeFromDate, // Format difference between dates as Relative Time
    formatDate,           // Format as Date
    formatNumber,         // Format as Number

    setDefaultFormats,    // Set default locale, number and Date formats
    setFormatters,        // Register additional formatters for use in <PreviewFormat />
    indentJson,           // Prettify an API JSON Response
    truncate,             // Truncate text that exceeds maxLength with an ellipsis
    apiValueFmt,          // Format an API Response value
} = useFormatters()
```

Many of these formatting functions return rich HTML markup which will need to be rendered using Vue's **v-html** directive:

```html
<span v-html="formatValue(value)"></span>
```

See the [PreviewFormat](/vue/formats) for examples for what each of these format functions render to. 

<api-reference component="setDefaultFormats"></api-reference>
## Set global default formats

Global default formats can be customized with `setDefaultFormats`:

```js
setDefaultFormats({
    locale: null,     // Use Browsers default local
    assumeUtc: true,
    number: null,     // Use locale Number format
    date: {
        method: "Intl.DateTimeFormat",
        options: "{dateStyle:'medium'}"
    },
    maxFieldLength: 150,
    maxNestedFields: 150,
    maxNestedFieldLength: 150,
})
```

<api-reference component="setFormatters"></api-reference>
## Register custom formatters

Use `setFormatters` to register new formatters that you want to use in `[Format("method")]` or 
within `<PreviewFormat/>` components, e.g. you could register a formatter that renders a QR Code image of the content with:

```ts
import { QRCode } from "qrcode-svg"

function qrcode(content) {
    return new QRCode({ content, padding:4, width:256, height:256 }).svg()
}

setFormatters({
    qrcode,
})
```

Where it will be able to be used within format components, e.g:

```html
<PreviewFormat :value="url" :format="{ method:'qrcode' }" />
```

That can also be used to decorate properties in C# DTOs with the [Format Attribute](/locode/formatters), e.g:

```csharp
[Format("qrcode")]
public string Code { get; set; }
```

## Overriding built-in formatters

`setFormatters` can also be to override the built-in formatting functions by registering alternative implementations for:

```ts
setFormatters({
    currency,
    bytes,
    link,
    linkTel,
    linkMailTo,
    icon,
    iconRounded,
    attachment,
    hidden,
    time,
    relativeTime,
    relativeTimeFromMs,
    formatDate,
    formatNumber,
})
```

## TypeScript Definition

TypeScript definition of the API surface area and type information for correct usage of `useFormatters()`

```ts
class Formats {
    static currency: FormatInfo;
    static bytes: FormatInfo;
    static link: FormatInfo;
    static linkTel: FormatInfo;
    static linkMailTo: FormatInfo;
    static icon: FormatInfo;
    static iconRounded: FormatInfo;
    static attachment: FormatInfo;
    static time: FormatInfo;
    static relativeTime: FormatInfo;
    static relativeTimeFromMs: FormatInfo;
    static date: FormatInfo;
    static number: FormatInfo;
    static hidden: FormatInfo;
}

/** Format any value or object graph */
function formatValue(value: any, format?: FormatInfo | null, attrs?: any): any;

/** Format number as Currency */
function currency(val: number, attrs?: any): string;

/** Format number in human readable disk size */
function bytes(val: number, attrs?: any): string;


/** Format URL as <a> link */
function link(href: string, opt?: {
    cls?: string;
    target?: string;
    rel?: string;
}): string;

/** Format email as <a> mailto: link */
function linkMailTo(email: string, opt?: {
    subject?: string;
    body?: string;
    cls?: string;
    target?: string;
    rel?: string;
}): string;

/** Format Phone Number as <a> tel: link */
function linkTel(tel: string, opt?: {
    cls?: string;
    target?: string;
    rel?: string;
}): string;

/** Format Image URL as an Icon */
function icon(url: string, attrs?: any): string;

/** Format Image URL as a full rounded Icon */
function iconRounded(url: string, attrs?: any): string;

/** Format File attachment URL as an Attachment */
function attachment(url: string, attrs?: any): string;

/** Format as empty string */
function hidden(o: any): string;

/** Format duration in time format */
function time(o: any, attrs?: any): string;

/** Format Date as Relative Time from now */
function relativeTime(val: string | Date | number, rtf?: Intl.RelativeTimeFormat): string | undefined;

/** Format difference between dates as Relative Time */
function relativeTimeFromDate(d: Date, from?: Date): string | undefined;

/** Format time in ms as Relative Time from now */
function relativeTimeFromMs(elapsedMs: number, rtf?: Intl.RelativeTimeFormat): string | undefined;

/** Format as Date */
function formatDate(d: Date | string | number, attrs?: any): string;

/** Format as Number */
function formatNumber(n: number, attrs?: any): string;

/** Set default locale, number and Date formats */
function setDefaultFormats(newFormat: DefaultFormats): void;

/** Register additional formatters for use in <PreviewFormat /> */
function setFormatters(formatters: {
    [name: string]: Function;
}): void;

/** Prettify an API JSON Response */
function indentJson(o: any): string;

/** Truncate text that exceeds maxLength with an ellipsis */
function truncate(str: string, maxLength: number): string;

/** Format an API Response value */
function apiValueFmt(o: any, format?: FormatInfo | null, attrs?: any): any;
```


# File Utils
Source: https://docs.servicestack.net/vue/use-files

The file utils are utilized by the `<FileInput>` [Input component](/vue/form-inputs) and 
`icon`, `iconRounded` and `attachment` [formatters](/vue/use-formatters) for resolving file SVG Icons 
and MIME Types that Apps can also utilize in `useFiles()`

```js
import { useFiles } from '@servicestack/vue'

const {
    extSvg,           // Resolve SVG XML for file extension
    extSrc,           // Resolve SVG Data URI for file extension
    getExt,           // Resolve File extension from file name or path
    canPreview,       // Check if path or URI is of a supported web image type
    getFileName,      // Resolve file name from /file/path
    getMimeType,      // Resolve the MIME type for a file path name or extension
    formatBytes,      // Format file size in human readable bytes
    filePathUri,      // Resolve the Icon URI to use for file
    encodeSvg,        // Encode SVG XML for usage in Data URIs
    svgToDataUri,     // Convert SVG XML to data:image URL
    fileImageUri,     // Resolve image preview URL for file
    objectUrl,        // Create and track an Object URL for an uploaded file
    flush,            // Release all tracked Object URLs
    inputFiles,       // Resolve file metadata for all uploaded HTML input files
    iconOnError,      // Error handler for broken images to return a fallbackSrc
    iconFallbackSrc,  // Resolve the fallback URL for a broken Image URL
} = useFiles()
```

## TypeScript Definition

TypeScript definition of the API surface area and type information for correct usage of `useFiles()`

```ts
/** Resolve SVG XML for file extension */
function extSvg(ext: string): string | null;

/** Resolve SVG URI for file extension */
function extSrc(ext: string): any;

/** Resolve File extension from file name or path */
function getExt(path?: string | null): string | null;

/** Check if path or URI is of a supported web image type */
function canPreview(path: string): boolean;

/** Resolve file name from /file/path */
function getFileName(path?: string | null): string | null;

/** Resolve the MIME type for a file path name or extension */
function getMimeType(fileNameOrExt: string): string;

/** Format file size in human readable bytes */
function formatBytes(bytes: number, d?: number): string;

/** Resolve the Icon URI to use for file */
function filePathUri(path?: string): string | null;

/** Encode SVG XML for usage in Data URIs */
function encodeSvg(s: string): string;

/** Convert SVG XML to data:image URL */
function svgToDataUri(svg: string): string;

/** Resolve image preview URL for file */
function fileImageUri(file: any | {
    name: string;
}): string | null;

/** Create and track Image URL for an uploaded file */
function objectUrl(file: Blob | MediaSource): string;

/** Release all tracked Object URLs */
function flush(): void;

/** Resolve file metadata for all uploaded HTML file input files */
function inputFiles(input: HTMLInputElement): {
    fileName: string;
    contentLength: number;
    filePath: string | null;
}[] | null;

/** Error handler for broken images to return a fallbackSrc */
function iconOnError(img: HTMLImageElement, fallbackSrc?: string): void;

/** Resolve the fallback URL for a broken Image URL */
function iconFallbackSrc(src: string, fallbackSrc?: string): string | null;
```


# Vue Tailwind Global Configuration
Source: https://docs.servicestack.net/vue/use-config

## Manage Global Configuration

`useConfig` is used to maintain global configuration that's used throughout the Vue Component Library.

```ts
import { useConfig } from "@servicestack/vue"

const {
    config,                   // Resolve configuration in a reactive Ref<UiConfig>
    setConfig,                // Set global configuration
    assetsPathResolver,       // Resolve Absolute URL to use for relative paths
    fallbackPathResolver,     // Resolve fallback URL to use if primary URL fails
    autoQueryGridDefaults,    // Resolve AutoQueryGrid default configuration
    setAutoQueryGridDefaults, // Set AutoQueryGrid default configuration
} = useConfig()
```

The asset and fallback URL resolvers are useful when hosting assets on a separate CDN from the hosted website.

### Default configuration

```js
setConfig({
    redirectSignIn:       '/signin',
    assetsPathResolver:   src => src,
    fallbackPathResolver: src => src,
})
```

## AutoQueryGrid Defaults

Use `setAutoQueryGridDefaults` to change the default configuration for all [AutoQueryGrid](/vue/autoquerygrid) components:

```ts
const { setAutoQueryGridDefaults } = useConfig()

setAutoQueryGridDefaults({
    deny: [],
    hide: [],
    toolbarButtonClass: undefined,
    tableStyle: "stripedRows",
    take: 25,
    maxFieldLength: 150,
})
```

TypeScript Definitions for available AutoQueryGridDefaults:

```ts
type AutoQueryGridDefaults = {
    deny?:GridAllowOptions[]
    hide?:GridShowOptions[]
    toolbarButtonClass?: string
    tableStyle?: TableStyleOptions
    take?:number
    maxFieldLength?: number
}

export type GridAllowOptions = "filtering" | "queryString" | "queryFilters"
export type GridShowOptions = "toolbar" | "preferences" | "pagingNav" | "pagingInfo" | "downloadCsv" 
    | "refresh" | "copyApiUrl" | "resetPreferences" | "filtersView" | "newItem"
```

## TypeScript Definition

TypeScript definition of the API surface area and type information for correct usage of `useConfig()`

```ts
interface UiConfig {
    redirectSignIn?: string
    assetsPathResolver?: (src:string) => string
    fallbackPathResolver?: (src:string) => string
}

/** Resolve configuration in a reactive Ref<UiConfig> */
const config:ComputedRef<UiConfig>

/** Set global configuration */
function setConfig(config: UiConfig): void;

/** Resolve Absolute URL to use for relative paths */
function assetsPathResolver(src?: string): string | undefined;

/** Resolve fallback URL to use if primary URL fails */
function fallbackPathResolver(src?: string): string | undefined;
```


# General Utils
Source: https://docs.servicestack.net/vue/use-utils

General utils used by Vue Components you may also find useful in your Apps:

```js
import { useUtils } from "@servicestack/vue"

const {
    dateInputFormat,  // Format Date into required input[type=date] format
    timeInputFormat,  // Format TimeSpan or Date into required input[type=time] format
    setRef,           // Double set reactive Ref<T> to force triggering updates
    unRefs,           // Returns a dto with all Refs unwrapped
    transition,       // Update reactive `transition` class based on Tailwind animation transition rule-set
    focusNextElement, // Set focus to the next element inside a HTML Form
    getTypeName,      // Resolve Request DTO name from a Request DTO instance
    htmlTag,          // HTML Tag builder
    htmlAttrs,        // Convert object dictionary into encoded HTML attributes
    linkAttrs,        // Convert HTML Anchor attributes into encoded HTML attributes
    toAppUrl,         // Resolve Absolute URL from relative path
    isPrimitive,      // Check if value is a scalar type
    isComplexType,    // Check if value is a non-scalar type
} = useUtils()
```

## TypeScript Definition

TypeScript definition of the API surface area and type information for correct usage of `useUtils()`

```ts
/** Format Date into required input[type=date] format */
declare function dateInputFormat(d: Date): string;

/** Format TimeSpan or Date into required input[type=time] format */
declare function timeInputFormat(s?: string | number | Date | null): string;

/** Double set reactive Ref<T> to force triggering updates */
declare function setRef($ref: Ref<any>, value: any): void;

/** Returns a dto with all Refs unwrapped */
declare function unRefs(o: any): any;

/** Update reactive `transition` class based on Tailwind animation transition rule-set */
declare function transition(rule: TransitionRules, transition: Ref<string>, show: boolean): void;

/** Set focus to the next element inside a HTML Form */
declare function focusNextElement(): void;

/** Resolve Request DTO name from a Request DTO instance */
declare function getTypeName(dto: any): any;

/** HTML Tag builder */
declare function htmlTag(tag: string, child?: string, attrs?: any): string;

/** Convert object dictionary into encoded HTML attributes */
declare function htmlAttrs(attrs: any): string;

/** Convert HTML Anchor attributes into encoded HTML attributes */
declare function linkAttrs(attrs: {
    href: string;
    cls?: string;
    target?: string;
    rel?: string;
}): {
    target: string;
    rel: string;
    class: string;
} & {
    href: string;
    cls?: string | undefined;
    target?: string | undefined;
    rel?: string | undefined;
};

/** Resolve Absolute URL from relative path */
declare function toAppUrl(url: string): string | undefined;

/** Check if value is a scalar type */
declare function isPrimitive(value: any): boolean;

/** Check if value is a non-scalar type */
declare function isComplexType(value: any): boolean;
```