/// <summary>
/// Creates an instance of <see cref="WebApiModule"/> using the specified response serializer
/// and adds it to a module container without giving it a name.
/// </summary>
/// <typeparam name="TContainer">The type of the module container.</typeparam>
/// <param name="this">The <typeparamref name="TContainer"/> on which this method is called.</param>
/// <param name="baseRoute">The base route of the module.</param>
/// <param name="serializer">A <see cref="ResponseSerializerCallback"/> used to serialize
/// the result of controller methods returning <see langword="object"/>
/// or <see cref="Task{TResult}">Task<object></see>.</param>
/// <param name="configure">A callback used to configure the newly-created <see cref="WebApiModule"/>.</param>
/// <returns><paramref name="this"/> with a <see cref="RoutingModule"/> added.</returns>
/// <exception cref="NullReferenceException"><paramref name="this"/> is <see langword="null"/>.</exception>
/// <exception cref="ArgumentNullException">
/// <para><paramref name="serializer"/> is <see langword="null"/>.</para>
/// <para>- or -</para>
/// <para><paramref name="configure"/> is <see langword="null"/>.</para>
/// </exception>
/// <seealso cref="WebApiModule"/>
/// <seealso cref="WebApiModuleExtensions"/>
/// <seealso cref="IWebModuleContainer.Modules"/>
/// <seealso cref="IComponentCollection{T}.Add"/>
public static TContainer WithWebApi <TContainer>(
this TContainer @this,
string baseRoute,
ResponseSerializerCallback serializer,
Action <WebApiModule> configure)
where TContainer : class, IWebModuleContainer
=> WithWebApi(@this, null, baseRoute, serializer, configure);
/// <summary>
/// <para>Gets a <see cref="HttpExceptionHandlerCallback" /> that will serialize a HTTP exception's
/// <see cref="IHttpException.Message">Message</see> and <see cref="IHttpException.DataObject">DataObject</see> properties
/// and send them as a JSON response.</para>
/// <para>The response will be a JSON object with a <c>message</c> property and a <c>data</c> property.</para>
/// </summary>
/// <param name="serializerCallback">A <see cref="ResponseSerializerCallback" /> used to serialize data and send it to the client.</param>
/// <returns>A <see cref="HttpExceptionHandlerCallback" />.</returns>
/// <exception cref="ArgumentNullException"><paramref name="serializerCallback"/> is <see langword="null"/>.</exception>
public static HttpExceptionHandlerCallback FullDataResponse(ResponseSerializerCallback serializerCallback)
{
Validate.NotNull(nameof(serializerCallback), serializerCallback);
return((context, httpException) => serializerCallback(context, new
{
message = httpException.Message,
data = httpException.DataObject,
}));
}
/// <summary>
/// Creates an instance of <see cref="WebApiModule"/>, using the specified response serializer
/// and adds it to a module container, giving it the specified <paramref name="name"/>
/// if not <see langword="null"/>
/// </summary>
/// <typeparam name="TContainer">The type of the module container.</typeparam>
/// <param name="this">The <typeparamref name="TContainer"/> on which this method is called.</param>
/// <param name="name">The name.</param>
/// <param name="baseRoute">The base route of the module.</param>
/// <param name="serializer">A <see cref="ResponseSerializerCallback"/> used to serialize
/// the result of controller methods returning <see langword="object"/>
/// or <see cref="Task{TResult}">Task<object></see>.</param>
/// <param name="configure">A callback used to configure the newly-created <see cref="WebApiModule"/>.</param>
/// <returns><paramref name="this"/> with a <see cref="RoutingModule"/> added.</returns>
/// <exception cref="NullReferenceException"><paramref name="this"/> is <see langword="null"/>.</exception>
/// <exception cref="ArgumentNullException">
/// <para><paramref name="serializer"/> is <see langword="null"/>.</para>
/// <para>- or -</para>
/// <para><paramref name="configure"/> is <see langword="null"/>.</para>
/// </exception>
/// <seealso cref="WebApiModule"/>
/// <seealso cref="WebApiModuleExtensions"/>
/// <seealso cref="IWebModuleContainer.Modules"/>
/// <seealso cref="IComponentCollection{T}.Add"/>
public static TContainer WithWebApi <TContainer>(
this TContainer @this,
string?name,
string baseRoute,
ResponseSerializerCallback serializer,
Action <WebApiModule> configure)
where TContainer : class, IWebModuleContainer
{
configure = Validate.NotNull(nameof(configure), configure);
var module = new WebApiModule(baseRoute, serializer);
return(WithModule(@this, name, module, configure));
}
/// <summary>
/// <para>Gets a <see cref="HttpExceptionHandlerCallback" /> that will serialize a HTTP exception's
/// <see cref="IHttpException.DataObject">DataObject</see> property and send it as a JSON response.</para>
/// </summary>
/// <param name="serializerCallback">A <see cref="ResponseSerializerCallback" /> used to serialize data and send it to the client.</param>
/// <returns>A <see cref="HttpExceptionHandlerCallback" />.</returns>
/// <exception cref="ArgumentNullException"><paramref name="serializerCallback"/> is <see langword="null"/>.</exception>
public static HttpExceptionHandlerCallback DataResponse(ResponseSerializerCallback serializerCallback)
{
Validate.NotNull(nameof(serializerCallback), serializerCallback);
return((context, httpException) => serializerCallback(context, httpException.DataObject));
}
/// <summary>
/// Initializes a new instance of the <see cref="WebApiModuleBase" /> class,
/// using the specified response serializer.
/// </summary>
/// <param name="baseRoute">The base route served by this module.</param>
/// <param name="serializer">A <see cref="ResponseSerializerCallback"/> used to serialize
/// the result of controller methods returning <see langword="object"/>
/// or <see cref="Task{TResult}">Task<object></see>.</param>
/// <exception cref="ArgumentNullException"><paramref name="serializer"/> is <see langword="null"/>.</exception>
/// <seealso cref="IWebModule.BaseRoute" />
/// <seealso cref="Validate.UrlPath" />
protected WebApiModuleBase(string baseRoute, ResponseSerializerCallback serializer)
: base(baseRoute)
{
Serializer = Validate.NotNull(nameof(serializer), serializer);
}
/// <summary>
/// Initializes a new instance of the <see cref="WebApiModule" /> class,
/// using the specified response serializer.
/// </summary>
/// <param name="baseRoute">The base URL path served by this module.</param>
/// <param name="serializer">A <see cref="ResponseSerializerCallback"/> used to serialize
/// the result of controller methods returning <see langword="object"/>
/// or <see cref="Task{TResult}">Task<object></see>.</param>
/// <exception cref="ArgumentNullException"><paramref name="serializer"/> is <see langword="null"/>.</exception>
/// <seealso cref="IWebModule.BaseRoute" />
/// <seealso cref="Validate.UrlPath" />
public WebApiModule(string baseRoute, ResponseSerializerCallback serializer)
: base(baseRoute, serializer)
{
}
/// <summary> /// <para>Asynchronously sends serialized data as a response, using the specified response serializer.</para> /// <para>As of EmbedIO version 3.0, the default response serializer has the same behavior of JSON /// response methods of version 2.</para> /// </summary> /// <param name="this">The <see cref="IHttpContext"/> interface on which this method is called.</param> /// <param name="serializer">A <see cref="ResponseSerializerCallback"/> used to prepare the response.</param> /// <param name="data">The data to serialize.</param> /// <returns>A <see cref="Task"/> representing the ongoing operation.</returns> /// <exception cref="NullReferenceException"><paramref name="this"/> is <see langword="null"/>.</exception> /// <exception cref="ArgumentNullException"><paramref name="serializer"/> is <see langword="null"/>.</exception> /// <seealso cref="SendDataAsync(IHttpContext,ResponseSerializerCallback,object)"/> /// <seealso cref="ResponseSerializer.Default"/> public static Task SendDataAsync(this IHttpContext @this, ResponseSerializerCallback serializer, object data) => Validate.NotNull(nameof(serializer), serializer)(@this, data);
