DevInstance.WebServiceToolkit 10.3.2

DevInstance.WebServiceToolkit

ASP.NET Core utilities for web service development including query model binding, exception handling, and service registration.

Installation

dotnet add package DevInstance.WebServiceToolkit

This package includes DevInstance.WebServiceToolkit.Common and DevInstance.WebServiceToolkit.Database as dependencies.

Features

• Query Model Binding - Automatic binding of query string parameters to strongly-typed POCOs
• Exception Handling - Standardized HTTP exception types with automatic response mapping
• Service Registration - Attribute-based automatic dependency injection

Quick Start

1. Configure Services

using DevInstance.WebServiceToolkit.Http.Query;
using DevInstance.WebServiceToolkit.Tools;

var builder = WebApplication.CreateBuilder(args);

// Add query model binding support
builder.Services.AddControllers()
    .AddWebServiceToolkitQuery();

// Auto-register services marked with [WebService]
builder.Services.AddServerWebServices();

2. Query Model Binding

Define query models with the [QueryModel] attribute:

using DevInstance.WebServiceToolkit.Http.Query;
using System.ComponentModel;

[QueryModel]
public class ProductQuery
{
    [DefaultValue(0)]
    public int Page { get; set; }

    [DefaultValue(20)]
    public int PageSize { get; set; }

    public string? Search { get; set; }

    [QueryName("sort")]
    public string? SortBy { get; set; }
}

Use in controllers - binding happens automatically:

[HttpGet]
public ActionResult<ProductList> GetProducts(ProductQuery query)
{
    // query is populated from ?page=0&pageSize=20&search=widget&sort=name
}

3. Exception Handling

Use HandleWebRequestAsync to automatically convert exceptions to HTTP responses:

using DevInstance.WebServiceToolkit.Controllers;
using DevInstance.WebServiceToolkit.Exceptions;

[HttpGet("{id}")]
public Task<ActionResult<Product>> GetProduct(string id)
{
    return this.HandleWebRequestAsync<Product>(async () =>
    {
        var product = await _productService.GetByIdAsync(id);
        if (product == null)
            throw new RecordNotFoundException(id);  // Returns 404
        return Ok(product);
    });
}

Exception to HTTP Status Mapping:

Every error response carries a WebServiceError JSON body:

{ "errorType": 3, "message": "Name is required", "propertyName": "Name" }

It is wire-compatible with DevInstance.BlazorToolkit's ServiceActionError, so Blazor clients using HttpApiContext read the message and property name directly. Derive your own domain exceptions from WebServiceException (or a concrete exception) to control their status code.

To give [ApiController] model-validation failures the same body, register:

builder.Services.AddControllers()
    .AddWebServiceToolkitErrors();

A global IExceptionHandler can produce the same body for exceptions thrown outside HandleWebRequestAsync via ControllerUtils.ToWebServiceError(exception).

4. Service Registration

Mark services for automatic DI registration:

using DevInstance.WebServiceToolkit.Tools;

public interface IProductService
{
    Task<Product?> GetByIdAsync(string id);
}

[WebService]
public class ProductService : IProductService
{
    // Automatically registered as scoped service
}

// For testing, use WebServiceMock
[WebServiceMock]
public class MockProductService : IProductService
{
    // Register with AddServerWebServicesMocks()
}

Register services:

// Production
builder.Services.AddServerWebServices();

// Testing
builder.Services.AddServerWebServicesMocks();

API Reference

Query Model Binding

Exceptions

Controllers

Service Registration

See Also

• DevInstance.WebServiceToolkit.Common - Common models (no ASP.NET Core dependency)
• DevInstance.WebServiceToolkit.Database - Database query interfaces