Voir la source de Asp.net web api 2

[[Category:Web]]
[[Category:CSharp]]
= Liens =
* [https://www.strathweb.com/2013/10/asp-net-web-api-2-is-out-overview-of-features Nouveautés Web API 2]

= Web API vs MVC =
MVC est designé pour des applications web standard qui servent des pages HTML.<br />
Web API est designé pour des applications REST qui servent des objets sérialisés (JSON, XML).

= Routing =
<filebox fn='App_Start/WebApiConfig.cs'>
public static void Register(HttpConfiguration config)
{
    config.MapHttpAttributeRoutes();

    config.Routes.MapHttpRoute(
        name: "DefaultApi",
        routeTemplate: "api/{controller}/{action}",
        defaults: new { action = RouteParameter.Optional }
    );
</filebox>

<filebox fn='Global.asax.cs'>
public class WebApiApplication : HttpApplication
{
    protected void Application_Start()
    {
        GlobalConfiguration.Configure(WebApiConfig.Register);
    }
</filebox>

= [https://docs.microsoft.com/en-us/aspnet/web-api/overview/web-api-routing-and-actions/attribute-routing-in-web-api-2 Api Controller] =
== GET ==
<filebox fn='TestController.cs'>
[ApiVersion("1")]
[RoutePrefix("api/v{version:apiVersion}/test")]  // prefix pour toutes les méthodes du controller
public class TestController : ApiController
{
    // api/v1/test/result/{query}
    [HttpGet]  // force GET (optinal, GET by default)
    [Route("result/{query}")]  // route avec 1 paramètre
    public IHttpActionResult Get(string query) { }

    // api/v1/test/result/{query1}/{query2}
    [Route("result/{query1}/{query2}")]  // route avec 2 paramètres
    public IHttpActionResult Get(string query1, string query2) { }

    // api/v1/test/result/{query}/{optionalQuery?}
    [Route("result/{query}/{optionalQuery?}")]  // route avec 1 paramètre optionnel
    public IHttpActionResult Get(string query, string optionalQuery = null) { }

    // api/v1/test?query=text
    [Route("")]
    public IHttpActionResult Get([FromUri]string query) { }

    // api/v1/test/result?Prop1=1&Prop2=2
    [Route("")]
    public IHttpActionResult Get([FromUri]ComplexType ct)
    {
        return this.Ok(ct);
        // { "Prop1": 1, "Prop2": 2 }
    }

    // api/v1/test?cts[0].Prop1=1&cts[0].Prop2=2&cts[1].Prop1=3&cts[1].Prop2=4
    [Route("")]
    public IHttpActionResult Get([FromUri]IEnumerable<ComplexType> cts)
    {
        return this.Ok(cts);
        // [
        //     { "Prop1": 1, "Prop2": 2 },
        //     { "Prop1": 3, "Prop2": 4 }
        // ]
    }

    // api/other, use ~ to overwrite route prefix
    [Route("~/api/other")]
    public IHttpActionResult Get()
    { }
</filebox>
* [https://docs.microsoft.com/en-us/aspnet/web-api/overview/web-api-routing-and-actions/attribute-routing-in-web-api-2#optional Optional URI Parameters and Default Values]

== POST ==
<filebox fn='TestController.cs'>
// api/v1/test
// item is passed in Body
[Post]
[Route("")]
[ResponseType(typeof(Item))]
public IHttpActionResult Post(Item item)
{
    if (item == null || item.Id == 0 || string.IsNullOrWhiteSpace(item.Name))
    {
        return this.BadRequest();
    }

    if (items.Select(i => i.Id).Contains(item.Id))
    {
        return this.Conflict();
    }
    else
    {
        return this.Created(
            this.Request.RequestUri + $"?id={item.Id}",
            item);
    }
</filebox>

= Content Negociation =
Permet de spécifier sous quelle forme on souhaite la réponse.<br />
Le HTTP Header {{boxx|Accept}} permet de spécifier le format attendu.
<kode lang='bash'>
curl http://localhost:111/api/values -H "Accept: application/xml"
</kode>
{{info | L'extension pour Firefox {{boxx|RESTED}} permet de tester les requêtes.}}
<filebox fn='Global.asax.cs'>
protected void Application_Start()
{
    // return json by default (ajouter à la fin de la méthode)
    GlobalConfiguration.Configuration.Formatters.Clear();
    GlobalConfiguration.Configuration.Formatters.Add(new JsonMediaTypeFormatter());
</filebox>
<filebox fn='App_Start/WebApiConfig.cs'>
// return html by default instead of xml
config.Formatters.JsonFormatter.SupportedMediaTypes.Add(new MediaTypeHeaderValue("text/html"));
</filebox>

= Header =
<filebox fn='MyClient.cs'>
var request = new HttpRequestMessage(HttpMethod.Post, uri);
request.Headers.Add("HeaderName", headerValues);
request.Content = new StringContent(JsonConvert.SerializeObject(myObject));

var response = await this.httpClient.SendAsync(request, cancellationToken);
response.EnsureSuccessStatusCode();
</filebox>

<filebox fn='MyController.cs'>
[HttpGet]
[Route("route")]
[OpenApiTag(ControllerName)]
[SwaggerResponse(HttpStatusCode.OK, typeof(bool))]
[SwaggerResponse(HttpStatusCode.BadRequest, typeof(void))]
public async Task<IHttpActionResult> TestAsync([FromUri]SomeQuery someQuery, CancellationToken cancellationToken)
{
    if (this.Request.Headers.TryGetValues("HeaderName", out var headerValues))
    {}
</filebox>

= [[JSON_et_CSharp#JsonConverter|JsonConverter]] =
Allow to customize the generated JSON.
<filebox fn='ItemClient.cs'>
public async Task<IReadOnlyList<Item>> GetByIdsAsync(IReadOnlyCollection<int> ids, CancellationToken cancellationToken)
{
    var serializedIds = QueryStringSerializer.Serialize(ids, new ListJsonConverter());
    var uri = new Uri($"items?ids={serializedIds}", UriKind.Relative);
</filebox>

= [https://docs.microsoft.com/en-us/aspnet/core/mvc/advanced/custom-model-binding Model Binder] =
Permet de redéfinir la manière dont sera déserialisé l'url.
<filebox fn='TestController.cs'>
// association 1, fonctionne seulement si ComplexType est passé en paramètre
// api/test?ct=1,2
public IHttpActionResult Get([ModelBinder(typeof(ComplexTypeModelBinder))] ComplexType ct) { }

// api/test?cts[0]=1,2&cts[1]=3,4
public IHttpActionResult Get([FromUri] IEnumerable<ComplexType> cts) { }

// api/test?ComplexTypes[0]=1,2&ComplexTypes[1]=3,4
public IHttpActionResult Get([FromUri] Container container) { }
</filebox>

<filebox fn='ComplexTypeModelBinder.cs' lang='cs' collapsed>
using System.Web.Http.ModelBinding;

// System.Web.Http.ModelBinding.IModelBinder
public class ComplexTypeModelBinder : IModelBinder
{
    public bool BindModel(HttpActionContext actionContext, ModelBindingContext bindingContext)
    {
        if (bindingContext.ModelType != typeof(ComplexType))
        {
            return false;
        }

        ValueProviderResult val = bindingContext.ValueProvider.GetValue(bindingContext.ModelName);
        if (val == null)
        {
            return false;
        }

        // doesn't seem useful
        if (!(val.RawValue is string key))
        {
            bindingContext.ModelState.AddModelError(bindingContext.ModelName, "Wrong value type");
            return false;
        }

        var splittedValues = valueProviderResult.AttemptedValue.Split(',');
        if (splittedValues.Length != 2)
        {
            bindingContext.ModelState.AddModelError(bindingContext.ModelName,
                "Cannot convert value to ComplexType");
            return false;
        }

        var result = new ComplexType
        {
            Prop1 = int.Parse(values[0]),
            Prop2 = int.Parse(values[1])
        };
        bindingContext.Model = result;
        return true;
    }
}
</filebox>

<filebox fn='ComplexType.cs'>
// association 2, fonctionne si ComplexType est passé en paramètre mais aussi s'il est un sous-élément du paramètre
[ModelBinder(typeof(ComplexTypeModelBinder))]
public class ComplexType
{
    public int Prop1 { get; set; }
    public int Prop2 { get; set; }
}

public class Container
{
    public IEnumerable<ComplexType> ComplexTypes { get; set; }
}
</filebox>

<filebox fn='WebApiConfig.cs'>
public static void Register(HttpConfiguration config)
{
    // association 3, fonctionne seulement si ComplexType est passé en paramètre
    // la méthode du controller ne doit pas contenir FromUri
    config.ParameterBindingRules.Add(
      typeof(ComplexType),
      descriptor => descriptor.BindWithModelBinding(new ComplexTypeModelBinder()));

    // association 4, fonctionne si ComplexType est passé en paramètre mais aussi s'il est un sous-élément du paramètre
    // la méthode du controller doit contenir FromUri
    config.Services.Insert(typeof(ModelBinderProvider), 0, new ComplexTypeModelBinderProvider());
}
</filebox>

<filebox fn='ComplexTypeModelBinderProvider.cs' collapsed>
public sealed class ComplexTypeModelBinderProvider : ModelBinderProvider
{
    public override IModelBinder GetBinder(HttpConfiguration configuration, Type modelType)
    {
        return modelType == typeof(ComplexType) ? new ComplexTypeModelBinder() : null;
    }
}
</filebox>

= Documentation =
Project Properties → Build → Output → cocher XML Documentation file → {{boxx|App_Data\[ProjectName].xml}}
<filebox fn='Areas/HelpPage/App_Start/HelpPageConfig.cs'>
public static class HelpPageConfig
{
    public static void Register(HttpConfiguration config)
    {
        config.SetDocumentationProvider(new XmlDocumentationProvider(HttpContext.Current.Server.MapPath("~/App_Data/[ProjectName].xml")));
</filebox>

= Client =
== GET ==
<kode lang='cs'>
var httpClient = new HttpClient();

// demande explicitement du xml ("application/xml") ou du json ("application/json")
httpClient.DefaultRequestHeaders.Accept.Add(new MediaTypeWithQualityHeaderValue("application/xml"));

// requête en une ligne utilisant Result, ce qui brise l'async
string content = httpClient.GetAsync(url).Result.Content.ReadAsStringAsync().Result;

// requête en 2 temsp avec test du status code
HttpResponseMessage response = await httpClient.GetAsync(url);
if (response.IsSuccessStatusCode)
{
    // XML
    var doc = XDocument.Load(await response.Content.ReadAsStreamAsync());
    var ns = (XNamespace)"http://schemas.datacontract.org/2004/07/WebAPITest.Models";
    foreach (var name in doc.Descendants(ns + "Name"))
    {
        Console.WriteLine(name.Value);
    }

    // récupération du contenu comme un string
    string content = await response.Content.ReadAsStringAsync();
    // désérialisation du contenu
    // ReadAsAsync<T> nécessite l'assembly System.Net.Http.Formatting
    // disponible dans le paquet NuGet Microsoft.AspNet.WebApi.Client
    // et le using System.Net.Http;
    JObject content = await response.Content.ReadAsAsync<JObject>();
}
else
{
    // retourne un Task<T> avec un contenu null
    return await Task.FromResult<JObject>(null);
}
</kode>

<kode lang='xml'>
<ArrayOfPerson xmlns:i="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://schemas.datacontract.org/2004/07/WebAPITest.Models">
  <Person>
    <Name>John</Name>
  </Person>
  <Person>
    <Name>Billy</Name>
  </Person>
</ArrayOfPerson>
</kode>

== POST ==
<kode lang='cs'>
// content dans l'url
var content = new FormUrlEncodedContent(new[]
{
    new KeyValuePair<string, string>("clé", "valeur")
});

// content dans le body
var content = new StringContent(
    new JavaScriptSerializer().Serialize(myObject), 
    Encoding.UTF8, 
    "application/json");

HttpResponseMessage responseMessage = await httpClient.PostAsync(url, content);
string result = await responseMessage.Content.ReadAsStringAsync();
</kode>

== Token ==
<kode lang='cs'>
// GET
var request = new HttpRequestMessage(HttpMethod.Get, url);
request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", token);
// POST
var request = new HttpRequestMessage(HttpMethod.Post, url);
request.Headers.Authorization = new AuthenticationHeaderValue("Bearer", token);
request.Content = content;

HttpResponseMessage responseMessage = await httpClient.SendAsync(request);
string result = await responseMessage.Content.ReadAsStringAsync();
</kode>

= [https://docs.microsoft.com/en-us/aspnet/web-api/overview/error-handling/exception-handling HttpResponseException] =
{{info | By default, most exceptions are translated into an HTTP response with status code 500, Internal Server Error.}}
<kode lang='cs'>
// HttpResponseException permet de spécifier le code d'erreur, ici 404
throw new HttpResponseException(HttpStatusCode.NotFound);

// spécifie en plus le Content et la ReasonPhrase
var responseMessage = new HttpResponseMessage(HttpStatusCode.NotFound)
{
    Content = new StringContent("Error content."),
    ReasonPhrase = "Error reason."
}
throw new HttpResponseException(responseMessage);
</kode>

= Dependencies Injection =
* Install nuget packages: {{boxx|DryIoc}} {{boxx|DryIoc.WebApi}}
<filebox fn='Global.asax.cs'>
public class WebApiApplication : System.Web.HttpApplication
{
    protected void Application_Start()
    {
        GlobalConfiguration.Configure(DryIocConfig.Register);
</filebox>

<filebox fn='DryIocConfig.cs'>
public static void Register(HttpConfiguration config)
{
    var container = new Container();
    container.Register<IMyService, MyService>();
    container.WithWebApi(config);
}
</filebox>

= Loguer les exceptions non-gérées =
{{info | Nuget: {{boxx|Microsoft.AspNet.WebApi.Core}}}}
<filebox fn='App_Start\WebApiConfig.cs'>
public static class WebApiConfig
{
    public static void Register(HttpConfiguration config)
    {
        /* ... */
        // plusieurs ExceptionLogger peuvent être ajoutés, permet juste de loguer
        config.Services.Add(typeof(IExceptionLogger), new MyExceptionLogger());
        // un seul ExceptionHandler, permet de modifier la réponse
        config.Services.Replace(typeof(IExceptionHandler), new GlobalExceptionHandler());
</filebox>
<filebox fn='MyExceptionLogger.cs'>
public class MyExceptionLogger : ExceptionLogger
{
    public override void Log(ExceptionLoggerContext context)
    {
        // log it
        base.Log(context);
</filebox>
<filebox fn='GlobalExceptionHandler.cs'>
public class GlobalExceptionHandler : ExceptionHandler
{
    public override void Handle(ExceptionHandlerContext context)
    {
        // réécrit le message d'erreur
        context.Result = new TextErrorResult
        {
            RequestMessage = context.ExceptionContext.Request,
            Content = context.Exception.GetAllMessages()
        };

private class TextErrorResult : IHttpActionResult
{
    public HttpRequestMessage RequestMessage { get; set; }

    public string Content { get; set; }

    public Task<HttpResponseMessage> ExecuteAsync(CancellationToken cancellationToken)
    {
        var response = new HttpResponseMessage(HttpStatusCode.InternalServerError);
        response.Content = new StringContent(Content);
        response.RequestMessage = RequestMessage;
        return Task.FromResult(response);
</filebox>

= Authorize =
* [[ASP.NET_MVC#Authentication|ASP.NET MVC Authentication]]
{{info | Pour accéder à une méthode {{boxx|Authorize}}, il faut passer un [[Web_API#Token|token]] d'accès.}}
<filebox fn='MyController.cs'>
[Authorize]
[HttpGet]
[Route("userinfo")]
public string UserInfo()
{
    string name = ClaimsPrincipal.Current.FindFirst(ClaimTypes.Name).Value;
    string givenName = ClaimsPrincipal.Current.FindFirst(ClaimTypes.GivenName).Value;
    string surname = ClaimsPrincipal.Current.FindFirst(ClaimTypes.Surname).Value;
    string email = ClaimsPrincipal.Current.FindFirst(ClaimTypes.Email);
    string upn = ClaimsPrincipal.Current.FindFirst(ClaimTypes.Upn).Value; // user principal name
    string scope = ClaimsPrincipal.Current.FindFirst("http://schemas.microsoft.com/identity/claims/scope").Value;
    string objectId = ClaimsPrincipal.Current.FindFirst("http://schemas.microsoft.com/identity/claims/objectidentifier").Value;

    // using Microsoft.AspNet.Identity;
    // packaget NuGet Microsoft ASP.NET Identity Core
    string userId = User.Identity.GetUserId();
}
</filebox>

= [https://docs.microsoft.com/en-us/aspnet/web-api/overview/security/enabling-cross-origin-requests-in-web-api Cross-Origin Requests] =
Permet à d'autres sites d'appeler mon API Web, contournant ainsi la same-origin policy.

= [https://github.com/RicoSuter/NSwag/wiki/OwinGlobalAsax#integration Swagger / NSwag] =
Install Nuget packages: {{boxx|Microsoft.Owin.Host.SystemWeb}} {{boxx|NSwag.AspNet.Owin}}

<filebox fn='Global.asax.cs'>
protected void Application_Start()
{
    RouteTable.Routes.MapOwinPath("swagger", app =>
    {
        app.UseSwaggerReDoc(typeof(WebApiApplication).Assembly, s =>
        {
            s.GeneratorSettings.DefaultUrlTemplate = "api/{controller}/{id}";
            s.MiddlewareBasePath = "/swagger";
        });
    });
</filebox>

<filebox fn='Web.config' lang='xml'>
<configuration>
  <appSettings>
    <add key="owin:AutomaticAppStartup" value="false" />
  </appSettings>

  <system.webServer>
    <!-- choice 1: Pipe all request to the .NET pipeline -->
    <modules runAllManagedModulesForAllRequests="true" />

    <!-- choice 2: Pipe only the Swagger request to the specific middlewares -->
    <handlers>
      <add name="NSwag" path="swagger" verb="*" type="System.Web.Handlers.TransferRequestHandler" preCondition="integratedMode,runtimeVersionv4.0" />
    </handlers>
  </system.webServer>
</filebox>

Url: {{boxx|<nowiki>http://localhost:{port}/swagger</nowiki>}}

= Visual Studio et un projet Web API =
# New Project → ASP.NET Web Application → Template: Empty → cocher Web API
# Clique-droit sur le dossier {{boxx|Controllers}} → Add Controller → Web API 2 Controller - Empty

= Erreurs =
== [https://stackoverflow.com/questions/33681978/strings-sent-through-web-apis-gets-wrapped-in-quotes Les appels consécutifs à plusieurs Web API échappent plusieurs fois les caractères] ==
Les appels consécutifs à {{boxx|GetStringAsync}} échappent autant de fois les caractères.<br />
Utiliser plutôt {{boxx|GetAsync}}.
<kode lang='cs'>
// autre solution
string json = await httpClient.GetStringAsync(url);
HttpResponseMessage response = Request.CreateResponse(HttpStatusCode.OK);
response.Content = new StringContent(json, Encoding.UTF8, "application/json");
// retourner response au lieu de json
</kode>

== The file or directory does not exist on the server ==
Le verbe utilisé n'est pas autorisé sur le serveur. Changer la configuration du serveur.
<filebox fn='Documents\IISExpress\config\applicationhost.xml'>
<add 
  name="ExtensionlessUrl-Integrated-4.0" 
  path="*." verb="GET,HEAD,POST,DEBUG" 
  type="System.Web.Handlers.TransferRequestHandler" 
  preCondition="integratedMode,runtimeVersionv4.0" />
</filebox>
{{info | VS utilise {{boxx|[Dossier solution]\.vs\config\applicationhost.xml}} en surcharge du fichier de config global.}}