From 3f8edf130a14d34024a42ebd678fa3f699ef5916 Mon Sep 17 00:00:00 2001 From: Mike Kistler Date: Tue, 29 Oct 2024 19:40:16 -0700 Subject: [PATCH] Add examples for attributes (#58196) * Add examples for a few Mvc attributes * Scope to parameter binding attributes. * Fixes from PR review --- src/Mvc/Mvc.Core/src/FromBodyAttribute.cs | 24 +++++++++++++++++++++ src/Mvc/Mvc.Core/src/FromFormAttribute.cs | 16 ++++++++++++++ src/Mvc/Mvc.Core/src/FromHeaderAttribute.cs | 15 +++++++++++++ src/Mvc/Mvc.Core/src/FromQueryAttribute.cs | 15 +++++++++++++ src/Mvc/Mvc.Core/src/FromRouteAttribute.cs | 14 ++++++++++++ 5 files changed, 84 insertions(+) diff --git a/src/Mvc/Mvc.Core/src/FromBodyAttribute.cs b/src/Mvc/Mvc.Core/src/FromBodyAttribute.cs index ca4b362eea92..809cd3969542 100644 --- a/src/Mvc/Mvc.Core/src/FromBodyAttribute.cs +++ b/src/Mvc/Mvc.Core/src/FromBodyAttribute.cs @@ -10,9 +10,33 @@ namespace Microsoft.AspNetCore.Mvc; /// Specifies that a parameter or property should be bound using the request body. /// /// +/// Binds a parameter or property to the request body. +/// /// By default, ASP.NET Core MVC delegates the responsibility of reading the body to an input formatter.
/// In the case of ASP.NET Core Minimal APIs, the body is deserialized by . +/// +/// For more information about parameter binding see +/// Parameter binding. /// +/// +/// In this example, the value of the 'name' field in the form-data request body is bound to the name parameter, +/// and the value of the 'age' field is bound to the age parameter. +/// +/// app.MapPost("/from-body", ([FromBody] Person person) => person); +/// +/// public record Person(string Name, int Age); +/// +/// +/// If the EmptyBodyBehavior is set to EmptyBodyBehavior.Allow in the FromBody attribute, +/// requests without a request body are allowed. +/// +/// app.MapPost("/allow-empty-body", +/// ( +/// [Description("An optional request body")] +/// [FromBody(EmptyBodyBehavior = EmptyBodyBehavior.Allow)] Body body +/// ) => +/// +/// [AttributeUsage(AttributeTargets.Parameter | AttributeTargets.Property, AllowMultiple = false, Inherited = true)] public class FromBodyAttribute : Attribute, IBindingSourceMetadata, IConfigureEmptyBodyBehavior, IFromBodyMetadata { diff --git a/src/Mvc/Mvc.Core/src/FromFormAttribute.cs b/src/Mvc/Mvc.Core/src/FromFormAttribute.cs index 3e1b705e35af..4f57878ffe0d 100644 --- a/src/Mvc/Mvc.Core/src/FromFormAttribute.cs +++ b/src/Mvc/Mvc.Core/src/FromFormAttribute.cs @@ -9,6 +9,22 @@ namespace Microsoft.AspNetCore.Mvc; /// /// Specifies that a parameter or property should be bound using form-data in the request body. /// +/// +/// Binds a parameter or property to a field in a form-data request body with the same name, +/// or the name specified in the property. +/// Form parameter names are matched case-insensitively. +/// +/// For more information about parameter binding see +/// Parameter binding. +/// +/// +/// In this example, the value of the 'name' field in the form-data request body is bound to the name parameter, +/// and the value of the 'age' field is bound to the age parameter. +/// +/// app.MapPost("/from-form", ([FromForm] string name, [FromForm] int age) +/// => new { Name = name, Age = age }); +/// +/// [AttributeUsage(AttributeTargets.Parameter | AttributeTargets.Property, AllowMultiple = false, Inherited = true)] public class FromFormAttribute : Attribute, IBindingSourceMetadata, IModelNameProvider, IFromFormMetadata { diff --git a/src/Mvc/Mvc.Core/src/FromHeaderAttribute.cs b/src/Mvc/Mvc.Core/src/FromHeaderAttribute.cs index d2209698cf83..f914ed495317 100644 --- a/src/Mvc/Mvc.Core/src/FromHeaderAttribute.cs +++ b/src/Mvc/Mvc.Core/src/FromHeaderAttribute.cs @@ -9,6 +9,21 @@ namespace Microsoft.AspNetCore.Mvc; /// /// Specifies that a parameter or property should be bound using the request headers. /// +/// +/// Binds a parameter or property to the value of the request header with the same name, +/// or the name specified in the property. +/// Note that HTTP header names are case-insensitive, so the header name is matched without regard to case. +/// +/// For more information about parameter binding see +/// Parameter binding. +/// +/// +/// In this example, the value of the 'User-Agent' header is bound to the parameter. +/// +/// app.MapGet("/user-agent", ([FromHeader(Name = "User-Agent")] string userAgent) +/// => userAgent); +/// +/// [AttributeUsage(AttributeTargets.Parameter | AttributeTargets.Property, AllowMultiple = false, Inherited = true)] public class FromHeaderAttribute : Attribute, IBindingSourceMetadata, IModelNameProvider, IFromHeaderMetadata { diff --git a/src/Mvc/Mvc.Core/src/FromQueryAttribute.cs b/src/Mvc/Mvc.Core/src/FromQueryAttribute.cs index 3f9727f344b4..f83238aff252 100644 --- a/src/Mvc/Mvc.Core/src/FromQueryAttribute.cs +++ b/src/Mvc/Mvc.Core/src/FromQueryAttribute.cs @@ -9,6 +9,21 @@ namespace Microsoft.AspNetCore.Mvc; /// /// Specifies that a parameter or property should be bound using the request query string. /// +/// +/// Binds a parameter or property to the value of query string parameter with the same name, +/// or the name specified in the property. +/// The query parameter name is matched case-insensitively. +/// +/// For more information about parameter binding see +/// Parameter binding. +/// +/// +/// In this example, the value of the 'User-Agent' header is bound to the parameter. +/// +/// app.MapGet("/version", ([FromQuery(Name = "api-version")] string apiVersion) +/// => apiVersion); +/// +/// [AttributeUsage(AttributeTargets.Parameter | AttributeTargets.Property, AllowMultiple = false, Inherited = true)] public class FromQueryAttribute : Attribute, IBindingSourceMetadata, IModelNameProvider, IFromQueryMetadata { diff --git a/src/Mvc/Mvc.Core/src/FromRouteAttribute.cs b/src/Mvc/Mvc.Core/src/FromRouteAttribute.cs index e3fee8160c31..6524c70af5ab 100644 --- a/src/Mvc/Mvc.Core/src/FromRouteAttribute.cs +++ b/src/Mvc/Mvc.Core/src/FromRouteAttribute.cs @@ -10,6 +10,20 @@ namespace Microsoft.AspNetCore.Mvc; /// /// Specifies that a parameter or property should be bound using route-data from the current request. /// +/// +/// Binds a parameter or property to the value of a route parameter with the same name, +/// or the name specified in the property. +/// The route parameter name is matched against parameter segments of the route pattern case-insensitively. +/// +/// For more information about parameter binding see +/// Parameter binding. +/// +/// +/// In this example, the value of the 'id' route parameter is bound to the parameter. +/// +/// app.MapGet("/from-route/{id}", ([FromRoute] string id) => id); +/// +/// [AttributeUsage(AttributeTargets.Parameter | AttributeTargets.Property, AllowMultiple = false, Inherited = true)] public class FromRouteAttribute : Attribute, IBindingSourceMetadata, IModelNameProvider, IFromRouteMetadata {