Update "Custom Model Binding" to 3.1. (dotnet#16424)

* 3.1 Sample.

* Updated links to 3.1 sample.

* Update custom-model-binding.md

Co-authored-by: Rick Anderson <[email protected]>

Author: serpent5

aspnetcore/mvc/advanced/custom-model-binding.md

@@ -3,18 +3,18 @@ title: Custom Model Binding in ASP.NET Core
 author: ardalis
 description: Learn how model binding allows controller actions to work directly with model types in ASP.NET Core.
 ms.author: riande
-ms.date: 01/01/2020
+ms.date: 01/06/2020
 uid: mvc/advanced/custom-model-binding
 ---
 # Custom Model Binding in ASP.NET Core
 
 ::: moniker range=">= aspnetcore-3.0"
 
-By [Steve Smith](https://ardalis.com/)
+By [Steve Smith](https://ardalis.com/) and [Kirk Larkin](https://twitter.com/serpent5)
 
 Model binding allows controller actions to work directly with model types (passed in as method arguments), rather than HTTP requests. Mapping between incoming request data and application models is handled by model binders. Developers can extend the built-in model binding functionality by implementing custom model binders (though typically, you don't need to write your own provider).
 
-[View or download sample code](https://github.com/aspnet/AspNetCore.Docs/tree/master/aspnetcore/mvc/advanced/custom-model-binding/) ([how to download](xref:index#how-to-download-a-sample))
+[View or download sample code](https://github.com/aspnet/AspNetCore.Docs/tree/master/aspnetcore/mvc/advanced/custom-model-binding/samples) ([how to download](xref:index#how-to-download-a-sample))
 
 ## Default model binder limitations
 
@@ -28,7 +28,7 @@ Before creating your own custom model binder, it's worth reviewing how existing
 
 ### Working with the ByteArrayModelBinder
 
-Base64-encoded strings can be used to represent binary data. For example, an image can be encoded as a string. The sample includes an image as a base64-encoded string in [Base64String.txt](https://github.com/aspnet/AspNetCore.Docs/blob/master/aspnetcore/mvc/advanced/custom-model-binding/samples/2.x/CustomModelBindingSample/Base64String.txt).
+Base64-encoded strings can be used to represent binary data. For example, an image can be encoded as a string. The sample includes an image as a base64-encoded string in [Base64String.txt](https://github.com/aspnet/AspNetCore.Docs/blob/master/aspnetcore/mvc/advanced/custom-model-binding/samples/3.x/CustomModelBindingSample/Base64String.txt).
 
 ASP.NET Core MVC can take a base64-encoded string and use a `ByteArrayModelBinder` to convert it into a byte array. The <xref:Microsoft.AspNetCore.Mvc.ModelBinding.Binders.ByteArrayModelBinderProvider> maps `byte[]` arguments to `ByteArrayModelBinder`:
 
@@ -42,7 +42,8 @@ public IModelBinder GetBinder(ModelBinderProviderContext context)
 
     if (context.Metadata.ModelType == typeof(byte[]))
     {
-        return new ByteArrayModelBinder();
+        var loggerFactory = context.Services.GetRequiredService<ILoggerFactory>();
+        return new ByteArrayModelBinder(loggerFactory);
     }
 
     return null;
@@ -53,15 +54,15 @@ When creating your own custom model binder, you can implement your own `IModelBi
 
 The following example shows how to use `ByteArrayModelBinder` to convert a base64-encoded string to a `byte[]` and save the result to a file:
 
-[!code-csharp[](custom-model-binding/samples/2.x/CustomModelBindingSample/Controllers/ImageController.cs?name=post1)]
+[!code-csharp[](custom-model-binding/samples/3.x/CustomModelBindingSample/Controllers/ImageController.cs?name=snippet_Post)]
 
 You can POST a base64-encoded string to this api method using a tool like [Postman](https://www.getpostman.com/):
 
 ![postman](custom-model-binding/images/postman.png "postman")
 
 As long as the binder can bind request data to appropriately named properties or arguments, model binding will succeed. The following example shows how to use `ByteArrayModelBinder` with a view model:
 
-[!code-csharp[](custom-model-binding/samples/2.x/CustomModelBindingSample/Controllers/ImageController.cs?name=post2&highlight=2)]
+[!code-csharp[](custom-model-binding/samples/3.x/CustomModelBindingSample/Controllers/ImageController.cs?name=snippet_SaveProfile&highlight=2)]
 
 ## Custom model binder sample
 
@@ -73,24 +74,24 @@ In this section we'll implement a custom model binder that:
 
 The following sample uses the `ModelBinder` attribute on the `Author` model:
 
-[!code-csharp[](custom-model-binding/samples/2.x/CustomModelBindingSample/Data/Author.cs?highlight=6)]
+[!code-csharp[](custom-model-binding/samples/3.x/CustomModelBindingSample/Data/Author.cs?highlight=6)]
 
 In the preceding code, the `ModelBinder` attribute specifies the type of `IModelBinder` that should be used to bind `Author` action parameters.
 
 The following `AuthorEntityBinder` class binds an `Author` parameter by fetching the entity from a data source using Entity Framework Core and an `authorId`:
 
-[!code-csharp[](custom-model-binding/samples/2.x/CustomModelBindingSample/Binders/AuthorEntityBinder.cs?name=demo)]
+[!code-csharp[](custom-model-binding/samples/3.x/CustomModelBindingSample/Binders/AuthorEntityBinder.cs?name=snippet_Class)]
 
 > [!NOTE]
 > The preceding `AuthorEntityBinder` class is intended to illustrate a custom model binder. The class isn't intended to illustrate best practices for a lookup scenario. For lookup, bind the `authorId` and query the database in an action method. This approach separates model binding failures from `NotFound` cases.
 
 The following code shows how to use the `AuthorEntityBinder` in an action method:
 
-[!code-csharp[](custom-model-binding/samples/2.x/CustomModelBindingSample/Controllers/BoundAuthorsController.cs?name=demo2&highlight=2)]
+[!code-csharp[](custom-model-binding/samples/3.x/CustomModelBindingSample/Controllers/BoundAuthorsController.cs?name=snippet_Get&highlight=2)]
 
 The `ModelBinder` attribute can be used to apply the `AuthorEntityBinder` to parameters that don't use default conventions:
 
-[!code-csharp[](custom-model-binding/samples/2.x/CustomModelBindingSample/Controllers/BoundAuthorsController.cs?name=demo1&highlight=2)]
+[!code-csharp[](custom-model-binding/samples/3.x/CustomModelBindingSample/Controllers/BoundAuthorsController.cs?name=snippet_GetById&highlight=2)]
 
 In this example, since the name of the argument isn't the default `authorId`, it's specified on the parameter using the `ModelBinder` attribute. Both the controller and action method are simplified compared to looking up the entity in the action method. The logic to fetch the author using Entity Framework Core is moved to the model binder. This can be a considerable simplification when you have several methods that bind to the `Author` model.
 
@@ -100,14 +101,14 @@ You can apply the `ModelBinder` attribute to individual model properties (such a
 
 Instead of applying an attribute, you can implement `IModelBinderProvider`. This is how the built-in framework binders are implemented. When you specify the type your binder operates on, you specify the type of argument it produces, **not** the input your binder accepts. The following binder provider works with the `AuthorEntityBinder`. When it's added to MVC's collection of providers, you don't need to use the `ModelBinder` attribute on `Author` or `Author`-typed parameters.
 
-[!code-csharp[](custom-model-binding/samples/2.x/CustomModelBindingSample/Binders/AuthorEntityBinderProvider.cs?highlight=17-20)]
+[!code-csharp[](custom-model-binding/samples/3.x/CustomModelBindingSample/Binders/AuthorEntityBinderProvider.cs?highlight=17-20)]
 
 > Note:
 > The preceding code returns a `BinderTypeModelBinder`. `BinderTypeModelBinder` acts as a factory for model binders and provides dependency injection (DI). The `AuthorEntityBinder` requires DI to access EF Core. Use `BinderTypeModelBinder` if your model binder requires services from DI.
 
 To use a custom model binder provider, add it in `ConfigureServices`:
 
-[!code-csharp[](custom-model-binding/samples/2.x/CustomModelBindingSample/Startup.cs?name=snippet_ConfigureServices&highlight=5-10)]
+[!code-csharp[](custom-model-binding/samples/3.x/CustomModelBindingSample/Startup.cs?name=snippet_ConfigureServices&highlight=5-8)]
 
 When evaluating model binders, the collection of providers is examined in order. The first provider that returns a binder is used. Adding your provider to the end of the collection may result in a built-in model binder being called before your custom binder has a chance. In this example, the custom provider is added to the beginning of the collection to ensure it's used for `Author` action arguments.
 
@@ -137,7 +138,7 @@ By [Steve Smith](https://ardalis.com/)
 
 Model binding allows controller actions to work directly with model types (passed in as method arguments), rather than HTTP requests. Mapping between incoming request data and application models is handled by model binders. Developers can extend the built-in model binding functionality by implementing custom model binders (though typically, you don't need to write your own provider).
 
-[View or download sample code](https://github.com/aspnet/AspNetCore.Docs/tree/master/aspnetcore/mvc/advanced/custom-model-binding/) ([how to download](xref:index#how-to-download-a-sample))
+[View or download sample code](https://github.com/aspnet/AspNetCore.Docs/tree/master/aspnetcore/mvc/advanced/custom-model-binding/samples) ([how to download](xref:index#how-to-download-a-sample))
 
 ## Default model binder limitations
 

aspnetcore/mvc/advanced/custom-model-binding/samples/3.x/CustomModelBindingSample/Base64String.txt

@@ -0,0 +1,62 @@
+using System;
+using System.Threading.Tasks;
+using CustomModelBindingSample.Data;
+using Microsoft.AspNetCore.Mvc.ModelBinding;
+
+namespace CustomModelBindingSample.Binders
+{
+    #region snippet_Class
+    public class AuthorEntityBinder : IModelBinder
+    {
+        private readonly AuthorContext _context;
+
+        public AuthorEntityBinder(AuthorContext context)
+        {
+            _context = context;
+        }
+
+        public Task BindModelAsync(ModelBindingContext bindingContext)
+        {
+            if (bindingContext == null)
+            {
+                throw new ArgumentNullException(nameof(bindingContext));
+            }
+
+            var modelName = bindingContext.ModelName;
+
+            // Try to fetch the value of the argument by name
+            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;
+            }
+
+            if (!int.TryParse(value, out var id))
+            {
+                // Non-integer arguments result in model state errors
+                bindingContext.ModelState.TryAddModelError(
+                    modelName, "Author Id must be an integer.");
+
+                return Task.CompletedTask;
+            }
+
+            // Model will be null if not found, including for
+            // out of range id values (0, -3, etc.)
+            var model = _context.Authors.Find(id);
+            bindingContext.Result = ModelBindingResult.Success(model);
+            return Task.CompletedTask;
+        }
+    }
+    #endregion
+}

aspnetcore/mvc/advanced/custom-model-binding/samples/3.x/CustomModelBindingSample/Binders/AuthorEntityBinder.cs

@@ -0,0 +1,25 @@
+using CustomModelBindingSample.Data;
+using Microsoft.AspNetCore.Mvc.ModelBinding;
+using Microsoft.AspNetCore.Mvc.ModelBinding.Binders;
+using System;
+
+namespace CustomModelBindingSample.Binders
+{
+    public class AuthorEntityBinderProvider : IModelBinderProvider
+    {
+        public IModelBinder GetBinder(ModelBinderProviderContext context)
+        {
+            if (context == null)
+            {
+                throw new ArgumentNullException(nameof(context));
+            }
+
+            if (context.Metadata.ModelType == typeof(Author))
+            {
+                return new BinderTypeModelBinder(typeof(AuthorEntityBinder));
+            }
+
+            return null;
+        }
+    }
+}

aspnetcore/mvc/advanced/custom-model-binding/samples/3.x/CustomModelBindingSample/Binders/AuthorEntityBinderProvider.cs

@@ -0,0 +1,30 @@
+using Microsoft.AspNetCore.Mvc;
+using CustomModelBindingSample.Data;
+
+namespace CustomModelBindingSample.Controllers
+{
+    [ApiController]
+    [Route("api/[controller]")]
+    public class AuthorsController : Controller
+    {
+        private readonly AuthorContext _context;
+
+        public AuthorsController(AuthorContext context)
+        {
+            _context = context;
+        }
+
+        [HttpGet("{id}")]
+        public IActionResult GetById(int id)
+        {
+            var author = _context.Authors.Find(id);
+
+            if (author == null)
+            {
+                return NotFound();
+            }
+
+            return Ok(author);
+        }
+    }
+}

aspnetcore/mvc/advanced/custom-model-binding/samples/3.x/CustomModelBindingSample/Controllers/AuthorsController.cs

@@ -0,0 +1,36 @@
+using Microsoft.AspNetCore.Mvc;
+using CustomModelBindingSample.Data;
+
+namespace CustomModelBindingSample.Controllers
+{
+    [ApiController]
+    [Route("api/[controller]")]
+    public class BoundAuthorsController : ControllerBase
+    {
+        #region snippet_GetById
+        [HttpGet("{id}")]
+        public IActionResult GetById([ModelBinder(Name = "id")] Author author)
+        {
+            if (author == null)
+            {
+                return NotFound();
+            }
+
+            return Ok(author);
+        }
+        #endregion
+
+        #region snippet_Get
+        [HttpGet("get/{authorId}")]
+        public IActionResult Get(Author author)
+        {
+            if (author == null)
+            {
+                return NotFound();
+            }
+
+            return Ok(author);
+        }
+        #endregion
+    }
+}

aspnetcore/mvc/advanced/custom-model-binding/samples/3.x/CustomModelBindingSample/Controllers/BoundAuthorsController.cs

@@ -0,0 +1,67 @@
+using System.IO;
+using Microsoft.AspNetCore.Mvc;
+using Microsoft.Extensions.Configuration;
+
+namespace CustomModelBindingSample.Controllers
+{
+
+    [ApiController]
+    [Route("api/[controller]")]
+    public class ImageController : ControllerBase
+    {
+        private readonly string _targetFilePath;
+
+        public ImageController(IConfiguration config)
+        {
+            _targetFilePath = config["StoredFilesPath"];
+        }
+
+        #region snippet_Post
+        [HttpPost]
+        public void Post([FromForm] byte[] file, string filename)
+        {
+            // Don't trust the file name sent by the client. Use
+            // Path.GetRandomFileName to generate a safe random
+            // file name. _targetFilePath receives a value
+            // from configuration (the appsettings.json file in
+            // the sample app).
+            var trustedFileName = Path.GetRandomFileName();
+            var filePath = Path.Combine(_targetFilePath, trustedFileName);
+
+            if (System.IO.File.Exists(filePath))
+            {
+                return;
+            }
+
+            System.IO.File.WriteAllBytes(filePath, file);
+        }
+        #endregion
+
+        #region snippet_SaveProfile
+        [HttpPost("Profile")]
+        public void SaveProfile([FromForm] ProfileViewModel model)
+        {
+            // Don't trust the file name sent by the client. Use
+            // Path.GetRandomFileName to generate a safe random
+            // file name. _targetFilePath receives a value
+            // from configuration (the appsettings.json file in
+            // the sample app).
+            var trustedFileName = Path.GetRandomFileName();
+            var filePath = Path.Combine(_targetFilePath, trustedFileName);
+
+            if (System.IO.File.Exists(filePath))
+            {
+                return;
+            }
+
+            System.IO.File.WriteAllBytes(filePath, model.File);
+        }
+
+        public class ProfileViewModel
+        {
+            public byte[] File { get; set; }
+            public string FileName { get; set; }
+        }
+        #endregion
+    }
+}

aspnetcore/mvc/advanced/custom-model-binding/samples/3.x/CustomModelBindingSample/Controllers/ImageController.cs

@@ -0,0 +1,8 @@
+<Project Sdk="Microsoft.NET.Sdk.Web">
+  <PropertyGroup>
+    <TargetFramework>netcoreapp3.1</TargetFramework>
+  </PropertyGroup>
+  <ItemGroup>
+    <PackageReference Include="Microsoft.EntityFrameworkCore.InMemory" Version="3.1.0" />
+  </ItemGroup>
+</Project>

aspnetcore/mvc/advanced/custom-model-binding/samples/3.x/CustomModelBindingSample/CustomModelBindingSample.csproj

@@ -0,0 +1,15 @@
+using CustomModelBindingSample.Binders;
+using Microsoft.AspNetCore.Mvc;
+
+namespace CustomModelBindingSample.Data
+{
+    [ModelBinder(BinderType = typeof(AuthorEntityBinder))]
+    public class Author
+    {
+        public int Id { get; set; }
+        public string Name { get; set; }
+        public string GitHub { get; set; }
+        public string Twitter { get; set; }
+        public string BlogUrl { get; set; }
+    }
+}

aspnetcore/mvc/advanced/custom-model-binding/samples/3.x/CustomModelBindingSample/Data/Author.cs

@@ -0,0 +1,12 @@
+using Microsoft.EntityFrameworkCore;
+
+namespace CustomModelBindingSample.Data
+{
+    public class AuthorContext : DbContext
+    {
+        public AuthorContext(DbContextOptions<AuthorContext> options)
+            : base(options) { }
+
+        public DbSet<Author> Authors { get; set; }
+    }
+}