Voir la source de Asp.net core 9 web api

[[Category:.NET Core]]
= Links =
* [[Swagger]]

= New projet =
<kode lang='bash'>
dotnet new webapi -o [project-name] --no-https
</kode>
{{info | On VS to not open the web brower when you start the application: right-click on the project → Properties → Debug → uncheck Launch browser}}

= [https://learn.microsoft.com/en-us/aspnet/core/tutorials/first-web-api?view=aspnetcore-8.0&tabs=visual-studio Controller] =
<filebox fn='Controllers/ItemsController.cs'>
[ApiController]
[Route("[controller]")]         // /item
[Produces("application/json")]  // inform about the output format, default is plain text (force le format JSON?)
public class ItemController(IItemService itemService) : ControllerBase
{ /* ... */ }
</filebox>

* [https://learn.microsoft.com/en-us/aspnet/core/web-api/action-return-types?view=aspnetcore-8.0 Controller action return types]

== GET ==
<kode lang='cs'>
[HttpGet("{id:int}")]
[ProducesResponseType(typeof(ItemResponse), StatusCodes.Status200OK)]
[ProducesResponseType(StatusCodes.Status404NotFound)]
public async Task<IActionResult> GetByIdAsync(int id, CancellationToken cancellationToken)
{
    var item = await context.Items
        .AsNoTracking()
        .FirstOrDefaultAsync(x => x.Id == id, cancellationToken);

    return item is null ? NotFound() : Ok(mapper.Map<ItemResponse>(item));
}

[HttpGet]
[ProducesResponseType(typeof(IReadOnlyCollection<ItemResponse>), StatusCodes.Status200OK)]
[ProducesResponseType(typeof(ValidationProblemDetails), StatusCodes.Status400BadRequest)]
public async Task<IActionResult> GetAsync([FromQuery] ItemQuery query, CancellationToken cancellationToken)
{
    var predicate = PredicateBuilder.New<Item>(true);
    if (!string.IsNullOrEmpty(query.Name))
    {
        predicate = predicate.And(x => EF.Functions.Like(x.Name, $"%{query.Name}%"));
    }
    if (query.Ids != null && query.Ids.Count > 0)
    {
        predicate = predicate.And(x => query.Ids.Contains(x.Id));
    }

    var items = await context.Items
        .Where(predicate)
        .AsNoTracking()
        .ToListAsync(cancellationToken);

    return Ok(mapper.Map<IReadOnlyCollection<ItemResponse>>(items));
}
</kode>

== POST ==
<kode lang='csharp'>
[HttpPost]
[ProducesResponseType(typeof(ItemResponse), StatusCodes.Status201Created)]
[ProducesResponseType(typeof(ValidationProblemDetails), StatusCodes.Status400BadRequest)]
public async Task<IActionResult> CreateAsync(CreateUpdateItemQuery query, CancellationToken cancellationToken)
{
    var item = this.mapper.Map<Item>(query);
    await context.AddAsync(item, cancellationToken);
    await context.SaveChangesAsync(cancellationToken);

    var response = this.mapper.Map<ItemResponse>(item);

    // uri to the newly created item
    var uri = new Uri($"https://www.site.net/items/{createdItem.Id}");
    return Created(uri, response);

    var actionName = nameof(ItemController.GetByIdAsync);  // default to controller method name. Tmo handle Async suffix see the warning box below
    var controllerName = "Item";  // default to controller name. Don't add the 'Controller' suffix
    var routeValues = new { id = item.Id }; // path and query parameters
    return CreatedAtAction(actionName, controllerName, routeValues, response);

    var routeValues = new
    {
        controller = "Item",  // name of the controller without "Controller", set only if it is a different one
        action = nameof(ItemController.GetByIdAsync),  // name of a controller method, optional
        id = item.Id  // set the id and all other needed parameters
    };
    return CreatedAtRoute(routeValues, createdResource);
}
</kode>
* [https://ochzhen.com/blog/created-createdataction-createdatroute-methods-explained-aspnet-core Created, CreatedAtAction, CreatedAtRoute methods]
{{warn | 
To handle Async suffix in CreatedAtAction
<filebox fn='Program.cs'>
builder.Services.AddControllers(options =>
{
    options.SuppressAsyncSuffixInActionNames = false;
});
</filebox>
}}

== [https://docs.microsoft.com/en-us/aspnet/core/tutorials/first-web-api PUT / Update] ==
<kode lang='csharp'>
[HttpPut("{id}")]
[ProducesResponseType(StatusCodes.Status204NoContent)]
[ProducesResponseType(typeof(ValidationProblemDetails), StatusCodes.Status400BadRequest)]
[ProducesResponseType(StatusCodes.Status404NotFound)]
public async Task<IActionResult> UpdateAsync(int id, CreateUpdateItemQuery query)
{
    var itemToUpdate = await context.Items.FirstOrDefaultAsync(x => x.Id == id, cancellationToken);
    if (itemToUpdate is null)
    {
        return NotFound();
    }

    this.mapper.Map(query, itemToUpdate);
    await context.SaveChangesAsync(cancellationToken);

    return NoContent();
}
</kode>

== DELETE ==
<kode lang='cs'>
[HttpDelete("{id:int}")]
[ProducesResponseType(StatusCodes.Status204NoContent)]
[ProducesResponseType(StatusCodes.Status404NotFound)]
public async Task<IActionResult> DeleteAsync(int id, CancellationToken cancellationToken)
{
    if (!await context.Items.AnyAsync(x => x.Id == id, cancellationToken))
    {
        return NotFound();
    }

    context.Remove(new Item { Id = id });
    await context.SaveChangesAsync(cancellationToken);
    return NoContent();
}
</kode>

== Headers ==
<kode lang='cs'>
Response.Headers.Append("Key", "Value");
</kode>

== [https://medium.com/@celery_liu/asp-net-core-web-api-with-swagger-api-versioning-for-dotnet-8-c8ce2fd7808c Version] ==
* [[Swagger#Version|Configure Swagger to handle version]]
<filebox fn='Program.cs'>
// nuget package Asp.Versioning.Mvc
builder.Services
    .AddApiVersioning(options =>
    {
        options.ReportApiVersions = true;
        options.AssumeDefaultVersionWhenUnspecified = true;
        options.DefaultApiVersion = new ApiVersion(1, 0);
    });
</filebox>

<filebox fn='ItemController.cs'>
[ApiVersion("1.0")]
[Route("v{version:apiVersion}/[controller]")]
[ApiController]
public class ItemController : ControllerBase
{ }
</filebox>

= [https://learn.microsoft.com/en-us/aspnet/core/web-api/handle-errors?view=aspnetcore-7.0#problem-details-service Return exceptions as problem details response] =
{{info | By default exceptions are returned in plain text.<br>With the problem details service it returns now a problem details response.}}
{{warn | In case of exception the media type returned is {{boxx|application/problem+json}} which is not handled by default on the client side.}}

<filebox fn='Program.cs'>
//builder.Services.AddControllers();
builder.Services.AddProblemDetails();

//var app = builder.Build();

app.UseExceptionHandler();
app.UseStatusCodePages();


if (app.Environment.IsDevelopment())
{
    app.UseDeveloperExceptionPage();
}

//app.MapControllers();
//app.Run();
</filebox>

== [https://learn.microsoft.com/en-us/aspnet/core/web-api/handle-errors?view=aspnetcore-7.0#exception-handler OLD Exception handler] ==
<filebox fn='Program.cs' collapsed>
//var app = builder.Build();

if (app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/error-development");
}
else
{
    app.UseExceptionHandler("/error");
}

//app.UseAuthorization();
</filebox>

<filebox fn='Controllers/ErrorController.cs' collapsed>
[ApiController]
public class ErrorController : ControllerBase
{
    [Route("/error")]
    [ApiExplorerSettings(IgnoreApi = true)]
    public IActionResult HandleError() => Problem();

    [Route("/error-development")]
    [ApiExplorerSettings(IgnoreApi = true)]
    public IActionResult HandleErrorDevelopment([FromServices] IHostEnvironment hostEnvironment)
    {
        if (!hostEnvironment.IsDevelopment())
        {
            return NotFound();
        }

        var exceptionHandlerFeature = HttpContext.Features.Get<IExceptionHandlerFeature>()!;

        return Problem(
            detail: exceptionHandlerFeature.Error.StackTrace,
            title: GetFinalInnerException(exceptionHandlerFeature.Error).Message);

        static Exception GetFinalInnerException(Exception exception)
            => exception.InnerException is null ? exception : GetFinalInnerException(exception.InnerException);
    }
}
</filebox>

== Handle application/problem+json on the client side ==
<filebox fn='Clients/ItemClient.cs'>
private static IEnumerable<MediaTypeFormatter> problemJsonMediaTypeFormatters
    => new MediaTypeFormatter[1] { new ProblemJsonMediaTypeFormatter() };

var response = await httpClient.GetAsync(uri, cancellationToken);
if (response.StatusCode == System.Net.HttpStatusCode.BadRequest)
{
    var validationProblemDetails =
        await response.Content.ReadAsAsync<ValidationProblemDetails>(
            problemJsonMediaTypeFormatters, cancellationToken);
</filebox>

<filebox fn='MediaTypeFormatters/ProblemJsonMediaTypeFormatter.cs'>
public class ProblemJsonMediaTypeFormatter : JsonMediaTypeFormatter
{
    private static readonly MediaTypeHeaderValue problemJsonMediaType = new("application/problem+json");

    public ProblemJsonMediaTypeFormatter()
    {
        SupportedMediaTypes.Add(problemJsonMediaType);
    }
}
</filebox>

= [[Fluent_validation|Fluent Validation]] =
* [https://github.com/FluentValidation/FluentValidation.AspNetCore GitHub]
* [https://docs.fluentvalidation.net/en/latest/index.html Documentation]
<kode lang='bash'>
dotnet add package FluentValidation.AspNetCore
</kode>

<filebox fn='Program.cs'>
//builder.Services.AddControllers();
builder.Services.AddFluentValidationAutoValidation();

builder.Services.AddValidatorsFromAssemblyContaining<Program>();
</filebox>

<filebox fn='Validators/ItemValidator.cs'>
public class CreateItemQueryValidator : AbstractValidator<CreateItemQuery>
{
    public CreateItemQueryValidator()
    {
        RuleFor(x => x.Name).NotEmpty();
        RuleFor(x => x.Description)
            .MinimumLength(3)
            .Unless(x => string.IsNullOrEmpty(x.Description)); // empty or min lenght 3
</filebox>

= [https://learn.microsoft.com/en-us/aspnet/core/host-and-deploy/health-checks?view=aspnetcore-7.0 Health check] =
<filebox fn='Program.cs'>
//var builder = WebApplication.CreateBuilder(args);

builder.Services
    .AddHealthChecks()
    .AddDbContextCheck<MyAppContext>(); // add Microsoft.Extensions.Diagnostics.HealthChecks.EntityFrameworkCore package

//var app = builder.Build();

app.MapHealthChecks("/health");
</filebox>

{| class="wikitable wtp" 
! HTTP Code
! Description
|-
| 200 || healthy
|-
| 503 || unhealthy
|}

= CORS =
<filebox fn='Programs.cs'>
// app.UseStaticFiles();

// fix access from origin '...' has been blocked by CORS policy: No 'Access-Control-Allow-Origin' header is present on the requested resource
// allow all origins
app.UseCors(x => x.SetIsOriginAllowed(origin => true));
// allow https://localhost:4200
app.UseCors(x => x.WithOrigins("https://localhost:4200"));
</filebox>

= [https://stackoverflow.com/questions/36358751/how-do-you-enforce-lowercase-routing-in-asp-net-core URL with kebab case] =
<filebox fn='Program.cs'>
builder.Services
    .AddControllers(options =>
    {
        options.Conventions.Add(new RouteTokenTransformerConvention(new KebabCaseParameterTransformer()));
    })
</filebox>

<filebox fn='KebabCaseParameterTransformer.cs'>
public partial class KebabCaseParameterTransformer : IOutboundParameterTransformer
{
    [GeneratedRegex("([a-z])([A-Z])")]
    private static partial Regex kebabCaseRegex();

    public string? TransformOutbound(object? value)
        => value == null ? null : kebabCaseRegex().Replace(value.ToString(), "$1-$2").ToLower();
}
</filebox>

= Client =
<filebox fn='Client/ItemClient.cs'>
public class ItemClient : IItemClient
{
    private const string PATH = "item";
    private const string APIVERSION = "1";

    private readonly HttpClient httpClient;
    private readonly QueryBuilder queryBuilder;

    // injection de HttpClient
    public ItemClient(HttpClient httpClient)
    {
        this.httpClient = httpClient;

        queryBuilder = new QueryBuilder();
        queryBuilder.Add("api-version", APIVERSION);
    }
</filebox>

<filebox fn='Clients/OperationResult.cs' collapsed>
public class OperationResult<T>
{
    private readonly IDictionary<string, string[]> validationErrors;

    public T? Result { get; }
    public IReadOnlyCollection<string> ErrorMessages => validationErrors.SelectMany(x => x.Value).ToList();
    public bool IsValid => validationErrors.Count == 0;

    // used to handle errors of server validation
    public OperationResult(IDictionary<string, string[]> validationErrors)
    {
        this.validationErrors = validationErrors;
    }

    // used to handle errros of client validation with FluentValidation
    public OperationResult(IEnumerable<ValidationFailure> validationFailures)
    {
        validationErrors = validationFailures
            .GroupBy(x => x.PropertyName, x => x.ErrorMessage)
            .ToDictionary(x => x.Key, x => x.ToArray());
    }

    // used to handle error
    public OperationResult(string errorMessage)
    {
        validationErrors = new Dictionary<string, string[]> { { string.Empty, new string[] { errorMessage } } };
    }

    // use to hanlde valid result
    public OperationResult(T result)
    {
        Result = result;
        validationErrors = new Dictionary<string, string[]>();
    }
}
</filebox>

<filebox fn='Clients/OperationStatus.cs' collapsed>
public class OperationStatus
{
    public string ErrorMessage { get; }
    public IDictionary<string, string[]> Errors { get; }
    public bool Success => string.IsNullOrEmpty(ErrorMessage) && Errors.Count == 0;

    // use to hanlde valid status
    public OperationStatus()
    {
        ErrorMessage = string.Empty;
        Errors = new Dictionary<string, string[]>();
    }

    // used to handle single error of server validation
    public OperationStatus(string errorMessage)
    {
        ErrorMessage = errorMessage;
        Errors = new Dictionary<string, string[]>();
    }

    // used to handle errors of server validation
    public OperationStatus(IDictionary<string, string[]> errors)
    {
        ErrorMessage = string.Empty;
        Errors = errors;
    }
}
</filebox>

<filebox fn='Extensions/QueryExtensions.cs' collapsed>
public static class QueryExtensions
{
    public static QueryString ToQueryString(this FetchItemQuery query)
    {
        var queryBuilder = new QueryBuilder
        {
            { nameof(query.PageIndex), query.PageIndex.ToString(CultureInfo.InvariantCulture) },
            { nameof(query.PageSize), query.PageSize.ToString(CultureInfo.InvariantCulture) }
        };

        queryBuilder.AddIfValueNotNullNorEmpty(nameof(query.MyProperty), query.MyProperty);

        return queryBuilder.ToQueryString();
    }
}
</filebox>

<filebox fn='Extensions/QueryBuilderExtensions.cs' collapsed>
public static class QueryBuilderExtensions
{
    public static void AddIfValueNotNullNorEmpty(this QueryBuilder source, string key, string value)
    {
        if (string.IsNullOrEmpty(value))
        {
            return;
        }

        source.Add(key, value);
    }
}
</filebox>

== Dependency Injection ==
[https://learn.microsoft.com/en-us/dotnet/core/extensions/httpclient-factory#typed-clients Typed clients] are transient objects usually injected into services.<br>
They are expected to be short-lived.<br>
If a typed client instance is captured in a [https://learn.microsoft.com/en-us/dotnet/core/extensions/httpclient-factory#avoid-typed-clients-in-singleton-services singleton], it may prevent it from reacting to DNS changes, defeating one of the purposes of IHttpClientFactory.
<filebox fn='Program.cs'>
services
    .AddHttpClient<IMyClient, MyClient>(x =>
    {
        x.DefaultRequestHeaders.Authorization = // AuthenticationHeaderValue see below

        x.BaseAddress = new Uri("https://www.address.net");
        x.DefaultRequestHeaders.UserAgent.ParseAdd("my-app");
        x.Timeout = TimeSpan.FromSeconds(100); // default 100s
    })
    .ConfigurePrimaryHttpMessageHandler(() => new HttpClientHandler
    {
        Proxy = new WebProxy
        {
            Address = new Uri($"http://localhost:9000"),
            BypassProxyOnLocal = false,
            UseDefaultCredentials = false,
        },
    });
</filebox>
* [https://medium.com/@szntb/getting-burnt-with-httpclient-9c1712151039 Getting burnt with HttpClient]

=== Basic Base64 user password authentication ===
<kode lang='cs' collapsed>
var authenticationString = $"{username}:{password}";
var base64EncodedAuthenticationString = Convert.ToBase64String(Encoding.ASCII.GetBytes(authenticationString));
x.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Basic", base64EncodedAuthenticationString);
</kode>

=== AAD OAuth2 JWT authentication ===
<kode lang='cs' collapsed>
var builder = ConfidentialClientApplicationBuilder
    .Create(clientId)
    .WithClientSecret(clientSecret)
    .WithAuthority(new Uri(authorityUri))
    .Build();
var result = await builder
    .AcquireTokenForClient([scope])
    .ExecuteAsync();
x.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", result.AccessToken);
</kode>

=== Cognito OAuth2 JWT authentication ===
<kode lang='cs' collapsed>
var request = new HttpRequestMessage(HttpMethod.Post, tokenEndPoint);
var authHeader = Convert.ToBase64String(Encoding.UTF8.GetBytes($"{clientId}:{clientSecret}"));
request.Headers.Authorization = new AuthenticationHeaderValue("Basic", authHeader);
request.Content = new FormUrlEncodedContent(
[
    new KeyValuePair<string, string>("grant_type", "client_credentials"),
    new KeyValuePair<string, string>("scope", scope)
]);

using var httpClient = new HttpClient();
var response = await httpClient.SendAsync(request);
response.EnsureSuccessStatusCode();

var responseContent = await response.Content.ReadAsStringAsync();
var tokenResponse = JObject.Parse(responseContent);
var accessToken = tokenResponse["access_token"].ToString();

x.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", accessToken);
</kode>

== Cache ==
<filebox fn='Program.cs'>
services.AddMemoryCache();  // inject IMemoryCache
</filebox>

<filebox fn='MyClient.cs' collapsed>
public class MyClient(HttpClient httpClient, IMemoryCache cache) : IMyClient
{
    private static readonly TimeSpan expiration = TimeSpan.FromHours(1);

    private async Task<Item[]> GetItemsAsync()
    {
        var uri = "items";

        if (cache.TryGetValue(uri, out Item[]? cachedResponse))
            return cachedResponse;

        var response = await httpClient.GetAsync(uri);
        if (!response.IsSuccessStatusCode)
        {
            // handle error
            var errorMessage = $"url: {httpClient.BaseAddress}/{uri}, status code: {response.StatusCode}, content: {await response.Content.ReadAsStringAsync()}";
            return [];
        }

        var content = await response.Content.ReadFromJsonAsync<Item[]?>();
        cache.Set(uri, content, expiration);

        return content;
    }
</filebox>

== GET ==
<kode lang='cs'>
// all in 1: get response, EnsureSuccessStatusCode, then deserialize the content
var items = await httpClient.GetFromJsonAsync<ItemResponse[]>(uri) ?? [];

// step by step
var response = await HttpClient.GetAsync(uri, cancellationToken);
if (response.StatusCode == HttpStatusCode.???)
    // handle status code error

response.EnsureSuccessStatusCode();

var items = (await response.Content.ReadFromJsonAsync<ItemResponse[]>(cancellationToken)) ?? [];
</kode>

=== Json Converters ===
<kode>
public class ItemResponse
{
    [JsonConverter(typeof(JsonStringEnumConverter))]  // allow (de)serialization from/to string
    public ItemType ItemType { get; set; }
    [JsonConverter(typeof(JsonStringBoolConverter))]  // allow (de)serialization from/to string
    public bool Archived { get; set; }
}

public enum ItemType
{
    Main,
    Specific
}
</kode>

<filebox fn='JsonStringBoolConverter.cs' collapsed>
public class JsonStringBoolConverter: JsonConverter<bool>
{
    public override void Write(Utf8JsonWriter writer, bool value, JsonSerializerOptions options)
        => writer.WriteBooleanValue(value);

    public override bool Read(ref Utf8JsonReader reader, Type typeToConvert, JsonSerializerOptions options)
        => reader.TokenType switch
        {
            JsonTokenType.True => true,
            JsonTokenType.False => false,
            JsonTokenType.String
                => bool.TryParse(reader.GetString(), out var b) ? b : throw new JsonException(),
            JsonTokenType.Number
                => reader.TryGetInt64(out var l)
                ? Convert.ToBoolean(l)
                : reader.TryGetDouble(out var d) && Convert.ToBoolean(d),
            _ => throw new JsonException(),
        };
}
</filebox>

== POST ==
<kode lang='cs'>
public async Task<OperationStatus> CreateAsync(CreateUpdateItemQuery query)
{
    ArgumentNullException.ThrowIfNull(query);

    var uri = new Uri(PATH, UriKind.Relative);

    var response = await httpClient.PostAsJsonAsync(uri, query);
    // old way
    var queryJson = new StringContent(JsonSerializer.Serialize(query), Encoding.UTF8, "application/json");
    var response = await httpClient.PostAsync(uri, queryJson);

    if (response.StatusCode == HttpStatusCode.BadRequest)
    {
        var validationProblemDetails =
            await response.Content.ReadAsAsync<ValidationProblemDetails>(
                problemJsonMediaTypeFormatters, cancellationToken);

        return validationProblemDetails is null
            ? throw new InvalidDataException($"{nameof(validationProblemDetails)} is null")
            : new OperationStatus(validationProblemDetails.Errors);
    }

    response.EnsureSuccessStatusCode();

    // var item = await response.Content.ReadFromJsonAsync<ItemResponse>(cancellationToken);

    return new OperationStatus();
</kode>

== PUT ==
<kode lang='cs'>
public async Task<OperationStatus> UpdateAsync(int id, CreateUpdateItemQuery query, CancellationToken cancellationToken)
{
    ArgumentNullException.ThrowIfNull(query);

    var uri = new Uri($"{Path}/{id}", UriKind.Relative);
    var queryJson = new StringContent(JsonSerializer.Serialize(query), Encoding.UTF8, "application/json");

    var response = await httpClient.PutAsync(uri, queryJson, cancellationToken);
    if (response.StatusCode == HttpStatusCode.BadRequest)
    {
        var validationProblemDetails =
            await response.Content.ReadAsAsync<ValidationProblemDetails>(
                problemJsonMediaTypeFormatters, cancellationToken);

        return validationProblemDetails is null
            ? throw new InvalidDataException($"{nameof(validationProblemDetails)} is null")
            : new OperationStatus(validationProblemDetails.Errors);
    }

    if (response.StatusCode == HttpStatusCode.NotFound)
    {
        return new OperationStatus($"Item {id} has not been found.");
    }

    response.EnsureSuccessStatusCode();

    return new OperationStatus();
</kode>

== DELETE ==
<kode lang='cs'>
public async Task<OperationStatus> DeleteAsync(int id, CancellationToken cancellationToken)
{
    var uri = new Uri($"{Path}/{id}", UriKind.Relative);
    var response = await httpClient.DeleteAsync(uri, cancellationToken);

    if (response.StatusCode == HttpStatusCode.NotFound)
    {
        return new OperationStatus($"Item {id} has not been found.");
    }

    if (response.StatusCode == HttpStatusCode.InternalServerError)
    {
        var problemDetails = await response.Content.ReadAsAsync<ProblemDetails>(
            problemJsonMediaTypeFormatters, cancellationToken);

        var errorMessage = problemDetails is null || string.IsNullOrEmpty(problemDetails.Detail)
            ? "Unable to read the ProblemDetails error message"
            : problemDetails.Detail.Replace(" See the inner exception for details.", string.Empty);

        return new OperationStatus(errorMessage);
    }

    response.EnsureSuccessStatusCode();

    return new OperationStatus();
</kode>

= ClientBase =
ClientBase for
* GetById
* GetAll
* Create
* Update
* Delete

<filebox fn='ItemClient.cs'>
public class ItemClient :
    ClientBaseWithGetAll<ItemResponse, CreateUpdateItemQuery>, IItemClient
{
    protected override string Path => "item";

    public ItemClient(HttpClient httpClient)
        : base(httpClient)
    { }
}
</filebox>

<filebox fn='IItemClient.cs'>
public interface IItemClient :
    IClientBaseWithGetAll<ItemResponse, CreateUpdateItemQuery>
{ }
</filebox>

<filebox fn='ClientBase.cs' collapsed>
public abstract class ClientBase<TResponse, TCreateUpdateQuery> :
    IClientBase<TResponse, TCreateUpdateQuery>
{
    protected static IEnumerable<MediaTypeFormatter> problemJsonMediaTypeFormatters
        => new MediaTypeFormatter[1] { new ProblemJsonMediaTypeFormatter() };

    protected abstract string Path { get; }
    protected HttpClient HttpClient { get; }

    protected ClientBase(HttpClient httpClient)
    {
        HttpClient = httpClient;
    }

    public async Task<OperationResult<TResponse>> GetByIdAsync(
        int id,
        CancellationToken cancellationToken)
    {
        var uri = new Uri($"{Path}/{id}", UriKind.Relative);

        var response = await HttpClient.GetAsync(uri, cancellationToken);
        if (response.StatusCode == HttpStatusCode.NotFound)
        {
            return new OperationResult<TResponse>($"{typeof(TResponse)} {id} has not been found.");
        }

        response.EnsureSuccessStatusCode();

        var content = await response.Content.ReadAsAsync<TResponse>(cancellationToken);

        return new OperationResult<TResponse>(content);
    }

    public async Task<OperationStatus> DeleteAsync(int id, CancellationToken cancellationToken)
    {
        var uri = new Uri($"{Path}/{id}", UriKind.Relative);

        var response = await HttpClient.DeleteAsync(uri, cancellationToken);

        if (response.StatusCode == HttpStatusCode.NotFound)
        {
            return new OperationStatus($"{typeof(TResponse)} {id} has not been found.");
        }

        if (response.StatusCode == HttpStatusCode.InternalServerError)
        {
            var problemDetails = await response.Content.ReadAsAsync<ProblemDetails>(
                problemJsonMediaTypeFormatters, cancellationToken);

            var errorMessage = problemDetails is null || string.IsNullOrEmpty(problemDetails.Detail)
                ? "Unable to read the ProblemDetails error message"
                : problemDetails.Detail.Replace(" See the inner exception for details.", string.Empty);

            return new OperationStatus(errorMessage);
        }

        response.EnsureSuccessStatusCode();

        return new OperationStatus();
    }

    public async Task<OperationStatus> CreateAsync(
        TCreateUpdateQuery query,
        CancellationToken cancellationToken)
    {
        ArgumentNullException.ThrowIfNull(query);

        var uri = new Uri(Path, UriKind.Relative);
        var queryJson = new StringContent(JsonSerializer.Serialize(query), Encoding.UTF8, "application/json");

        var response = await HttpClient.PostAsync(uri, queryJson, cancellationToken);
        if (response.StatusCode == HttpStatusCode.BadRequest)
        {
            var validationProblemDetails =
                await response.Content.ReadAsAsync<ValidationProblemDetails>(
                    problemJsonMediaTypeFormatters, cancellationToken);

            return validationProblemDetails is null
                ? throw new InvalidDataException($"{nameof(validationProblemDetails)} is null")
                : new OperationStatus(validationProblemDetails.Errors);
        }

        response.EnsureSuccessStatusCode();

        return new OperationStatus();
    }

    public async Task<OperationStatus> UpdateAsync(
        int id,
        TCreateUpdateQuery query,
        CancellationToken cancellationToken)
    {
        ArgumentNullException.ThrowIfNull(query);

        var uri = new Uri($"{Path}/{id}", UriKind.Relative);
        var queryJson = new StringContent(JsonSerializer.Serialize(query), Encoding.UTF8, "application/json");

        var response = await HttpClient.PutAsync(uri, queryJson, cancellationToken);
        if (response.StatusCode == HttpStatusCode.BadRequest)
        {
            var validationProblemDetails =
                await response.Content.ReadAsAsync<ValidationProblemDetails>(
                    problemJsonMediaTypeFormatters, cancellationToken);

            return validationProblemDetails is null
                ? throw new InvalidDataException($"{nameof(validationProblemDetails)} is null")
                : new OperationStatus(validationProblemDetails.Errors);
        }

        if (response.StatusCode == HttpStatusCode.NotFound)
        {
            return new OperationStatus($"{typeof(TResponse)} {id} has not been found.");
        }

        response.EnsureSuccessStatusCode();

        return new OperationStatus();
    }
}
</filebox>

<filebox fn='IClientBase.cs' collapsed>
public interface IClientBase<TResponse, TCreateUpdateQuery>
{
    Task<OperationResult<TResponse>> GetByIdAsync(int id, CancellationToken cancellationToken);
    Task<OperationStatus> DeleteAsync(int id, CancellationToken cancellationToken);

    Task<OperationStatus> CreateAsync(
        TCreateUpdateQuery query,
        CancellationToken cancellationToken);

    Task<OperationStatus> UpdateAsync(
        int id,
        TCreateUpdateQuery query,
        CancellationToken cancellationToken);
}
</filebox>

<filebox fn='ClientBaseWithGetAll.cs' collapsed>
public abstract class ClientBaseWithGetAll<TResponse, TCreateUpdateQuery> :
    ClientBase<TResponse, TCreateUpdateQuery>
{
    protected ClientBaseWithGetAll(HttpClient httpClient)
        : base(httpClient)
    { }

    public async Task<IReadOnlyCollection<TResponse>> GetAllAsync(
        CancellationToken cancellationToken)
    {
        var uri = new Uri(Path, UriKind.Relative);

        var response = await HttpClient.GetAsync(uri, cancellationToken);
        response.EnsureSuccessStatusCode();

        var content = await response.Content
            .ReadAsAsync<IReadOnlyCollection<TResponse>>(cancellationToken);

        return content;
    }
}
</filebox>

<filebox fn='IClientBaseWithGetAll.cs' collapsed>
public interface IClientBaseWithGetAll<TResponse, TCreateUpdateQuery> :
    IClientBase<TResponse, TCreateUpdateQuery>
{
    Task<IReadOnlyCollection<TResponse>> GetAllAsync(CancellationToken cancellationToken);
}
</filebox>

= Query Strings =
Url: {{boxx|1=http://localhost:80/api/items?ids=1,2&retrieveDeleted=true}}

<filebox fn='ItemClient.cs'>
var ids = new[] { 1, 2 };
var retrieveDeleted = true;

var queryBuilder = new QueryBuilder();
queryBuilder.Add(nameof(ids), string.Join(",", ids));
queryBuilder.Add(nameof(retrieveDeleted), retrieveDeleted.ToString());

var uri = new Uri($"{Path}{queryBuilder.ToQueryString()}", UriKind.Relative);

var response = await this.httpClient.GetAsync(uri);
</filebox>

<filebox fn='ItemController.cs'>
[HttpGet]
public IActionResult Get([FromQuery] IReadOnlyCollection<int> ids, [FromQuery] bool retrieveDeleted = false)
{ }
// FromQuery is required for IReadOnlyCollection<int> to avoid having 415 Unsupported Media Type
</filebox>

= Pagination =
<filebox fn='ItemQuery.cs'>
public class ItemQuery
{
    public string Name { get; set; }
    public int PageIndex { get; set; }
    public int PageSize { get; set; }
}
</filebox>

<filebox fn='ItemClient.cs'>
public async Task<IReadOnlyCollection<ItemDto>> GetAsync()
{
    var query = new ItemQuery {
        ProfileName = string.Empty,
        PageIndex = 0,
        PageSize = 10
    };

    var uri = new Uri($"{Path}{query.ToQueryString()}", UriKind.Relative);
</filebox>

<filebox fn='ItemQueryExtension.cs'>
public static QueryString ToQueryString(this ItemQuery itemQuery)
{
    var queryBuilder = new QueryBuilder();
    queryBuilder.Add(nameof(itemQuery.ProfileName), itemQuery.Name);
    queryBuilder.Add(nameof(itemQuery.PageIndex), itemQuery.PageIndex.ToString());
    queryBuilder.Add(nameof(itemQuery.PageSize), itemQuery.PageSize.ToString());

    return queryBuilder.ToQueryString();
}
</filebox>

= [https://www.devtrends.co.uk/blog/handling-errors-in-asp.net-core-web-api UseStatusCodePagesWithReExecute] =
<filebox fn='Startup.cs'>
public void Configure(IApplicationBuilder app, IHostingEnvironment env)
{
    app.UseStatusCodePagesWithReExecute("/error/{0}");
    app.UseExceptionHandler("/error/500");

    app.UseMvc();
</filebox>

<kode lang='cs'>
[HttpGet("/error/{code:int}")]
public string Error(int code)
{
    return $"Error: {code}";
}
</kode>

= Action Filter =
<filebox fn='UpdateMyClassFilter.cs'>
public class UpdateMyClassFilter : IActionFilter
{
    public void OnActionExecuting(ActionExecutingContext context)
    {
        if (context.ActionArguments.Values.FirstOrDefault(x => x is MyClass) is MyClass myClass)
        {
            // do modification on myClass
        }
    }

    public void OnActionExecuted(ActionExecutedContext context) { }
}
</filebox>

<filebox fn='EmptyResultTo204Filter.cs' collapsed>
public class EmptyResultTo204Filter : IActionFilter
{
    public void OnActionExecuting(ActionExecutingContext context)
    { }

    public void OnActionExecuted(ActionExecutedContext context)
    {
        if (context.Result is EmptyResult)
            context.Result = new StatusCodeResult(StatusCodes.Status204NoContent);
    }
}
</filebox>

<filebox fn='Program.cs'>
builder.Services
    .AddControllers(x =>
    {
        x.Filters.Add<MyFilter>();
    });
</filebox>

= Middleware =
<filebox fn='EnsureNoContentMiddleware.cs'>
/// <summary>
/// A middleware to change the Status Code to 204 when it is equal to 200 and there is no content. 
/// </summary>
public class EnsureNoContentMiddleware(RequestDelegate next)
{
    public async Task InvokeAsync(HttpContext context)
    {
        // Call the next middleware in the pipeline
        await next(context);

        // If the response has no content and no explicit status code is set, default to 204 No Content
        if (context.Response.StatusCode == StatusCodes.Status200OK
            && context.Response.ContentLength == null
            && !context.Response.HasStarted)
        {
            context.Response.StatusCode = StatusCodes.Status204NoContent;
        }
    }
}
</filebox>

<filebox fn='Program.cs'>
app.UseMiddleware<EnsureNoContentMiddleware>();
</filebox>

= [https://github.com/gnaeus/OperationResult The Operation Result Pattern] =
<filebox fn='OperationResult.cs'>
public sealed class OperationResult<TResult, TError>
{
    public TResult Result { get; }
    public TError Error { get; }
    public bool Success => Error == null;

    public OperationResult(TResult result)
    {
        Result = result;
    }

    public OperationResult(TError error)
    {
        Error = error;
    }
}
</filebox>

<kode lang='csharp'>
OperationResult<MyDto, MyError> result;

if (/*...*/)
{
    result = new OperationResult<MyDto, MyError>(myError);
}
else
{
    result = new OperationResult<MyDto, MyError>(myDto);
}

return result;
</kode>

= JSON name mapping =
<kode lang='cs'>
[JsonPropertyName("otherName")]
public string Property1 { get; set; }
</kode>

= [https://docs.microsoft.com/en-us/dotnet/standard/serialization/system-text-json-migrate-from-newtonsoft-how-to JSON serialization: Newtonsoft.Json vs System.Text.Json] =
By default {{boxx|.NET Core 3.0}} uses [[JSON_et_CSharp#System.Text.Json|System.Text.Json]].

== Use Newtonsoft.Json ==
<kode lang='bash'>
dotnet add package Microsoft.AspNetCore.Mvc.NewtonsoftJson
</kode>
<filebox fn='Startup.cs'>
public void ConfigureServices(IServiceCollection services)
{
    services.AddControllers();
            .AddNewtonsoftJson();
</filebox>

= [https://docs.microsoft.com/en-us/aspnet/core/mvc/models/model-binding?view=aspnetcore-3.1 Model Binding] =
* [https://docs.microsoft.com/en-us/aspnet/core/mvc/advanced/custom-model-binding?view=aspnetcore-3.1 Custom Model Binding]
* [https://stackoverflow.com/questions/9584573/model-binding-comma-separated-query-string-parameter CommaSeparatedModelBinder]

<filebox fn='Program.cs'>
builder.Services.AddControllers(options =>
{
    options.ModelBinderProviders.Insert(0, new CommaSeparatedModelBinderProvider());
});
</filebox>

<filebox fn='CommaSeparatedModelBinderProvider.cs'>
public class CommaSeparatedModelBinderProvider : IModelBinderProvider
{
    public IModelBinder? GetBinder(ModelBinderProviderContext context)
    {
        ArgumentNullException.ThrowIfNull(context);

        if (context.Metadata.ModelType.GetInterface(nameof(IEnumerable)) != null
            && context.Metadata.ModelType != typeof(string))
        {
            return new BinderTypeModelBinder(typeof(CommaSeparatedModelBinder));
        }

        return null;
    }
}
</filebox>

<filebox fn='CommaSeparatedModelBinder.cs' collapsed>
public class CommaSeparatedModelBinder : IModelBinder
{
    private static readonly MethodInfo ToArrayMethod = typeof(Enumerable).GetMethod("ToArray")!;

    public Task BindModelAsync(ModelBindingContext bindingContext)
    {
        ArgumentNullException.ThrowIfNull(bindingContext);

        var modelType = bindingContext.ModelType;
        var modelName = bindingContext.ModelName;

        var valueType = modelType.GetElementType() ?? modelType.GetGenericArguments().FirstOrDefault();

        if (modelType.GetInterface(nameof(IEnumerable)) != null
            && valueType != null
            && valueType.GetInterface(nameof(IConvertible)) != null)
        {
            var valueProviderResult = bindingContext.ValueProvider.GetValue(modelName);

            if (valueProviderResult == ValueProviderResult.None)
            {
                return Task.CompletedTask;
            }

            bindingContext.ModelState.SetModelValue(modelName, valueProviderResult);

            var value = valueProviderResult.FirstValue;

            // Check if the argument value is null or empty
            if (string.IsNullOrEmpty(value))
            {
                return Task.CompletedTask;
            }

            var list = (IList?)Activator.CreateInstance(typeof(List<>).MakeGenericType(valueType));
            if (list is not null)
            {
                foreach (var splitValue in value.Split(commaSeparator))
                {
                    if (!string.IsNullOrWhiteSpace(splitValue))
                    {
                        list.Add(Convert.ChangeType(splitValue, valueType));
                    }
                }
            }

            var model = modelType.IsArray
                ? ToArrayMethod.MakeGenericMethod(valueType).Invoke(this, new[] { list })
                : list;

            bindingContext.Result = ModelBindingResult.Success(model);
        }

        return Task.CompletedTask;
    }
}
</filebox>

= [https://brokul.dev/sending-files-and-additional-data-using-httpclient-in-net-core Handle files] =
<filebox fn='FileClient.cs'>
await using var stream = System.IO.File.OpenRead("/path/MyFile.txt");
using var content = new MultipartFormDataContent
{
    { new StreamContent(stream), "file", "MyFile.txt" }
};

var response = await HttpClient.PostAsync(uri, content, cancellationToken);
</filebox>

<filebox fn='FileController.cs'>
[HttpPost]
public async Task<IActionResult> ImportAsync(
    [FromForm] IFormFile file,
    CancellationToken cancellationToken)
{
    using var memoryStream = new MemoryStream();
    await file.CopyToAsync(memoryStream, cancellationToken);

    byte[] b = memoryStream.ToArray();
}
</filebox>

= Log =
Add trace level for HttpClient, so you will get url and headers.
<filebox fn='appsettings.json'>
{
  "Logging": {
    "LogLevel": {
      "System.Net.Http.HttpClient": "Trace"
    }
  }
}
</filebox>

= [https://learn.microsoft.com/en-us/aspnet/core/performance/timeouts?view=aspnetcore-8.0 Request timeouts middleware] =
{{warn | To test in Visual Studio, run without the debugger.}}
<filebox fn='TaskController.cs'>
[ApiController]
[Route("[controller]")]
public class TaskController : ControllerBase
{
    [HttpPost("run")]
    [RequestTimeout(1000)] // 1000 ms
    [RequestTimeout("OneSecondPolicy")]
    public async Task RunTaskAsync(CancellationToken cancellationToken)
    {
        await Task.Delay(2000, cancellationToken);
    }
}
</filebox>

<filebox fn='Program.cs'>
builder.Services.AddRequestTimeouts();

builder.Services.AddRequestTimeouts(options => {
    options.DefaultPolicy = new RequestTimeoutPolicy { Timeout = TimeSpan.FromMilliseconds(1000) }; // default policy
    options.AddPolicy("OneSecondPolicy", TimeSpan.FromSeconds(1)); // named policy
});

app.UseRequestTimeouts();
</filebox>

= Erreurs =
== Unsupported Media Type with Postman ==
* Body → raw = json à envoyer
* Headers → Content-Type = application/json

== JsonSerializationException: Self referencing loop detected for property 'xxx' ... ==
<filebox fn='Startup.cs'>
services.AddMvc()
    // ignorer les références circulaires entre objets dans EF pour JSON
    .AddJsonOptions(opt => opt.SerializerSettings.ReferenceLoopHandling = ReferenceLoopHandling.Ignore);
</filebox>

== SqlException: Cannot insert explicit value for identity column in table 'xxx' when IDENTITY_INSERT is set to OFF ==
Impossible de sauvegarder les changements si une entité a été insérée avec une valeur ≠ {{boxx|default}} dans une propriété bindée avec une colonne {{boxx|Identity}}.<br />
Solution: forcer la valeur de cette propriété a {{boxx|default}}. La bdd mettra la valeur de la propriété a jour après avoir inséré l'entité.