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 or returning a HttpError
3. Using a Request or Response Filter Attribute like the built-in [AddHeader] (or your own) or using a Global Request or Response Filter.
4. Modifying output by accessing your services base.Response IHttpResponse API

Here are some code examples below using these different approaches:

public class HelloService : Service
{ 
    public object Get(Hello request) 
    { 
        //1. Returning a custom Response Status and Description with Response DTO body:
        var responseDto = ...;
        return new HttpResult(responseDto, HttpStatusCode.Conflict) {
            StatusDescription = "Computer says no",
        };

        //2. Throw or return a HttpError:
        throw new HttpError(HttpStatusCode.Conflict, "SomeErrorCode");

        //3. Modify the Request's IHttpResponse
        base.Response.StatusCode = (int)HttpStatusCode.Redirect;
        base.Response.AddHeader("Location", "http://path/to/new/uri");
    }

    //4. Using a Request or Response Filter 
    [AddHeader(ContentType = "text/plain")]
    public string Get(Hello request)
    {
        return "Hello, {0}!".Fmt(request.Name);
    }
}

Tip: You can also return a HttpError everywhere in your code and it will behave the same as throwing the http error: return new HttpError(System.Net.HttpStatusCode.Conflict, "SomeErrorCode");

Using a Request or Response Filter Attribute

Example 4). uses the in-built AddHeaderAttribute to modify the HTTP Response using a Request Filter attribute. You can also modify all HTTP Service Responses by using a Global Request or Response Filter:

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);
        }
    }
...
}

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 or apply them globally with Global Request/Response Filters.

To be able to add custom hooks without needing to subclass any service, we've introduced a IServiceRunner 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:

public virtual IServiceRunner<TRequest> CreateServiceRunner<TRequest>(ActionContext actionContext)
{           
    return new ServiceRunner<TRequest>(this, actionContext); //Cached per Service Action
}

With your own:

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:

public class MyServiceRunner<T> : ServiceRunner<T> 
{
    public override void OnBeforeExecute(
        IRequestContext requestContext, TRequest request) 
    {
      // Called just before any Action is executed
    }

    public override object OnAfterExecute(
        IRequestContext requestContext, object response) 
    {
      // Called just after any Action is executed.
      // You can modify the response returned here as well
    }

    public override object HandleException(
        IRequestContext requestContext, TRequest request, Exception ex) 
    {
      // Called whenever an exception is thrown in your Services Action
    }
}