Skip to content

4. A view e seu modelo

Até aqui, as actions geraram suas próprias respostas. Em uma aplicação MVC, esse é o papel de uma view: um arquivo que descreve a página HTML, com marcadores para os dados que a action lhe passa — o modelo da view. O [ASP.NET Core MVC] usa o engine de views [Razor]: uma view é um arquivo [.cshtml], derivado de HTML, no qual se insere código [C#] precedido do caractere [@]. O [Razor] faz parte do framework: não há nada a instalar.

4.1. Exemplo 13: Uma primeira view

O arquivo [Program.cs]:

1
2
3
4
5
6
7
8
var builder = WebApplication.CreateBuilder(args);

// os serviços do MVC: controllers E views Razor
builder.Services.AddControllersWithViews();

var app = builder.Build();
app.MapControllers();
app.Run();
  • Linha 4: [AddControllersWithViews] substitui [AddControllers] dos exemplos anteriores. Ele adiciona os serviços de view aos serviços de controller: o engine [Razor], a busca de arquivos de view e os Tag Helpers (Exemplo 15).

O modelo da view é uma classe simples. O arquivo [Models/PageModel.cs]:

1
2
3
4
namespace Example13.Models;

// o view model: os dados que a action passa para a view
public record PageModel(string Title, string Message, string Time);
  • linha 4: um [record] é uma classe cujas propriedades são definidas pelo construtor; aqui, três strings: [Title], [Message] e [Time]. É uma maneira concisa de definir uma classe que apenas transporta dados.

O arquivo [Controllers/ViewsController.cs]:

using Example13.Models;
using Microsoft.AspNetCore.Mvc;

namespace Example13.Controllers;

public class ViewsController : Controller
{
    // View(model): a view que leva o nome da action (Views/Views/Index.cshtml)
    [HttpGet("/")]
    public IActionResult Index()
    {
        var model = new PageModel(
            "My first view",
            "This page was built by Razor, on the server.",
            DateTime.Now.ToString("HH:mm:ss"));
        return View(model);
    }

    // View(name, model): a view é escolhida pela action
    [HttpGet("hello/{name}")]
    public IActionResult Hello(string name)
    {
        if (name == "unknown")
        {
            Response.StatusCode = 404;
            return View("Unknown", name);
        }
        var model = new PageModel(
            $"Hello {name}",
            "This time, the action designated the view by its name.",
            DateTime.Now.ToString("HH:mm:ss"));
        return View("Index", model);
    }
}

Vamos comentar este código:

  • linha 6: o controller deriva da classe [Controller], e não de [ControllerBase]: [Controller] acrescenta a [ControllerBase] tudo o que se relaciona a views (métodos [View], [ViewData], [TempData] etc.);
  • linhas 12–15: a action gera o modelo da view: um título, uma mensagem e a hora atual;
  • linha 16: [View(model)] devolve um [ViewResult]: a action não gera mais a resposta; em vez disso, designa uma view e lhe passa um modelo. Se nenhum nome de view for especificado, usa-se a view com o mesmo nome da action: [Index];
  • linhas 23–26: quando a view depende da requisição, a action escolhe a view. Aqui, o nome [unknown] exibe a view [Unknown], com código de status 404. O modelo dessa view é uma simples string;
  • linha 32: a action [Hello] especifica explicitamente a view [Index] pelo nome: duas actions compartilham a mesma view, com modelos diferentes.

Onde o [ASP.NET Core] procura a view [Index] da action [ViewsController.Index]? Por convenção, em duas pastas, nesta ordem:

  • [Views/Views/Index.cshtml]: a pasta com o nome do controller (sem o sufixo [Controller]);
  • [Views/Shared/Index.cshtml]: a pasta que contém as views compartilhadas por todos os controllers (veja o Exemplo 15).

Se a view não for encontrada em nenhum lugar, uma exceção lista os caminhos que foram verificados. Os arquivos do projeto:

13-first-view/
├── Controllers/
│   └── ViewsController.cs
├── Models/
│   └── PageModel.cs
├── Views/
│   ├── Views/
│   │   ├── Index.cshtml
│   │   └── Unknown.cshtml
│   └── _ViewImports.cshtml
├── appsettings.json
├── Example13.csproj
└── Program.cs

O arquivo [Views/_ViewImports.cshtml]:

@* as diretivas "using" compartilhadas por todas as views da pasta Views *@
@using Example13.Models
  • Linha 1: [@* ... *@] é um comentário [Razor]: ele não aparece na página gerada (ao contrário de um comentário HTML [<!-- -->]);
  • Linha 2: as diretivas do arquivo [_ViewImports.cshtml] valem para todas as views de sua pasta e subpastas. [@using Example13.Models] permite escrever [PageModel] em vez de [Example13.Models.PageModel] nas views.

O arquivo [Views/Views/Index.cshtml]:

@* o tipo do modelo desta view *@
@model PageModel
<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>@Model.Title</title>
</head>
<body>
  <h1>@Model.Title</h1>
  <p>@Model.Message</p>
  <p>Page built at @Model.Time.</p>
</body>
</html>
  • linha 2: a diretiva [@model] declara o tipo do modelo da view. Na view, a propriedade [Model] passa então a ser do tipo [PageModel], e o compilador verifica se [Model.Title] existe;
  • Linhas 7–12: cada expressão [@Model.Title] é substituída pelo valor correspondente do modelo. O [Razor] reconhece sozinho o fim de uma expressão: em [@Model.Time.], o ponto é seguido de uma tag, portanto não é um acesso a propriedade.

Uma view é um arquivo [C#] disfarçado: quando o projeto é compilado ([dotnet build]), cada arquivo [.cshtml] é traduzido em uma classe [C#], compilada junto com o restante da aplicação. Um erro em uma view ([@Model.Titl]) é, portanto, relatado durante a compilação. O resultado, na URL http://localhost:5000/:

Image

O código-fonte da página recebida pelo navegador não contém mais nenhum vestígio de [Razor]:

curl http://localhost:5000/
<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>My first view</title>
</head>
<body>
  <h1>My first view</h1>
  <p>This page was built by Razor, on the server.</p>
  <p>Page built at 12:12:36.</p>
</body>
</html>

Observe que caracteres acentuados inseridos por uma expressão [@] seriam codificados (esta página não contém nenhum): um título em francês como [Ma première vue] seria enviado como [Ma premi&#xE8;re vue], sendo [&#xE8;] o código do caractere [è], ao passo que um texto acentuado digitado diretamente na view permaneceria inalterado. O navegador exibe ambos corretamente, mas o código HTML fica difícil de ler. Veremos no Exemplo 15 como evitar isso. A URL http://localhost:5000/hello/martin exibe a mesma view com um modelo diferente:

Image

e http://localhost:5000/hello/unknown exibe uma view diferente:

curl -i http://localhost:5000/hello/unknown
HTTP/1.1 404 Not Found
Content-Type: text/html; charset=utf-8

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Unknown</title>
</head>
<body>
  <h1>Nobody is called [unknown] here.</h1>
</body>
</html>

O arquivo [Views/Views/Unknown.cshtml]:

@* o modelo desta view é uma simples string: o nome solicitado *@
@model string
<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Unknown</title>
</head>
<body>
  <h1>Nobody is called [@Model] here.</h1>
</body>
</html>
  • linha 2: o modelo dessa view é uma string;
  • linha 10: [@Model] é a própria string.

4.2. Exemplo 14: A linguagem Razor

O [Razor] não é uma linguagem de template “sem lógica” como o [Handlebars]: é possível escrever código [C#] dentro de uma view (condições, laços, variáveis, chamadas de método). Essa liberdade exige disciplina: a view deve servir apenas à formatação; cálculos e decisões pertencem à action e aos serviços. O Exemplo 14 apresenta uma visão geral da sintaxe. O modelo, arquivo [Models/BasicsModel.cs]:

namespace Example14.Models;

public record Product(string Name, decimal Price, bool InStock);

public record Address(string Street, string City);

public class BasicsModel
{
    public string Title { get; set; } = "";
    public string Name { get; set; } = "";
    public string? Nickname { get; set; }
    public string Html { get; set; } = "";
    public bool LoggedIn { get; set; }
    public string Currency { get; set; } = "";
    public List<Product> Products { get; set; } = [];
    public List<Product> Cart { get; set; } = [];
    public Address Address { get; set; } = new("", "");
}

O arquivo [Controllers/BasicsController.cs]:

using Example14.Models;
using Microsoft.AspNetCore.Mvc;

namespace Example14.Controllers;

public class BasicsController : Controller
{
    [HttpGet("/")]
    public IActionResult Index()
    {
        var model = new BasicsModel
        {
            Title = "Razor basics",
            Name = "Martin",
            Nickname = null,
            Html = "<b>this is HTML</b>",
            LoggedIn = true,
            Currency = "€",
            Products =
            [
                new Product("Keyboard", 25m, true),
                new Product("Mouse", 12.5m, false),
                new Product("Screen", 149m, true),
            ],
            Cart = [],
            Address = new Address("12 rue des Lilas", "Angers"),
        };
        return View(model);
    }
}
  • Linhas 11–26: a action preenche o modelo: algumas strings, um booleano, uma lista de três produtos, um carrinho de compras vazio e um endereço. [Nickname] é intencionalmente igual a [null].

A view, arquivo [Views/Basics/Index.cshtml]:

@model BasicsModel
@* um bloco de código C#: não produz nada na página *@
@{
    var total = Model.Products.Sum(p => p.Price);
    var count = Model.Products.Count;
}
<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>@Model.Title</title>
</head>
<body>
  <h1>@Model.Title</h1>
  @* 1. exibe um valor do modelo; um valor null não exibe nada *@
  <p>1. Name: @Model.Name - nickname: [@Model.Nickname]</p>
  @* 2. @ escapa o HTML, @Html.Raw o insere como está *@
  <p>2a. @Model.Html</p>
  <p>2b. @Html.Raw(Model.Html)</p>
  @* 3. uma condição *@
  @if (Model.LoggedIn)
  {
    <p>3. You are logged in.</p>
  }
  else
  {
    <p>3. You are not logged in.</p>
  }
  @* 4. um laço; as variáveis do laço são variáveis C# *@
  <p>4. Our products:</p>
  <ul>
    @for (var i = 0; i < Model.Products.Count; i++)
    {
      var product = Model.Products[i];
      <li>no. @i: @product.Name, @product.Price @Model.Currency
        @(product.InStock ? "(in stock)" : "(sold out)")
        @if (i == 0) { <text>- the first one</text> }
        @if (i == Model.Products.Count - 1) { @:- the last one, seen by @Model.Name
        }
      </li>
    }
  </ul>
  @* 5. a lista vazia *@
  <p>5. Your cart:
    @if (Model.Cart.Count == 0)
    {
      <text>it is empty.</text>
    }
    else
    {
      foreach (var p in Model.Cart) { <span>@p.Name</span> }
    }
  </p>
  @* 6. uma expressão explícita @( ... ), e as variáveis do bloco @{ } *@
  <p>6. @count products, for a total of @(total) @Model.Currency; average price: @((total / count).ToString("0.00")) @Model.Currency</p>
  <p>7. Address: @Model.Address.Street, @Model.Address.City.ToUpper()</p>
  <p>8. An email address: contact@example.com</p>
</body>
</html>

Vamos comentar este código:

  • Linhas 2–5: um bloco de código chamado [@{ ... }] contém instruções [C#]. Ele não produz nada na página. As variáveis que declara ([total], [count]) podem ser usadas mais adiante na view;
  • linha 16: um valor [null] ([@Model.Nickname]) não exibe nada, sem erro;
  • Linhas 18–19: uma expressão [@...] faz o escape dos caracteres especiais do HTML ([<] torna-se [&lt;]...): o texto é exibido tal como está. [@Html.Raw(...)] o insere sem escape: ele é interpretado como HTML. [Html.Raw] só deve ser usado para HTML gerado pela aplicação, nunca para dados digitados por um usuário: o usuário poderia injetar HTML, ou até mesmo [JavaScript], na página (um ataque conhecido como [XSS], [cross-site scripting]);
  • Linhas 21–27: uma condição. Depois de [@if (...)], o conteúdo entre chaves é HTML: o [Razor] reconhece o início de uma tag e volta ao modo HTML. Retornamos ao [C#] por meio de [@];
  • linhas 32–40: um laço [for] [C#]. [var product = ...] é uma instrução [C#], [<li>] é HTML: o [Razor] alterna entre os dois sem nenhum marcador específico;
  • Linha 36: uma expressão explícita [@( ... )]. Os parênteses são obrigatórios sempre que a expressão contém espaços ou operadores (neste caso, o operador condicional [? :]);
  • linha 37: para escrever texto não formatado dentro de um bloco [C#], coloque-o na tag especial [<text>], que não aparece na página;
  • linha 38: [@:] faz o mesmo para o restante da linha;
  • linhas 45–51: uma lista vazia é simplesmente [if]. No bloco [else], já em modo [C#], [foreach] é escrito sem [@];
  • linha 55: as variáveis do bloco [@{ }] e expressões explícitas, incluindo uma chamada de método: [ToString("0.00")] formata um número com duas casas decimais;
  • linha 56: um caminho com pontos [@Model.Address.Street] e uma chamada de método [ToUpper()];
  • linha 57: [Razor] reconhece que um [@] colocado entre dois caracteres alfanuméricos não é código: [contact@example.com] é um endereço de e-mail. Para escrever um [@] que seria ambíguo, ele é duplicado: [@@].

O resultado, na URL http://localhost:5000/:

Image

O código HTML produzido:

curl http://localhost:5000/
<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Razor basics</title>
</head>
<body>
  <h1>Razor basics</h1>
  <p>1. Name: Martin - nickname: []</p>
  <p>2a. &lt;b&gt;this is HTML&lt;/b&gt;</p>
  <p>2b. <b>this is HTML</b></p>
    <p>3. You are logged in.</p>
  <p>4. Our products:</p>
  <ul>
      <li>no. 0: Keyboard, 25 &#x20AC;
        (in stock)
- the first one      </li>
      <li>no. 1: Mouse, 12.5 &#x20AC;
        (sold out)
      </li>
      <li>no. 2: Screen, 149 &#x20AC;
        (in stock)
 - the last one, seen by Martin
      </li>
  </ul>
  <p>5. Your cart:
it is empty.  </p>
  <p>6. 3 products, for a total of 186.5 &#x20AC;; average price: 62.17 &#x20AC;</p>
  <p>7. Address: 12 rue des Lilas, ANGERS</p>
  <p>8. An email address: contact@example.com</p>
</body>
</html>

Observe os espaços e as linhas em branco deixados pelas instruções [C#]: eles não têm efeito na exibição. Vemos também a codificação dos caracteres acentuados provenientes de expressões ([&#x20AC;] para [€]), que é corrigida no exemplo seguinte.

4.3. Exemplo 15: template, views parciais, arquivos estáticos

As páginas de um site compartilham um template comum (cabeçalho, barra de navegação, rodapé). O [Razor] chama esse template de “layout”: cada view é inserida nele. Os componentes reutilizáveis de uma página são as views parciais. Por fim, as páginas precisam de arquivos estáticos (folhas de estilo, imagens, scripts), que são servidos como estão, sem passar por um controller. Os arquivos do exemplo:

15-layout/
├── Controllers/
│   └── PagesController.cs
├── Views/
│   ├── Pages/
│   │   ├── Home.cshtml
│   │   ├── Raw.cshtml
│   │   └── Team.cshtml
│   ├── Shared/
│   │   ├── _Card.cshtml
│   │   ├── _Layout.cshtml
│   │   └── _Navbar.cshtml
│   ├── _ViewImports.cshtml
│   └── _ViewStart.cshtml
├── wwwroot/
│   └── css/
│       └── styles.css
├── appsettings.json
├── Example15.csproj
└── Program.cs

O arquivo [Program.cs]:

using System.Text.Encodings.Web;
using System.Text.Unicode;
using Microsoft.Extensions.FileProviders;

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddControllersWithViews();
// o Razor escreve os caracteres acentuados como estão (e não "&#xE9;");
// < > & " ' continuam escapados
builder.Services.AddSingleton(HtmlEncoder.Create(UnicodeRanges.All));

var app = builder.Build();

// 1. os arquivos estáticos da pasta wwwroot: wwwroot/css/styles.css é servido como /css/styles.css
app.UseStaticFiles();
// 2. Bootstrap, compartilhado pelos exemplos: a pasta examples/common/bootstrap é servida em /bootstrap
app.UseStaticFiles(new StaticFileOptions
{
    FileProvider = new PhysicalFileProvider(Path.GetFullPath(Path.Combine(builder.Environment.ContentRootPath, "..", "common", "bootstrap"))),
    RequestPath = "/bootstrap",
});

app.MapControllers();
app.Run();

Vamos comentar este código:

  • linha 9: o serviço [HtmlEncoder] é o usado pelo [Razor] para escapar as expressões em [@]. Por padrão, ele deixa passar apenas os caracteres do alfabeto latino básico: é isso que codifica [é] como [&#xE9;] (e [€] como [&#x20AC;]). Substituímos esse serviço por um codificador que deixa passar todos os caracteres ([UnicodeRanges.All]). Os caracteres perigosos ([<], [>], [&], ["], [']) continuam escapados: a proteção contra injeção de HTML permanece intacta. Todos os exemplos seguintes, assim como o estudo de caso, incluem essa linha;
  • linha 14: um componente de middleware (veja o Capítulo 7) que serve os arquivos da pasta [wwwroot] do projeto: o arquivo [wwwroot/css/styles.css] é servido na URL [/css/styles.css]. Se o arquivo não existir, a requisição segue para os controllers;
  • linhas 16–19: um segundo serviço de arquivos estáticos. O framework CSS [Bootstrap] é comum a todos os exemplos: ele é armazenado uma única vez, na pasta [examples/common/bootstrap], e servido sob o prefixo [/bootstrap]. [PhysicalFileProvider] designa uma pasta do disco; [ContentRootPath] é a pasta do projeto. Assim, [examples/common/bootstrap/css/bootstrap.min.css] é servido na URL [/bootstrap/css/bootstrap.min.css]. O estudo de caso, por sua vez, coloca o [Bootstrap] em sua própria pasta, [wwwroot].

Vamos verificar:

curl -i http://localhost:5000/css/styles.css
HTTP/1.1 200 OK
Content-Length: 430
Content-Type: text/css

/* alguns ajustes sobre o Bootstrap */
body {
  background-color: #f5f7fa;
}

/* o rodapé do layout */
.footer {
  margin-top: 2rem;
  font-size: 0.85rem;
  color: #6c757d;
}

/* as mensagens de erro, na parte inferior da página, sobre um fundo rosa claro */
.error-area {
  margin-top: 1.5rem;
  padding: 0.75rem 1rem;
  background-color: #fdecef;
  border: 1px solid #f5c2c7;
  border-radius: 0.375rem;
  color: #842029;
}

O arquivo [Views/_ViewStart.cshtml]:

1
2
3
4
@* executado antes de cada view: todas as views usam o layout _Layout *@
@{
    Layout = "_Layout";
}
  • Linha 3: o arquivo [_ViewStart.cshtml] é executado antes de cada view de sua pasta e subpastas. Ele define a propriedade [Layout]: todas as views usam o template [_Layout], que é procurado na pasta da view e depois em [Views/Shared].

O arquivo [Views/_ViewImports.cshtml]:

1
2
3
@* os Tag Helpers do ASP.NET Core: tags HTML "enriquecidas", como <partial> *@
@addTagHelper *, Microsoft.AspNetCore.Mvc.TagHelpers
@using Example15.Controllers
  • Linha 2: ativa os Tag Helpers fornecidos pelo [ASP.NET Core]: tags ou atributos HTML processados pelo servidor. A tag [<partial>] é um exemplo disso. [*] significa “todos os Tag Helpers do assembly” [Microsoft.AspNetCore.Mvc.TagHelpers];
  • Linha 3: o tipo [Member] é declarado no namespace dos controllers.

O arquivo [Views/Shared/_Layout.cshtml]:

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  @* ViewData["Title"]: um valor definido pela view, lido pelo layout *@
  <title>@ViewData["Title"] - My site</title>
  <link rel="stylesheet" href="/bootstrap/css/bootstrap.min.css">
  <link rel="stylesheet" href="/css/styles.css">
</head>
<body>
  <div class="container py-3">
    <partial name="_Navbar" />
    @* a view solicitada pela action é inserida aqui *@
    @RenderBody()
    @* Context: a requisição atual (HttpContext), disponível em toda view *@
    <footer class="footer">Page [@Context.Request.Path] - © @DateTime.Now.Year</footer>
  </div>
</body>
</html>
  • linha 7: [ViewData] é um dicionário compartilhado por uma view e seu template (e pela action, que também pode armazenar valores nele). A view armazena nele seu título, e o template o exibe;
  • linhas 8–9: as folhas de estilo, servidas por [UseStaticFiles];
  • linha 13: inserção da view parcial [_Navbar], procurada na pasta da view e depois em [Views/Shared];
  • linha 15: o local onde o [Razor] insere a view solicitada pela action;
  • linha 17: [Context] é o objeto [HttpContext] da requisição atual (veja o Exemplo 05), acessível a qualquer view: o template exibe o caminho solicitado sem que cada action precise repassá-lo.

O arquivo [Views/Shared/_Navbar.cshtml]:

1
2
3
4
5
6
7
8
<nav class="navbar navbar-expand bg-light rounded mb-3 px-3">
  <span class="navbar-brand">My site</span>
  <div class="navbar-nav">
    <a class="nav-link" href="/">Home</a>
    <a class="nav-link" href="/team">Team</a>
    <a class="nav-link" href="/raw">Page without layout</a>
  </div>
</nav>

O arquivo [Views/Shared/_Card.cshtml]:

1
2
3
4
5
6
7
8
@* um "card" do Bootstrap; seu modelo: um Member (nome, papel) *@
@model Member
<div class="card">
  <div class="card-body">
    <h5 class="card-title">@Model.Name</h5>
    <p class="card-text">@Model.Role</p>
  </div>
</div>

Por convenção, o nome de uma view parcial ou de um template começa com [_]: não são páginas completas. A view parcial [_Card] tem seu próprio modelo (linha 2): um nome e um papel. O tipo [Member] é declarado no controller. O arquivo [Controllers/PagesController.cs]:

using Microsoft.AspNetCore.Mvc;

namespace Example15.Controllers;

public record Member(string Name, string Role);

public class PagesController : Controller
{
    [HttpGet("/")]
    public IActionResult Home()
    {
        return View();
    }

    [HttpGet("team")]
    public IActionResult Team()
    {
        List<Member> members =
        [
            new Member("Marie Pélissier", "Director"),
            new Member("Jacques Bromard", "Developer"),
            new Member("Philippe Jandot", "Graphic designer"),
        ];
        return View(members);
    }

    [HttpGet("raw")]
    public IActionResult Raw()
    {
        return View();
    }
}
  • linha 5: o tipo dos membros da equipe;
  • linha 12: a action [Home] não tem modelo: [View()] sem argumentos;
  • linhas 18–24: a action [Team] passa uma lista de membros.

A view parcial é usada de duas maneiras. O arquivo [Views/Pages/Home.cshtml]:

1
2
3
4
5
6
7
@{
    ViewData["Title"] = "Home";
}
<h1>Welcome</h1>
<p>This page only contains its own content: the header, the navigation
  bar and the footer come from the <code>_Layout.cshtml</code> layout.</p>
<partial name="_Card" model='new Member("A partial view", "inserted with a model built on the spot")' />
  • linha 2: a view coloca seu título em [ViewData], para o template;
  • Linha 7: o atributo [model] da tag [<partial>] fornece o modelo da view parcial: neste caso, um objeto criado na hora. É uma expressão [C#]: ela é delimitada por apóstrofos para que seja possível usar aspas dentro dela.

O arquivo [Views/Pages/Team.cshtml]:

@model List<Member>
@{
    ViewData["Title"] = "Our team";
}
<h1>Our team</h1>
<div class="row g-3">
  @foreach (var member in Model)
  {
    <div class="col-md-4">
      @* a partial view recebe o membro atual como modelo *@
      <partial name="_Card" model="member" />
    </div>
  }
</div>
  • Linha 11: a view parcial recebe a iteração atual do laço como modelo.

O arquivo [Views/Pages/Raw.cshtml]:

@* Layout = null: esta view não usa o layout, é uma página completa *@
@{
    Layout = null;
}
<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Raw page</title>
</head>
<body>
  <p>This page does not use the layout: no Bootstrap, no navigation bar.</p>
  <p><a href="/">Back to home</a></p>
</body>
</html>
  • Linha 3: definir [Layout] como [null] em uma view cancela a seleção feita por [_ViewStart.cshtml]: a view [Raw] é uma página HTML completa. Também seria possível especificar outro template ([Layout = "_Other"]).

As páginas resultantes, nas URLs http://localhost:5000/, http://localhost:5000/team, e http://localhost:5000/raw:

Image

Image

Image

O template, as views parciais e o [ViewData] são exatamente o que o estudo de caso usa: um template [_Layout.cshtml], views parciais para a barra de navegação, as mensagens e as janelas de confirmação.

4.4. Exemplo 16: helpers

Uma view costuma precisar de pequenas funções de formatação: formatar uma data ou um preço, colocar um texto em maiúsculas, criar um badge HTML... Com o [Razor], são simples métodos [C#], chamados dentro de uma expressão [@]. O [ASP.NET Core] também oferece os Tag Helpers: código [C#] que atua sobre uma tag HTML no momento em que a página é renderizada.

O arquivo [Helpers/Formats.cs]:

using System.Globalization;
using System.Text.Encodings.Web;
using Microsoft.AspNetCore.Html;

namespace Example16.Helpers;

// funções C# comuns, chamáveis a partir das views: @Formats.Money(...)
public static class Formats
{
    // "keyboard" -> "KEYBOARD"
    public static string Uppercase(string? text) => (text ?? "").ToUpperInvariant();

    // um valor monetário em uma moeda, no formato do idioma atual (CultureInfo.CurrentCulture)
    // "C" = moeda; o objeto NumberFormatInfo define o símbolo da moeda
    public static string Money(decimal amount, string currency = "EUR")
    {
        var format = (NumberFormatInfo)CultureInfo.CurrentCulture.NumberFormat.Clone();
        format.CurrencySymbol = currency == "USD" ? "$" : "€";
        return amount.ToString("C", format);
    }

    // uma data por extenso, no idioma atual: "Wednesday, September 23, 2026"
    public static string Date(DateTime when) => when.ToString("D", CultureInfo.CurrentCulture);

    // um helper que constrói HTML: ele retorna um IHtmlContent, que o Razor não escapa.
    // Cabe então ao helper escapar os dados que insere (HtmlEncoder)
    public static IHtmlContent Badge(int stock)
    {
        var cssClass = stock > 0 ? "text-bg-success" : "text-bg-danger";
        var text = HtmlEncoder.Default.Encode(stock > 0 ? $"{stock} in stock" : "sold out");
        return new HtmlString($"<span class=\"badge {cssClass}\">{text}</span>");
    }
}

Vamos detalhar este código:

  • linha 8: uma classe estática — seus métodos são chamados sem criar um objeto, [Formats.Uppercase(...)];
  • linha 11: conversão para maiúsculas. [ToUpperInvariant] é independente do idioma do usuário;
  • linhas 15–19: um valor monetário. O formato ["C"] ([currency]) formata um valor de acordo com a localidade atual ([CultureInfo.CurrentCulture]): separador decimal, separador de milhares e posição do símbolo da moeda. As regras da localidade são copiadas ([Clone]) para alterar o símbolo da moeda;
  • linha 23: uma data escrita por extenso (formato ["D"]), no idioma da cultura atual;
  • linhas 27–31: um helper que gera HTML. A saída de uma expressão [@] é escapada, a menos que seja um [IHtmlContent]: HTML pré-gerado. [HtmlString] é a implementação mais simples disso. O helper deve então escapar por conta própria os dados que insere em seu HTML ([HtmlEncoder.Default.Encode]).

O arquivo [TagHelpers/ActiveTagHelper.cs]:

using System.Text.Encodings.Web;
using Microsoft.AspNetCore.Mvc.TagHelpers;
using Microsoft.AspNetCore.Razor.TagHelpers;

namespace Example16.TagHelpers;

// um Tag Helper: aplica-se às tags <a> que carregam o atributo "active-path"
// <a href="/products" active-path="/products"> recebe a classe "active" se a
// página atual estiver sob esse caminho
[HtmlTargetElement("a", Attributes = "active-path")]
public class ActiveTagHelper(IHttpContextAccessor accessor) : TagHelper
{
    // o valor do atributo active-path="..."
    public string ActivePath { get; set; } = "";

    public override void Process(TagHelperContext context, TagHelperOutput output)
    {
        var path = accessor.HttpContext?.Request.Path.Value ?? "/";
        var isActive = ActivePath == "/" ? path == "/" : path.StartsWith(ActivePath, StringComparison.Ordinal);
        if (isActive)
        {
            output.AddClass("active", HtmlEncoder.Default); // adiciona a classe ao atributo class
        }
    }
}

Vamos detalhar este código:

  • linha 10: o Tag Helper se aplica às tags [<a>] que têm o atributo [active-path];
  • linha 11: um Tag Helper deriva da classe [TagHelper]. Ele é um serviço: recebe por injeção um [IHttpContextAccessor], que dá acesso à requisição atual;
  • linha 14: o valor do atributo [active-path="..."] é atribuído à propriedade de mesmo nome ([ActivePath]);
  • Linhas 16–22: o método [Process] é chamado para cada tag relevante. Se o caminho da página começa com o valor do atributo, a classe CSS [active] é adicionada à tag ([AddClass]). O próprio atributo [active-path] não aparece na página gerada: o Tag Helper o consumiu.

O arquivo [Program.cs]:

using System.Globalization;
using System.Text.Encodings.Web;
using System.Text.Unicode;
using Microsoft.Extensions.FileProviders;

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddControllersWithViews();
builder.Services.AddSingleton(HtmlEncoder.Create(UnicodeRanges.All));
// IHttpContextAccessor: dá acesso à requisição atual (usado por ActiveTagHelper)
builder.Services.AddHttpContextAccessor();

var app = builder.Build();

// um middleware: o idioma de formatação vem do parâmetro ?lang=fr da URL
app.Use(async (context, next) =>
{
    var language = context.Request.Query["lang"] == "fr" ? "fr-FR" : "en-US";
    CultureInfo.CurrentCulture = new CultureInfo(language);
    await next(context); // passa a vez para o próximo middleware
});

app.UseStaticFiles();
app.UseStaticFiles(new StaticFileOptions
{
    FileProvider = new PhysicalFileProvider(Path.GetFullPath(Path.Combine(builder.Environment.ContentRootPath, "..", "common", "bootstrap"))),
    RequestPath = "/bootstrap",
});

app.MapControllers();
app.Run();
  • linha 10: registra o serviço [IHttpContextAccessor], usado pelo Tag Helper;
  • linhas 15–19: middleware escrito diretamente em [Program.cs], executado a cada requisição. Ele seleciona a cultura com base no parâmetro [lang] da URL e depois passa o controle ao middleware seguinte ([next]). É uma forma simples de testar; o próximo capítulo tratará disso melhor.

O arquivo [Views/_ViewImports.cshtml]:

1
2
3
4
5
@addTagHelper *, Microsoft.AspNetCore.Mvc.TagHelpers
@* nossos próprios Tag Helpers, os do assembly Example16 *@
@addTagHelper *, Example16
@using Example16.Helpers
@using Example16.Controllers
  • Linha 3: ativamos os Tag Helpers para o nosso próprio projeto (o assembly [Example16]);
  • linha 4: as views podem escrever [Formats.Money(...)].

O arquivo [Views/Shared/_Navbar.cshtml]:

<nav class="navbar navbar-expand bg-light rounded mb-3 px-3">
  <span class="navbar-brand">Helpers</span>
  <div class="navbar-nav">
    @* 1. uma condição escrita na view *@
    <a class="nav-link @(Context.Request.Path == "/" ? "active" : "")" href="/">Home</a>
    @* 2. nosso Tag Helper: o atributo active-path="..." *@
    <a class="nav-link" href="/products" active-path="/products">Products</a>
    @* 3. um Tag Helper do ASP.NET: asp-action constrói a URL da action *@
    <a class="nav-link" asp-controller="Pages" asp-action="Products" asp-route-lang="fr">Produits (fr)</a>
  </div>
</nav>
  • Linhas 4–5: primeira forma de destacar o link da página atual: uma condição escrita na view;
  • linha 7: segunda forma, mais concisa: nosso Tag Helper. É a usada no estudo de caso;
  • linha 9: um Tag Helper do [ASP.NET Core]. Os atributos [asp-controller] e [asp-action] designam uma action; o Tag Helper calcula sua URL com base nas rotas (aqui, [/products]) e a escreve no atributo [href]. [asp-route-lang="fr"] adiciona um parâmetro, que é colocado na URL ([?lang=fr]) já que a rota não contém um parâmetro [lang]. Se a URL da action for alterada, o link a acompanha.

O código HTML da barra de navegação, da URL até [/products]:

1
2
3
4
5
6
7
8
<nav class="navbar navbar-expand bg-light rounded mb-3 px-3">
  <span class="navbar-brand">Helpers</span>
  <div class="navbar-nav">
    <a class="nav-link " href="/">Home</a>
    <a class="nav-link active" href="/products">Products</a>
    <a class="nav-link" href="/products?lang=fr">Produits (fr)</a>
  </div>
</nav>

O arquivo [Views/Pages/Products.cshtml]:

@model List<Product>
@{
    ViewData["Title"] = "Products";
}
<h1>Products</h1>
<table class="table table-sm w-auto">
  <thead><tr><th>Product</th><th>Price</th><th>Price in dollars</th><th>Stock</th></tr></thead>
  <tbody>
    @foreach (var product in Model)
    {
      <tr>
        <td>@Formats.Uppercase(product.Name)</td>
        <td>@Formats.Money(product.Price)</td>
        <td>@Formats.Money(product.Price, "USD")</td>
        <td>@Formats.Badge(product.Stock)</td>
      </tr>
    }
  </tbody>
</table>
  • Linhas 12–15: os helpers são chamados dentro de expressões [@]. [Badge] retorna HTML, inserido sem escape.

As páginas resultantes, em inglês (http://localhost:5000/, http://localhost:5000/products) e depois em francês (http://localhost:5000/products?lang=fr):

Image

Image

Image

Os preços mudam de formato conforme o idioma: [1 149,90 €] em francês, [€1,149.90] em inglês.

4.5. Exemplo 17: um formulário GET

Um formulário HTML enviado pelo método GET coloca seus campos na URL. É o método apropriado para uma pesquisa: ele não modifica nada, e a URL resultante pode ser salva nos favoritos ou compartilhada. O estudo de caso o utiliza para selecionar um médico e uma data.

O arquivo [Models/Book.cs]:

1
2
3
4
5
6
namespace Example17.Models;

public record Book(string Title, string Author, string Genre);

// o view model: a entrada (para exibi-la novamente), os gêneros, os resultados
public record SearchModel(string Keyword, string Genre, string[] Genres, List<Book> Results);
  • Linha 6: o modelo da view contém os valores digitados ([Keyword], [Genre]), para que o formulário possa exibi-los novamente, junto com a lista de gêneros e os resultados.

O arquivo [Controllers/BooksController.cs]:

using Example17.Models;
using Microsoft.AspNetCore.Mvc;

namespace Example17.Controllers;

public class BooksController : Controller
{
    private static readonly List<Book> Books =
    [
        new Book("Le Rouge et le Noir", "Stendhal", "novel"),
        new Book("Les Fleurs du mal", "Baudelaire", "poetry"),
        new Book("Madame Bovary", "Flaubert", "novel"),
        new Book("Alcools", "Apollinaire", "poetry"),
        new Book("Le Cid", "Corneille", "drama"),
    ];

    private static readonly string[] Genres = ["novel", "poetry", "drama"];

    // GET / e GET /search?keyword=...&genre=...: o formulário E seus resultados
    [HttpGet("/")]
    [HttpGet("search")]
    public IActionResult Search(string? keyword, string? genre)
    {
        var word = (keyword ?? "").Trim().ToLower();
        var results = Books
            .Where(b => word == "" || b.Title.ToLower().Contains(word) || b.Author.ToLower().Contains(word))
            .Where(b => string.IsNullOrEmpty(genre) || b.Genre == genre)
            .ToList();
        return View(new SearchModel(keyword ?? "", genre ?? "", Genres, results));
    }
}
  • linhas 8–14: os livros, em memória;
  • linhas 20–21: dois atributos de rota: a action processa [GET /] e [GET /search];
  • Linha 22: os parâmetros [keyword] e [genre] são vinculados aos parâmetros de mesmo nome na URL. Na primeira visita, o formulário ainda não foi enviado: seus valores são [null];
  • linhas 25–28: filtragem, com [LINQ]. Uma palavra-chave vazia ou uma categoria vazia não filtra nada;
  • linha 29: o modelo da view.

O arquivo [Views/Books/Search.cshtml]:

@model SearchModel
<h1 class="h3">Book search</h1>
@* method="get": os campos são enviados na URL (?keyword=...&genre=...) *@
<form method="get" action="/search" class="row g-2 align-items-end mb-3">
  <div class="col-auto">
    <label class="form-label" for="keyword">Title or author</label>
    @* value="@Model.Keyword": o campo exibe novamente o que foi digitado *@
    <input class="form-control" id="keyword" name="keyword" value="@Model.Keyword">
  </div>
  <div class="col-auto">
    <label class="form-label" for="genre">Genre</label>
    <select class="form-select" id="genre" name="genre">
      <option value="">(all)</option>
      @foreach (var genre in Model.Genres)
      {
        @* um atributo booleano: escrito se a condição for verdadeira, omitido caso contrário *@
        <option value="@genre" selected="@(genre == Model.Genre)">@genre</option>
      }
    </select>
  </div>
  <div class="col-auto">
    <button class="btn btn-primary" type="submit">Search</button>
  </div>
</form>
<p>@Model.Results.Count book(s) found.</p>
<ul>
  @foreach (var book in Model.Results)
  {
    <li><i>@book.Title</i>, @book.Author (@book.Genre)</li>
  }
</ul>
  • linha 4: [method="get"] e [action="/search"]: o envio do formulário é uma requisição [GET /search?keyword=...&genre=...]. Os nomes dos parâmetros são o atributo [name] de cada campo;
  • Linha 8: o atributo [value] exibe novamente o valor digitado;
  • linha 17: na lista suspensa, a opção correspondente ao gênero selecionado recebe o atributo [selected]. O [Razor] trata os atributos booleanos de forma específica: se o valor é [true], ele escreve [selected="selected"]; se é [false], ele não escreve o atributo. É exatamente o que o HTML exige, pois a simples presença do atributo [selected] basta para selecionar a opção.

Na primeira exibição (http://localhost:5000/) e depois de uma pesquisa:

Image

Image

A barra de endereços mostra os parâmetros enviados. Os caracteres acentuados e os espaços são codificados ali ([%C3%A9]...): é a codificação de URL, que o [ASP.NET Core] decodifica antes do binding do modelo.

4.6. Exemplo 18: campos de formulário

O Exemplo 18 reúne todos os tipos de campos HTML: texto, senha, data, botões de opção, caixas de seleção, lista suspensa, lista de seleção múltipla, área de texto e campo oculto. Ele mostra como o servidor os recebe e como a view os exibe.

O arquivo [Services/ListsService.cs]:

namespace Example18.Services;

public record Country(string Code, string Name);

// as listas oferecidas pelo formulário. Em uma aplicação real, elas
// viriam de um banco de dados: seriam lidas UMA vez, na inicialização,
// já que são as mesmas para todos os usuários
public class ListsService
{
    public string[] Titles { get; } = ["Mr", "Mme", "Melle"];

    public Country[] Countries { get; } =
    [
        new Country("fr", "France"),
        new Country("be", "Belgium"),
        new Country("ch", "Switzerland"),
        new Country("ca", "Canada"),
    ];

    public string[] Hobbies { get; } = ["reading", "music", "sport", "cinema"];

    public string[] Languages { get; } = ["French", "English", "Spanish", "German"];
}

As listas oferecidas pelo formulário são fornecidas por um serviço. São as mesmas para todos os usuários: um serviço instanciado uma única vez (um singleton; veja o Capítulo 6) é o lugar natural para armazená-las. Ele é registrado em [Program.cs]:

using System.Text.Encodings.Web;
using System.Text.Unicode;
using Example18.Services;
using Microsoft.Extensions.FileProviders;

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddControllersWithViews();
// o Razor escreve os caracteres acentuados como estão (e não "&#xE9;");
// < > & " ' continuam escapados
builder.Services.AddSingleton(HtmlEncoder.Create(UnicodeRanges.All));
// as listas do formulário: as mesmas para todos, um único objeto (singleton)
builder.Services.AddSingleton<ListsService>();

var app = builder.Build();

// 1. os arquivos estáticos da pasta wwwroot: wwwroot/css/styles.css é servido como /css/styles.css
app.UseStaticFiles();
// 2. Bootstrap, compartilhado pelos exemplos: a pasta examples/common/bootstrap é servida em /bootstrap
app.UseStaticFiles(new StaticFileOptions
{
    FileProvider = new PhysicalFileProvider(Path.GetFullPath(Path.Combine(builder.Environment.ContentRootPath, "..", "common", "bootstrap"))),
    RequestPath = "/bootstrap",
});

app.MapControllers();
app.Run();
  • linha 12: uma única instância de [ListsService], compartilhada por todas as requisições.

O arquivo [Models/Input.cs]:

namespace Example18.Models;

// o que o usuário digitou: o model binding preenche cada propriedade
// com o campo de mesmo nome (os arrays recebem todos os valores marcados)
public class Input
{
    public string? Name { get; set; }
    public string? Password { get; set; }
    public string? Comment { get; set; }
    public string? Title { get; set; }
    public string[] Hobbies { get; set; } = [];
    public string? Country { get; set; }
    public string[] Languages { get; set; } = [];
    public DateOnly? BirthDate { get; set; }
    public string? Token { get; set; }
}

// uma opção de uma lista e seu estado (marcada / selecionada)
public record Option(string Value, string Label, bool Chosen);

// o view model
public class FormModel
{
    public required Input Input { get; init; }
    public required List<Option> Titles { get; init; }
    public required List<Option> Hobbies { get; init; }
    public required List<Option> Countries { get; init; }
    public required List<Option> Languages { get; init; }
    public string? Received { get; init; } // o que o servidor recebeu, para exibi-lo
}

Vamos comentar este código:

  • Linhas 5–15: os dados digitados. O binding do modelo preenche cada propriedade com o campo de mesmo nome. As caixas de seleção e a lista suspensa são arrays ([string[]]): elas recebem todos os valores enviados (veja o Exemplo 10). A data de nascimento é convertida em [DateOnly];
  • linha 19: uma opção de uma lista: seu valor, seu rótulo e um booleano indicando se ela está marcada ou selecionada;
  • linhas 22–29: o modelo da view. A palavra-chave [required] exige que a propriedade seja informada quando o objeto é criado; [init] impede que ela seja modificada depois.

O arquivo [Controllers/FormController.cs]:

using Example18.Models;
using Example18.Services;
using Microsoft.AspNetCore.Mvc;

namespace Example18.Controllers;

[Route("form")]
public class FormController(ListsService lists) : Controller
{
    // GET: o formulário, com valores iniciais
    [HttpGet("")]
    public IActionResult Display()
    {
        var initial = new Input { Title = "Mme", Country = "fr", Languages = ["French"], Token = "A7X2" };
        return View("Form", Model(initial, null));
    }

    // POST: o model binding preenche [input]; exibimos o formulário novamente
    [HttpPost("")]
    public IActionResult Process(Input input)
    {
        // o que o navegador realmente enviou, campo a campo
        var received = string.Join("\n", Request.Form.Select(c => $"{c.Key} = [{string.Join(", ", c.Value.ToArray())}]"));
        return View("Form", Model(input, received));
    }

    // o view model: as listas, cada opção sendo marcada como marcada /
    // selecionada conforme a entrada. A view só precisará testar um booleano.
    private FormModel Model(Input input, string? received) => new()
    {
        Input = input,
        Titles = lists.Titles.Select(t => new Option(t, t, t == input.Title)).ToList(),
        Hobbies = lists.Hobbies.Select(h => new Option(h, h, input.Hobbies.Contains(h))).ToList(),
        Countries = lists.Countries.Select(c => new Option(c.Code, c.Name, c.Code == input.Country)).ToList(),
        Languages = lists.Languages.Select(l => new Option(l, l, input.Languages.Contains(l))).ToList(),
        Received = received,
    };
}

Vamos comentar este código:

  • linha 8: o serviço de listas é injetado;
  • linhas 11–15: [GET /form] exibe o formulário com valores iniciais;
  • linhas 19–24: [POST /form] recebe os dados digitados pelo usuário — preenchidos pelo binding do modelo — e redesenha o formulário. [Request.Form] também dá acesso aos campos tal como foram enviados: ele os converte em texto, uma linha por campo, para exibição;
  • linhas 29–36: o modelo da view. Para cada lista, a action calcula quais opções devem ser marcadas ou selecionadas: a view só precisará então testar um booleano.

O arquivo [Views/Form/Form.cshtml]:

@model FormModel
<h1 class="h3">A complete form</h1>
<form method="post" action="/form" style="max-width: 40rem">
  @* campo oculto: enviado com o formulário, mas invisível *@
  <input type="hidden" name="token" value="@Model.Input.Token">

  <div class="mb-2">
    <span class="form-label me-3">Title</span>
    @foreach (var title in Model.Titles)
    {
      @* radio buttons: mesmo [name], um único valor enviado *@
      <div class="form-check form-check-inline">
        <input class="form-check-input" type="radio" name="title" id="title-@title.Value"
               value="@title.Value" checked="@title.Chosen">
        <label class="form-check-label" for="title-@title.Value">@title.Label</label>
      </div>
    }
  </div>

  <div class="row g-2 mb-2">
    <div class="col">
      <label class="form-label" for="name">Name</label>
      <input class="form-control" type="text" id="name" name="name" value="@Model.Input.Name">
    </div>
    <div class="col">
      <label class="form-label" for="password">Password</label>
      @* uma senha NUNCA é reenviada na página *@
      <input class="form-control" type="password" id="password" name="password">
    </div>
    <div class="col">
      <label class="form-label" for="birthDate">Date of birth</label>
      @* um campo de data troca seus valores no formato yyyy-mm-dd *@
      <input class="form-control" type="date" id="birthDate" name="birthDate"
             value="@Model.Input.BirthDate?.ToString("yyyy-MM-dd")">
    </div>
  </div>

  <div class="mb-2">
    <span class="form-label me-3">Hobbies</span>
    @for (var i = 0; i < Model.Hobbies.Count; i++)
    {
      var hobby = Model.Hobbies[i];
      @* checkboxes: mesmo [name], vários valores possíveis *@
      <div class="form-check form-check-inline">
        <input class="form-check-input" type="checkbox" name="hobbies" id="hobby-@i"
               value="@hobby.Value" checked="@hobby.Chosen">
        <label class="form-check-label" for="hobby-@i">@hobby.Label</label>
      </div>
    }
  </div>

  <div class="row g-2 mb-2">
    <div class="col">
      <label class="form-label" for="country">Country</label>
      <select class="form-select" id="country" name="country">
        @foreach (var country in Model.Countries)
        {
          <option value="@country.Value" selected="@country.Chosen">@country.Label</option>
        }
      </select>
    </div>
    <div class="col">
      <label class="form-label" for="languages">Spoken languages</label>
      @* lista de seleção múltipla: vários valores possíveis *@
      <select class="form-select" id="languages" name="languages" multiple size="4">
        @foreach (var language in Model.Languages)
        {
          <option value="@language.Value" selected="@language.Chosen">@language.Label</option>
        }
      </select>
    </div>
  </div>

  <div class="mb-2">
    <label class="form-label" for="comment">Comment</label>
    @* uma área de texto: o valor fica ENTRE as tags *@
    <textarea class="form-control" id="comment" name="comment" rows="2">@Model.Input.Comment</textarea>
  </div>

  <button class="btn btn-primary" type="submit">Send</button>
</form>

@if (Model.Received is not null)
{
  <h2 class="h5 mt-3">What the server received</h2>
  <pre class="bg-light p-2 border">@Model.Received</pre>
}

Vamos comentar este código:

  • Linha 3: o formulário é enviado por POST: seus campos são incluídos no corpo da requisição;
  • Linha 5: um campo oculto é enviado com o formulário, mas não é exibido. Ele serve para repassar informações de uma página à seguinte (no estudo de caso, por exemplo, ele contém a versão de um registro). Atenção: o usuário pode modificá-lo;
  • Linhas 9–15: os botões de opção compartilham o mesmo [name]; apenas um pode ser selecionado, e apenas um valor é enviado. O atributo booleano [checked="@title.Chosen"] seleciona o botão (veja [selected], Exemplo 17);
  • linha 28: uma senha nunca é reenviada em uma página: o campo não tem atributo [value];
  • linhas 33–34: um campo de data. O navegador exibe a data no formato do usuário, mas sempre envia e recebe [yyyy-mm-dd];
  • linhas 40–46: caixas de seleção com o mesmo atributo [name]: cada caixa marcada envia seu valor; o parâmetro é, portanto, repetido;
  • linhas 55–60: uma lista suspensa. A opção selecionada tem o atributo [selected];
  • linha 65: o atributo [multiple] permite selecionar várias opções;
  • linha 77: o valor de um campo de texto fica entre suas tags, e não em um atributo [value];
  • Linhas 83–86: o que o servidor recebeu, exibido dentro de uma tag [<pre>], que preserva as quebras de linha.

O formulário inicial (http://localhost:5000/form) e, depois, após o envio:

Image

Image

Observe que o campo de texto exibiu novamente [Hello <b>everyone</b>] exatamente como foi digitado: graças ao escape das expressões [@], as tags digitadas não são interpretadas. A senha foi recebida, mas não é exibida. Com o [curl], podemos ver a diferença quando uma caixa de seleção está marcada:

curl -d "token=A7X2&title=Mr&name=Martin&hobbies=sport" http://localhost:5000/form
1
2
3
4
token = [A7X2]
title = [Mr]
name = [Martin]
hobbies = [sport]

e duas caixas marcadas:

curl -d "token=A7X2&title=Mr&name=Martin&hobbies=sport&hobbies=music" http://localhost:5000/form
1
2
3
4
token = [A7X2]
title = [Mr]
name = [Martin]
hobbies = [sport, music]

(apenas o conteúdo da tag [<pre>] da página é reproduzido, tal como exibido por um navegador). Uma caixa desmarcada não é enviada de forma alguma: [Request.Form] não contém o campo, e a propriedade [Hobbies] dos dados digitados mantém seu valor inicial — o array vazio.

4.7. Exemplo 19: validação de formulário

Um formulário inválido deve ser exibido novamente, mostrando os valores digitados e uma mensagem abaixo de cada campo com erro. O Exemplo 19 aplica a técnica do Exemplo 09 (validação feita pela action, usando [ModelState]) a um formulário de cadastro.

O arquivo [Models/RegistrationModel.cs]:

using System.ComponentModel.DataAnnotations;

namespace Example19.Models;

// os campos do formulário e suas restrições
public class RegistrationModel
{
    // remove os espaços supérfluos de uma entrada (o "setter" é chamado pelo model binding)
    private string? name;

    [Required(ErrorMessage = "The name is required.")]
    [MaxLength(20, ErrorMessage = "The name must not exceed 20 characters.")]
    public string? Name
    {
        get => name;
        set => name = value?.Trim();
    }

    [Required(ErrorMessage = "The email address is required.")]
    [EmailAddress(ErrorMessage = "Invalid email address.")]
    public string? Email { get; set; }

    // tudo o que vem de um formulário é uma string: "42" -> 42
    [Required(ErrorMessage = "The age is required.")]
    [Range(18, 120, ErrorMessage = "The age must be between 18 and 120 years.")]
    public int? Age { get; set; }

    [Required(ErrorMessage = "The password is required.")]
    [MinLength(6, ErrorMessage = "The password must have at least 6 characters.")]
    public string? Password { get; set; }

    // uma regra sobre DOIS campos: [Compare] compara com Password
    [Compare(nameof(Password), ErrorMessage = "The confirmation does not match the password.")]
    public string? Confirmation { get; set; }
}

// o view model: os valores a exibir novamente, os erros por campo
public class RegistrationForm
{
    public RegistrationModel Values { get; init; } = new();
    public Dictionary<string, string> Errors { get; init; } = new(StringComparer.OrdinalIgnoreCase);
    public bool Html5 { get; init; }
}

// o modelo da partial view _Field: um campo de entrada
public record FieldModel(string Name, string Label, string Type, string? Value, string? Error, string Attributes);

Vamos comentar este código:

  • Linhas 9–16: uma propriedade com um campo privado. Seu acessador [set]— chamado pelo binding do modelo — remove os espaços desnecessários da entrada: [" Martin "] torna-se ["Martin"]. Um nome formado apenas por espaços é convertido em [null] pelo próprio binding do modelo e [[Required]] o rejeita;
  • linha 12: [[MaxLength]] limita o comprimento de uma string, assim como [[StringLength]];
  • Linhas 25–26: a idade é convertida em um inteiro e depois validada;
  • linha 29: no mínimo 6 caracteres;
  • linha 33: a regra “a confirmação é igual à senha” envolve dois campos. O atributo [[Compare]] compara a propriedade que ele decora com outra propriedade, designada por seu nome ([nameof(Password)]: o nome da propriedade, verificado pelo compilador);
  • linhas 38–42: o modelo da view: os valores a serem exibidos novamente, os erros organizados por campo (um dicionário cujas chaves não diferenciam maiúsculas de minúsculas) e um booleano explicado mais adiante;
  • linha 46: a view parcial que exibe um campo.

O arquivo [Controllers/RegistrationController.cs]:

using Example19.Models;
using Microsoft.AspNetCore.Mvc;

namespace Example19.Controllers;

[Route("register")]
public class RegistrationController : Controller
{
    // ?html5=1: deixamos o navegador validar o formulário antes de enviá-lo
    [HttpGet("")]
    public IActionResult Display(bool html5)
    {
        return View("Registration", new RegistrationForm { Html5 = html5 });
    }

    [HttpPost("")]
    public IActionResult Register(RegistrationModel input, [FromQuery] bool html5)
    {
        if (!ModelState.IsValid)
        {
            // os erros por campo, para exibir cada mensagem sob o seu campo
            var errors = ModelState
                .Where(c => c.Value!.Errors.Count > 0)
                .ToDictionary(c => c.Key, c => c.Value!.Errors[0].ErrorMessage, StringComparer.OrdinalIgnoreCase);
            // exibimos o formulário NOVAMENTE: valores digitados (exceto as senhas),
            // e uma mensagem sob cada campo inválido
            input.Password = input.Confirmation = null;
            ViewData["Error"] = "The form contains errors.";
            return View("Registration", new RegistrationForm { Values = input, Errors = errors, Html5 = html5 });
        }
        return View("Welcome", input);
    }
}

Vamos comentar este código:

  • Linhas 11–13: o formulário vazio. O parâmetro [html5] será explicado mais adiante;
  • Linha 17: o binding do modelo preenche [input] com os campos do formulário e o valida. [[FromQuery]] obtém [html5] da URL;
  • Linhas 19–24: se houver erros, eles são organizados por campo. Um campo pode violar várias restrições: apenas a primeira mensagem de erro ([Errors[0]]) é mantida;
  • linhas 27–29: o formulário é exibido novamente: os valores digitados (exceto as senhas), os erros por campo e uma mensagem geral, armazenada em [ViewData] para o template;
  • linha 31: caso contrário, a página de boas-vindas, com os valores convertidos (a idade é um número, o nome foi limpo).

Um erro de conversão (uma idade [abc]) gera por padrão uma mensagem em inglês: [The value 'abc' is not valid for Age.] (veja o exemplo 08). O arquivo [Program.cs] a substitui:

using System.Text.Encodings.Web;
using System.Text.Unicode;
using Microsoft.Extensions.FileProviders;

var builder = WebApplication.CreateBuilder(args);
builder.Services.AddControllersWithViews(options =>
{
    // as mensagens dos erros de CONVERSÃO (p. ex. idade "abc"), substituindo as padrão
    var messages = options.ModelBindingMessageProvider;
    messages.SetAttemptedValueIsInvalidAccessor((value, field) => $"The value [{value}] is not valid.");
    messages.SetValueMustNotBeNullAccessor(field => "This field is required.");
});
// o Razor escreve os caracteres acentuados como estão (e não "&#xE9;");
// < > & " ' continuam escapados
builder.Services.AddSingleton(HtmlEncoder.Create(UnicodeRanges.All));

var app = builder.Build();

// 1. os arquivos estáticos da pasta wwwroot: wwwroot/css/styles.css é servido como /css/styles.css
app.UseStaticFiles();
// 2. Bootstrap, compartilhado pelos exemplos: a pasta examples/common/bootstrap é servida em /bootstrap
app.UseStaticFiles(new StaticFileOptions
{
    FileProvider = new PhysicalFileProvider(Path.GetFullPath(Path.Combine(builder.Environment.ContentRootPath, "..", "common", "bootstrap"))),
    RequestPath = "/bootstrap",
});

app.MapControllers();
app.Run();
  • Linhas 6–11: as mensagens de erro de binding do modelo são fornecidas pelo objeto [ModelBindingMessageProvider] das opções do MVC. Cada método de [Set...Accessor] substitui uma dessas mensagens por uma função que gera a mensagem. [SetAttemptedValueIsInvalidAccessor] trata um valor que não pode ser convertido; ela recebe o valor e o nome do campo. O estudo de caso substitui assim todas essas mensagens.

Os campos são todos construídos segundo o mesmo modelo: uma view parcial os centraliza. O arquivo [Views/Shared/_Field.cshtml]:

@* um campo de entrada; seu modelo: nome, rótulo, tipo, valor, erro e os
   atributos de validação HTML5 (required, maxlength...) *@
@model FieldModel
<div class="mb-2">
  <label class="form-label" for="@Model.Name">@Model.Label</label>
  <input class="form-control @(Model.Error is null ? "" : "is-invalid")" id="@Model.Name" name="@Model.Name"
         type="@Model.Type" value="@Model.Value" @Html.Raw(Model.Attributes)>
  @if (Model.Error is not null)
  {
    <div class="invalid-feedback">@Model.Error</div>
  }
</div>
  • linha 6: a classe [Bootstrap] [is-invalid] destaca em vermelho um campo inválido;
  • linha 7: os atributos de validação HTML5 são passados como parâmetros e inseridos sem escape ([Html.Raw]): eles são escritos pelo desenvolvedor, não digitados pelo usuário;
  • linha 10: a mensagem de erro, abaixo do campo (classe [Bootstrap] [invalid-feedback]).

O arquivo [Views/Registration/Registration.cshtml]:

@model RegistrationForm
@{
    // o erro de um campo, ou null
    string? Error(string field) => Model.Errors.GetValueOrDefault(field);
}
<h1 class="h3">Registration</h1>
@if (Model.Html5)
{
  <p>Browser validation <b>enabled</b> - <a href="/register">disable it</a></p>
}
else
{
  <p>Browser validation <b>disabled</b> - <a href="/register?html5=true">enable it</a></p>
}
@* novalidate: o navegador ignora os atributos required, min... e
   envia o formulário como está; somente o servidor valida *@
<form method="post" action="/register@(Model.Html5 ? "?html5=true" : "")" novalidate="@(!Model.Html5)">
  <partial name="_Field" model='new FieldModel("name", "Name", "text", Model.Values.Name, Error("name"), "required maxlength=\"20\"")' />
  <partial name="_Field" model='new FieldModel("email", "Email address", "email", Model.Values.Email, Error("email"), "required")' />
  <partial name="_Field" model='new FieldModel("age", "Age", "number", Model.Values.Age?.ToString(), Error("age"), "required min=\"18\" max=\"120\"")' />
  <partial name="_Field" model='new FieldModel("password", "Password", "password", null, Error("password"), "required minlength=\"6\"")' />
  <partial name="_Field" model='new FieldModel("confirmation", "Confirmation", "password", null, Error("confirmation"), "required")' />
  <button class="btn btn-primary" type="submit">Register</button>
</form>
  • linha 4: uma função local [C#], declarada no bloco [@{ }]: ela retorna o erro de um campo ou [null];
  • linha 17: o atributo booleano [novalidate] é definido quando [Html5] é falso;
  • Linhas 18–22: cada campo é uma inserção da view parcial, usando um modelo gerado na hora.

O arquivo [Views/Shared/_Layout.cshtml]:

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Registration</title>
  <link rel="stylesheet" href="/bootstrap/css/bootstrap.min.css">
  <link rel="stylesheet" href="/css/styles.css">
</head>
<body>
  <div class="container py-3" style="max-width: 36rem">
    @RenderBody()
    @* o erro global, na parte inferior da página, sobre um fundo rosa claro;
       ViewData["Error"] é definido pela action *@
    @if (ViewData["Error"] is string error)
    {
      <div class="error-area" role="alert">@error</div>
    }
  </div>
</body>
</html>
  • linhas 14–16: a mensagem global é exibida na parte inferior da página sobre um fundo rosa claro (classe [error-area] definida em [wwwroot/css/styles.css]), como no estudo de caso. [is string error] verifica o tipo do valor e o armazena em uma variável.

Vamos enviar o formulário (http://localhost:5000/register) com vários erros:

Image

depois preenchido corretamente (com espaços em volta do nome):

Image

E com uma idade não numérica, enviada por [curl] (o navegador a teria rejeitado em um campo [type="number"]):

curl -i -d "name=Martin&email=xx&age=abc" http://localhost:5000/register
HTTP/1.1 200 OK
Content-Type: text/html; charset=utf-8

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Registration</title>
  <link rel="stylesheet" href="/bootstrap/css/bootstrap.min.css">
  <link rel="stylesheet" href="/css/styles.css">
</head>
<body>
  <div class="container py-3" style="max-width: 36rem">
    <h1 class="h3">Registration</h1>
  <p>Browser validation <b>disabled</b> - <a href="/register?html5=true">enable it</a></p>
<form method="post" action="/register" novalidate="novalidate">
  <div class="mb-2">
  <label class="form-label" for="name">Name</label>
  <input class="form-control " id="name" name="name"
         type="text" value="Martin" required maxlength="20">
</div>

  <div class="mb-2">
  <label class="form-label" for="email">Email address</label>
  <input class="form-control is-invalid" id="email" name="email"
         type="email" value="xx" required>
    <div class="invalid-feedback">Invalid email address.</div>
</div>

  <div class="mb-2">
  <label class="form-label" for="age">Age</label>
  <input class="form-control is-invalid" id="age" name="age"
         type="number" required min="18" max="120">
    <div class="invalid-feedback">The value [abc] is not valid.</div>
</div>

  <div class="mb-2">
  <label class="form-label" for="password">Password</label>
  <input class="form-control is-invalid" id="password" name="password"
         type="password" required minlength="6">
    <div class="invalid-feedback">The password is required.</div>
</div>

  <div class="mb-2">
  <label class="form-label" for="confirmation">Confirmation</label>
  <input class="form-control " id="confirmation" name="confirmation"
         type="password" required>
</div>

  <button class="btn btn-primary" type="submit">Register</button>
</form>

      <div class="error-area" role="alert">The form contains errors.</div>
  </div>
</body>
</html>

4.7.1. Validação pelo navegador

Os atributos [required], [maxlength], [min], [max], [type="email"]... instruem o navegador a validar o formulário antes de enviá-lo: o usuário é notificado imediatamente por meio de um tooltip, sem nenhuma comunicação de ida e volta com o servidor. É o comportamento obtido ao clicar no link “enable it” (http://localhost:5000/register?html5=true), que remove o atributo [novalidate] do formulário.

Essa validação é uma conveniência, não uma medida de segurança: ela pode ser contornada simplesmente removendo o atributo [required] com as ferramentas de desenvolvedor do navegador ou enviando a requisição com [curl]. A validação no servidor continua sendo essencial. Por isso o exemplo desativa a validação do navegador por padrão: para demonstrar o funcionamento do servidor. O estudo de caso, por sua vez, mantém as duas: o atributo HTML5 por conveniência e a validação no servidor por segurança.

4.8. Exemplo 20: o padrão Post/Redirect/Get

Quando um formulário POST é enviado com sucesso, a action pode exibir uma página diretamente. O problema surge se o usuário atualizar essa página (tecla F5): o navegador reenvia o formulário e a operação é executada uma segunda vez (um pedido feito duas vezes, uma consulta marcada duas vezes...). O padrão Post / Redirect / Get (PRG) evita esse problema: uma action POST bem-sucedida não gera uma página; em vez disso, ela redireciona para uma página GET. Recarregar essa página apenas dispara outro GET, sem nenhum efeito.

Resta um detalhe: a página GET deve exibir uma mensagem (“a tarefa foi adicionada”), embora essa mensagem tenha sido gerada pela action POST em outra requisição. Para resolver isso, o [ASP.NET Core] fornece o [TempData]: um dicionário cujo conteúdo persiste até a próxima requisição e desaparece assim que é lido. É uma mensagem flash. Por padrão, o [TempData] é armazenado em um cookie, criptografado pelo servidor.

O arquivo [Services/TasksService.cs]:

namespace Example20.Services;

// a lista de tarefas, em memória, compartilhada por todos (singleton)
public class TasksService
{
    private readonly List<string> tasks = ["Read chapter 3"];

    public IReadOnlyList<string> List() => tasks;

    public void Add(string label) => tasks.Add(label);
}

O arquivo [Controllers/TasksController.cs]:

using Example20.Services;
using Microsoft.AspNetCore.Mvc;

namespace Example20.Controllers;

[Route("tasks")]
public class TasksController(TasksService tasks) : Controller
{
    // GET /tasks: a lista e o formulário de adição
    [HttpGet("")]
    public IActionResult Display()
    {
        return View("Tasks", tasks.List());
    }

    // POST /tasks: o padrão Post / Redirect / Get
    [HttpPost("")]
    public IActionResult Add(string? label)
    {
        var text = (label ?? "").Trim();
        if (text == "" || text.Length > 40)
        {
            // entrada inválida: exibimos a página novamente, sem redirecionamento
            ViewData["Label"] = label;
            ViewData["Error"] = "The label must have 1 to 40 characters.";
            return View("Tasks", tasks.List());
        }
        tasks.Add(text);
        // TempData: uma mensagem que sobreviverá ao redirecionamento, para a PRÓXIMA requisição
        TempData["Flash"] = $"The task [{text}] has been added.";
        // nenhuma página: um redirecionamento para a página GET
        return RedirectToAction(nameof(Display));
    }

    // POST /tasks/without-prg: o contraexemplo (uma página em resposta ao POST)
    [HttpPost("without-prg")]
    public IActionResult AddWithoutPrg(string? label)
    {
        tasks.Add(string.IsNullOrWhiteSpace(label) ? "(untitled)" : label.Trim());
        ViewData["WithoutPrg"] = true;
        return View("Tasks", tasks.List());
    }
}

Vamos detalhar este código:

  • linhas 11–13: a página de listagem;
  • linhas 21–26: uma entrada inválida: a página é recarregada (sem redirecionamento — a entrada e a mensagem de erro precisam ser mantidas);
  • linhas 28–32: uma entrada válida: a operação é executada, a mensagem é gravada como flash em [TempData] e, em seguida, ocorre um redirecionamento 302 para a action [Display]. [RedirectToAction] calcula a URL da action com base em sua rota (veja o Exemplo 04). [nameof(Display)] é o nome do método, validado pelo compilador;
  • linhas 36–41: o contraexemplo, para comparação.

O arquivo [Views/Tasks/Tasks.cshtml]:

@model IReadOnlyList<string>
<h1 class="h3">My tasks</h1>
<ol>
  @foreach (var task in Model)
  {
    <li>@task</li>
  }
</ol>
<form method="post" action="/tasks" class="d-flex gap-2">
  <input class="form-control" name="label" value="@ViewData["Label"]" placeholder="New task">
  <button class="btn btn-primary text-nowrap" type="submit">Add</button>
  @* formaction: este botão envia o MESMO formulário para outro endereço *@
  <button class="btn btn-outline-secondary text-nowrap" type="submit" formaction="/tasks/without-prg">Add without PRG</button>
</form>
@if (ViewData["WithoutPrg"] is true)
{
  <p class="text-danger mt-2">Page displayed in response to a POST: press F5 and the task will be added a second time.</p>
}
  • linha 13: o atributo [formaction] de um botão envia o formulário para um endereço diferente do especificado pelo atributo [action] do formulário. O formulário tem assim dois botões, que disparam duas actions diferentes. O estudo de caso usa essa abordagem em sua página de login.

O arquivo [Views/Shared/_Layout.cshtml]:

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Tasks</title>
  <link rel="stylesheet" href="/bootstrap/css/bootstrap.min.css">
  <link rel="stylesheet" href="/css/styles.css">
</head>
<body>
  <div class="container py-3" style="max-width: 36rem">
    @* a mensagem flash, no topo da página: LÊ-LA a remove de TempData *@
    @if (TempData["Flash"] is string flash)
    {
      <div class="alert alert-success" role="status">@flash</div>
    }
    @RenderBody()
    @if (ViewData["Error"] is string error)
    {
      <div class="error-area" role="alert">@error</div>
    }
  </div>
</body>
</html>

A mensagem flash é exibida na parte superior da página (linhas 12–14) e a mensagem de erro na parte inferior (linhas 17–19). Ler [TempData["Flash"]] marca o valor como consumido: ele é apagado ao final da requisição.

Veja o que o [curl] enxerga quando o formulário é enviado com sucesso. A opção [-c file] salva os cookies recebidos, [-b file] os envia de volta; [--data-urlencode] codifica os espaços e os acentos no campo:

curl -i -c cookies.txt -b cookies.txt --data-urlencode "label=Review ASP.NET" http://localhost:5000/tasks
1
2
3
4
HTTP/1.1 302 Found
Content-Length: 0
Location: /tasks
Set-Cookie: .AspNetCore.Mvc.CookieTempDataProvider=CfDJ8Mr17zLSwO9AhYlPOJdkD8mjtY...; path=/; samesite=lax; httponly

A resposta é um redirecionamento, com o cookie [.AspNetCore.Mvc.CookieTempDataProvider], que contém a mensagem flash criptografada (seu valor, muito longo, foi truncado). A requisição seguinte envia o cookie; a resposta o exclui (data de expiração no passado):

curl -i -c cookies.txt -b cookies.txt http://localhost:5000/tasks
HTTP/1.1 200 OK
Content-Type: text/html; charset=utf-8
Set-Cookie: .AspNetCore.Mvc.CookieTempDataProvider=; expires=Thu, 01 Jan 1970 00:00:00 GMT; path=/; samesite=lax; httponly

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Tasks</title>
  <link rel="stylesheet" href="/bootstrap/css/bootstrap.min.css">
  <link rel="stylesheet" href="/css/styles.css">
</head>
<body>
  <div class="container py-3" style="max-width: 36rem">
      <div class="alert alert-success" role="status">The task [Review ASP.NET] has been added.</div>
    <h1 class="h3">My tasks</h1>
<ol>
    <li>Read chapter 3</li>
    <li>Review ASP.NET</li>
</ol>
<form method="post" action="/tasks" class="d-flex gap-2">
  <input class="form-control" name="label" placeholder="New task">
  <button class="btn btn-primary text-nowrap" type="submit">Add</button>
  <button class="btn btn-outline-secondary text-nowrap" type="submit" formaction="/tasks/without-prg">Add without PRG</button>
</form>

  </div>
</body>
</html>

No navegador (http://localhost:5000/tasks), após adicionar uma tarefa:

Image

A barra de endereços exibe [/tasks]: é a página GET. Você pode recarregá-la sem risco; a mensagem desaparece. Uma entrada vazia:

Image

E o contraexemplo:

Image

Aqui, recarregar a página dispara um aviso do navegador (“Confirmar reenvio do formulário”) e depois adiciona a tarefa uma segunda vez. Todos os formulários POST do estudo de caso seguem o padrão PRG.

Uma regra simples orienta a escolha entre um link e um botão:

  • um link ([<a href>]) gera uma requisição GET. Uma requisição GET não deve modificar nada: navegadores, mecanismos de busca e antivírus podem seguir links por conta própria para preparar ou analisar uma página;
  • uma operação que modifica dados (adicionar, editar, excluir, sair) é um botão em um formulário POST.

O Exemplo 21 gerencia uma lista de contatos: é possível ver um contato clicando em um link e excluí-lo clicando em um botão, que abre uma janela de confirmação. Os arquivos deste exemplo:

21-links-buttons/
├── Controllers/
│   └── ContactsController.cs
├── Services/
│   └── ContactsService.cs
├── Views/
│   ├── Contacts/
│   │   ├── Details.cshtml
│   │   └── List.cshtml
│   ├── Shared/
│   │   ├── _Confirmation.cshtml
│   │   └── _Layout.cshtml
│   ├── _ViewImports.cshtml
│   └── _ViewStart.cshtml
├── wwwroot/
│   ├── css/
│   │   └── styles.css
│   └── js/
│       └── app.js
├── appsettings.json
├── Example21.csproj
└── Program.cs

O arquivo [Services/ContactsService.cs]:

namespace Example21.Services;

// um contato: um identificador, um nome, um telefone
public record Contact(int Id, string Name, string Phone);

// os contatos, em memória, compartilhados por todos (singleton)
public class ContactsService
{
    private readonly List<Contact> contacts =
    [
        new(1, "Marie Durand", "01 23 45 67 89"),
        new(2, "Paul Martin", "06 12 34 56 78"),
        new(3, "Philippe Jandot", "02 98 76 54 32"),
    ];
    private int lastId = 3;

    public IReadOnlyList<Contact> List() => contacts;

    // null se o contato não existir
    public Contact? Read(int id) => contacts.Find(c => c.Id == id);

    public Contact? Edit(int id, string name, string phone)
    {
        var index = contacts.FindIndex(c => c.Id == id);
        if (index < 0) return null;
        // um record é imutável: nós o substituímos por uma cópia modificada (com with)
        contacts[index] = contacts[index] with { Name = name, Phone = phone };
        return contacts[index];
    }

    public Contact Add(string name, string phone)
    {
        var contact = new Contact(++lastId, name, phone);
        contacts.Add(contact);
        return contact;
    }

    public Contact? Delete(int id)
    {
        var contact = Read(id);
        if (contact is not null) contacts.Remove(contact);
        return contact;
    }
}
  • Linha 4: um contato;
  • linha 20: [Find] retorna [null] se nenhum contato tiver esse ID;
  • linhas 22–28: um [record] é imutável: suas propriedades não são modificadas; em vez disso, ele é substituído por uma cópia modificada. A expressão [with { ... }] cria essa cópia;
  • linhas 31–35: [++lastId] incrementa o contador antes de usá-lo: os identificadores são 4, 5...

O arquivo [Controllers/ContactsController.cs]:

using Example21.Services;
using Microsoft.AspNetCore.Mvc;

namespace Example21.Controllers;

[Route("contacts")]
public class ContactsController(ContactsService contacts) : Controller
{
    // um LINK (<a href>): uma requisição GET, que não modifica nada
    [HttpGet("")]
    public IActionResult List()
    {
        return View(contacts.List());
    }

    [HttpGet("{id:int}")]
    public IActionResult Details(int id)
    {
        var contact = contacts.Read(id);
        return contact is null ? NotFound() : View(contact);
    }

    // um BOTÃO em um formulário POST: uma requisição que modifica dados
    [HttpPost("{id:int}")]
    public IActionResult Save(int id, string name, string phone)
    {
        var contact = contacts.Edit(id, name, phone);
        if (contact is null) return NotFound();
        TempData["Flash"] = $"The contact [{contact.Name}] has been edited.";
        return RedirectToAction(nameof(List));
    }

    // mesmo formulário, outro botão (atributo formaction): outra action
    [HttpPost("{id:int}/duplicate")]
    public IActionResult Duplicate(int id, string name, string phone)
    {
        var copy = contacts.Add($"{name} (copy)", phone);
        TempData["Flash"] = $"The contact [{copy.Name}] has been created.";
        return RedirectToAction(nameof(List));
    }

    [HttpPost("{id:int}/delete")]
    public IActionResult Delete(int id)
    {
        var contact = contacts.Delete(id);
        if (contact is null) return NotFound();
        TempData["Flash"] = $"The contact [{contact.Name}] has been deleted.";
        return RedirectToAction(nameof(List));
    }
}

Vamos comentar este código:

  • linhas 11–20: as duas páginas: a lista e a página de detalhes do contato. A restrição de rota [:int] (veja o Exemplo 02) aceita apenas um identificador inteiro; um contato inexistente resulta em um erro 404;
  • linhas 24–30: gravação de um registro, usando PRG;
  • linhas 34–39: duplicação, disparada por um segundo botão no mesmo formulário (atributo [formaction]);
  • linhas 42–48: exclusão, usando POST.

O arquivo [Views/Contacts/List.cshtml]:

@model IReadOnlyList<Contact>
<h1 class="h3">Contacts</h1>
<table class="table align-middle">
  <tbody>
    @foreach (var contact in Model)
    {
      <tr>
        <td>@contact.Name</td>
        <td>@contact.Phone</td>
        <td class="text-end">
          @* view: um link simples *@
          <a class="btn btn-sm btn-outline-primary" href="/contacts/@contact.Id">View</a>
          @* delete: um formulário POST, cujo envio será confirmado *@
          <form method="post" action="/contacts/@contact.Id/delete" class="d-inline"
                data-confirmation="Delete the contact @contact.Name?">
            <button class="btn btn-sm btn-outline-danger" type="submit">Delete</button>
          </form>
        </td>
      </tr>
    }
  </tbody>
</table>
  • linha 12: ver: um link, exibido como botão pelo [Bootstrap];
  • linhas 14–17: excluir: um pequeno formulário (POST), reduzido ao seu botão. O atributo [data-confirmation] contém a pergunta a ser feita antes do envio. Os atributos [data-*] são opcionais: o HTML os ignora, enquanto o [JavaScript] da página pode lê-los.

O arquivo [Views/Contacts/Details.cshtml]:

@model Contact
<h1 class="h3">Contact no. @Model.Id</h1>
<form method="post" action="/contacts/@Model.Id">
  <div class="mb-2">
    <label class="form-label" for="name">Name</label>
    <input class="form-control" id="name" name="name" value="@Model.Name">
  </div>
  <div class="mb-3">
    <label class="form-label" for="phone">Phone</label>
    <input class="form-control" id="phone" name="phone" value="@Model.Phone">
  </div>
  @* dois botões de envio para o mesmo formulário *@
  <button class="btn btn-primary" type="submit">Save</button>
  <button class="btn btn-outline-primary" type="submit" formaction="/contacts/@Model.Id/duplicate">Duplicate</button>
  <a class="btn btn-link" href="/contacts">Back to the list</a>
</form>
  • Linhas 13–14: dois botões de envio para o mesmo formulário.

4.9.1. A janela de confirmação

A caixa de diálogo do navegador ([window.confirm]) não pode ser formatada nem traduzida: seus botões permanecem no idioma do navegador. Ela é substituída por uma janela [Bootstrap], incorporada à página e oculta até ser necessária. O arquivo [Views/Shared/_Confirmation.cshtml]:

@* uma única janela para a página inteira, oculta (d-none) no início *@
<div id="confirmation-modal" class="d-none">
  <div class="modal-backdrop fade show"></div>
  <div class="modal fade show d-block" tabindex="-1" role="alertdialog" aria-modal="true">
    <div class="modal-dialog modal-dialog-centered">
      <div class="modal-content">
        <div class="modal-header">
          <h5 class="modal-title">Confirmation</h5>
        </div>
        <div class="modal-body">
          <p class="mb-0" id="confirmation-modal-message"></p>
        </div>
        <div class="modal-footer">
          <button type="button" class="btn btn-secondary" data-action="no">No, go back</button>
          <button type="button" class="btn btn-danger" data-action="yes">Yes, confirm</button>
        </div>
      </div>
    </div>
  </div>
</div>
  • linha 2: a classe [d-none] oculta a janela;
  • linha 3: o fundo cinza;
  • linha 11: a posição da pergunta;
  • linhas 14–15: os dois botões, identificados pelo atributo [data-action].

O arquivo [Views/Shared/_Layout.cshtml]:

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Contacts</title>
  <link rel="stylesheet" href="/bootstrap/css/bootstrap.min.css">
  <link rel="stylesheet" href="/css/styles.css">
</head>
<body>
  <div class="container py-3" style="max-width: 40rem">
    @if (TempData["Flash"] is string flash)
    {
      <div class="alert alert-success" role="status">@flash</div>
    }
    @RenderBody()
  </div>
  @* a janela de confirmação, presente em todas as páginas *@
  <partial name="_Confirmation" />
  @* o script, no final da página: os elementos que ele procura já existem *@
  <script src="/js/app.js"></script>
</body>
</html>
  • linha 18: a janela está presente em todas as páginas;
  • linha 20: o script é carregado no final da página; quando é executado, os elementos que ele procura já existem. Ele é servido pelo [UseStaticFiles] a partir de [wwwroot/js/app.js].

Um pequeno trecho de [JavaScript] liga os formulários à janela. O arquivo [wwwroot/js/app.js]:

// confirmação dos formulários que carregam o atributo data-confirmation="..."
// Sem JavaScript, esses formulários são simplesmente enviados sem confirmação.
(() => {
  const modal = document.getElementById('confirmation-modal');
  const message = document.getElementById('confirmation-modal-message');
  let pending = null; // o formulário a enviar se o usuário confirmar

  // 1. interceptamos o envio dos formulários a confirmar
  document.querySelectorAll('form[data-confirmation]').forEach((form) => {
    form.addEventListener('submit', (event) => {
      event.preventDefault(); // o envio é suspenso
      pending = form;
      message.textContent = form.dataset.confirmation;
      modal.classList.remove('d-none'); // a janela aparece
    });
  });

  // 2. os dois botões da janela
  modal.addEventListener('click', (event) => {
    const action = event.target.dataset.action;
    if (action === 'yes') {
      pending.submit(); // envio, SEM disparar novamente o evento 'submit'
    } else if (action === 'no') {
      modal.classList.add('d-none');
      pending = null;
    }
  });
})();
  • linha 3: o código é envolvido em uma função executada imediatamente, para evitar a criação de variáveis globais;
  • linhas 9–14: o envio de cada formulário que possui o atributo [data-confirmation] é interceptado. [preventDefault()] suspende o envio; o formulário é guardado, a pergunta é colocada na janela ([textContent], e não [innerHTML]: a pergunta é exibida como texto, nunca interpretada como HTML) e a janela é exibida;
  • Linhas 19–25: “Sim” envia o formulário guardado. O método [submit()] de um formulário o envia sem disparar o evento [submit]: não há nova solicitação de confirmação. “Não” oculta a janela.

Se o [JavaScript] estiver desativado, os formulários simplesmente são enviados sem confirmação: a aplicação continua funcionando. É o princípio do aprimoramento progressivo: o [JavaScript] acrescenta conveniência, mas não é essencial. O estudo de caso segue esse princípio (seu script, [wwwroot/js/app.js], acrescenta o tratamento do teclado: a tecla Esc e o foco). As páginas resultantes, geradas a partir de http://localhost:5000/contacts: a lista, a solicitação de confirmação, a lista após a exclusão e o perfil de um contato:

Image

Image

Image

Image

Por fim, verificamos que a exclusão não pode ser disparada por uma requisição GET:

curl -i http://localhost:5000/contacts/2/delete
1
2
3
HTTP/1.1 405 Method Not Allowed
Content-Length: 0
Allow: POST

O caminho existe, mas não para o método GET: o [ASP.NET Core] retorna [405 Method Not Allowed] e o cabeçalho [Allow] indica o método aceito. Com POST:

curl -i -X POST http://localhost:5000/contacts/2/delete
1
2
3
4
HTTP/1.1 302 Found
Content-Length: 0
Location: /contacts
Set-Cookie: .AspNetCore.Mvc.CookieTempDataProvider=CfDJ8Mr17zLSwO9AhYlPOJdkD8nJg8...; path=/; samesite=lax; httponly